Installation

This guide is based on the latest SFRA code and the RefArchGlobal reference site. If your SFCC setup differs or if you are using an alternate setup, some steps may vary, but the overall installation approach remains the same.

Step-by-Step Installation

1. Install Client-Side Dependencies and Build Assets

This step is required only if you are using SFRA and plan to use the int_dqe_sfra cartridge. If you are not using SFRA or the int_dqe_sfra cartridge, this step can be skipped.

To complete this step:

1. Install npm dependencies by running the following command:

   npm install

2. Open the package.json file and modify the paths.base property to point to your local SFRA directory.

3. Run the following commands to compile JavaScript and SCSS. This will create the client-side assets:

   npm run compile:js && npm run compile:scss

2. Upload the Cartridges

Once the dependencies are installed and client-side assets are built, upload the cartridges to your SFCC instance.

To upload the cartridges:

• Upload the cartridges folder to the WebDAV location for your sandbox using CyberDuck or any other WebDAV client.
• Alternatively, you can use B2C Commerce UX Studio or the Prophet Debugger extension for VS Code.

For further instructions on uploading cartridges to SFCC, refer to the official SFCC documentation.

3. Register the Cartridge with Individual SFCC Sites

To enable the DQE integration for your storefront, register the cartridge in SFCC Business Manager.

To register the cartridge:

1. Navigate to Administration > Sites > Manage Sites in SFCC Business Manager.
2. Click the Site Name for the storefront site where you want to add DQE engagement functionality.
3. Select the Settings tab.

4. Add the following to the Effective Cartridge Path:

   • If you are using SFRA, add:

     int_dqe_sfra:int_dqe:

   • If you are not using SFRA, add only:

     :int_dqe:

   For an SFRA-based Site Path, it should look like this:

   int_dqe_sfra:int_dqe:app_storefront_base

   

5. Click Apply.
6. Repeat steps 2 to 5 for each storefront site where DQE Engagement will be implemented.

Registering the BM Cartridge Globally in SFCC

To use the DQE Business Manager (BM) extension, register the BM cartridge with the Business Manager site.

To register the BM cartridge globally:

1. Go to Administration > Sites > Manage Sites in Business Manager.
2. Click the Manage the Business Manager site link for the site where you want to register the BM cartridge.
3. In the Effective Cartridge Path section, add bm_dqe: to the list of cartridges.
4. Click Apply to save the changes and register the BM cartridge globally.

Importing Metadata and Services in SFCC

To integrate DQE metadata and services into your Salesforce Commerce Cloud (SFCC) instance, import the necessary configurations as described below.

1. Navigate to Site Development

   Go to Administration > Site Development > Site Import & Export in SFCC Business Manager.

2. Prepare Metadata Files

   All metadata is stored in the data/site_template folder.

   • The data/site_template folder contains sample DQE code mapping and validation configurations for SFRA sites, including RefArch and RefArchGlobal.
   • If you want to change the site, go to data/site_template/sites and rename the folder to match your site ID.
   • To remove sample configurations, open data/site_template/sites and delete all folders and their contents.

3. Archive Metadata Folder

   Archive the data/site_template folder from the repository and prepare it for upload.

4. Upload Archive

   In the Upload Archive section of the Site Import & Export page, select the archived data/site_template folder and click Select Upload.

5. Reload Page and Select Site Template

   After the page reloads, choose the site_template radio button to confirm that you are importing the correct metadata.

6. Import

   Click Import to import the DQE metadata and services into your SFCC instance.

Importing Metadata, Services, and Custom Objects in SFCC

Depending on your Salesforce Commerce Cloud (SFCC) environment, you can import metadata, services, and custom objects separately.

1. Importing Metadata

Metadata files are stored in the data/site_template/meta folder and should be uploaded through Business Manager.

Steps:

1. Navigate to BM > Administration > Site Development > Import & Export.
2. Upload the XML metadata files from the data/site_template/meta folder.
3. After uploading, click Import Meta Data to import the metadata files.

2. Importing Services

The data/site_template/services.xml file contains services that can be imported separately.

Steps:

1. Navigate to BM > Administration > Operations > Import & Export.
2. Upload the services.xml file located in data/site_template.
3. After uploading, click Import Services to import the services.

3. Importing Custom Objects

The custom object definitions for each site are located in data/site_template/sites/[site_id]/custom-objects/[custom_object_type].xml.

Steps:

1. Navigate to Merchant Tools > Custom Objects > Import & Export in Business Manager.
2. Upload the XML custom object files located in data/site_template/sites/[site_id]/custom-objects/.
3. After uploading, click Import Custom Objects to import the custom objects.

Cartridge Metadata After Import

After importing the metadata, services, and custom objects, the following attributes, definitions, and services should appear in the system.

System Object Definitions

• Site Preferences: DQE group with attributes. Specific attributes are listed in the relevant documentation section.

Custom Object Definitions and Sample Mapping for Sites

• dqeAddressValidationConfigs
• dqeEmailValidationConfigs
• dqePhoneValidationConfigs

Services

• dqe.http.address.suggestions.complete
• dqe.http.address.suggestions.search
• dqe.http.address.validate
• dqe.http.email.validate
• dqe.http.phone.validate

Granting BM Extension Access

By default, access to the DQE Business Manager modules is not granted to any BM users. To provide access, follow these steps:

1. Go to Administration > Organization > Roles in SFCC Business Manager.
2. Select the user role that you want to grant access to.
3. Go to the Business Manager Modules tab.
4. Select the Sites Context and either select all sites or only the desired sites.
5. Check the modules from the DQE section.
6. Click Update to save the changes.