Salesforce Commerce Cloud - Installation

This guide is based on the latest SFRA code and the RefArchGlobal reference site. If your SFCC setup differs or you're 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, which 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, the next step is to 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, you need to register the cartridge in SFCC Business Manager.

To register the cartridge:

1. Navigate to Administration > Sites > Manage Sites in the SFCC Business Manager.

2. Click on 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 – 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, you must register the BM cartridge with the Business Manager site. Follow these steps to ensure the cartridge is properly registered.

Steps to Register the BM Cartridge Globally:

1. Navigate to SFCC Business Manager:

   • Go to Administration > Sites > Manage Sites in the Business Manager.

2. Access the Business Manager Settings:

   • Click on the Manage the Business Manager site link for the site where you want to register the BM cartridge.

3. Add BM Cartridge to Effective Cartridge Path:

   • In the Effective Cartridge Path section, add bm_dqe: to the list of cartridges.

4. Apply the Changes:

   • 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, follow the steps below to import the necessary configurations.

Steps to Import DQE Metadata and Services:

1. Navigate to Site Development:

   • Go to Administration > Site Development > Site Import & Export in the 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 (RefArch and RefArchGlobal).
     • If you wish to change the site, navigate to data/site_template/sites, and change the folder name to match the ID of your site.
     • To remove the sample configurations, simply 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 (which contains the necessary files) 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. Press Import Button:

   • Finally, press the Import button 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, it is possible to import metadata, services, and custom objects separately. Follow the instructions below for each section.

1. Importing Metadata

Metadata files are stored in the data/site_template/meta folder and should be uploaded through the 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 will be listed in the relevant document section).

Custom Object Definitions and Samples of 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 the 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 just the desired sites.
5. Check the modules from the “DQE” section.
6. Click Update to save the changes.