RCG B2C Commerce Sync Cartridge - Source

This asset is a component of MuleSoft Accelerator for Retail, which accelerates implementation of essential integration use cases such as customer profile sync and order sync across commerce, marketing, CRM, ERP, and OMS applications.

The solution includes pre-built APIs, connectors, and integration templates that help unlock business-critical data from external systems, all the while guiding you to adopt best practices synthesized from thousands of customer implementations. These assets can be used as is or extended to meet your company's unique needs.

Customer profile sync cartridge

The Customer Profile Sync Cartridge is used to detect when a customer profile is created or updated in Salesforce B2C Commerce and invoke an API for further processing of the customer profile data in real-time.

Development setup

The following tools are available to help support the development and deployment of cartridges for B2C Commerce:

• UX Studio - an Eclipse-based product, and
• Visual Studio Code - a popular editor designed for modern applications.

B2C Commerce UX Studio

You can find all the details about downloading and installing UX Studio from the Administration > Site Development > Development Setup page in Business Manager.

Visual Studio Code

The Prophet Debugger extension for VS Code can also be used to upload and debug cartridges. A file named dw.json must exist in the project's root directory, which provides the connection details. The format of the file is as follows:

{
    "hostname": "URL to your CC instance",
    "username": "Account Manager login",
    "password": "Account Manageer password",
    "cartridge": ["plugin_instorepickup"],
    "code-version": "Current Version ID"
}

Once configured, you can use the palette command Prophet: Clean Project/Upload all to upload the cartridges.

Install the cartridge

To enable the features of the customer sync use case, the plugin_mulesoft_apisync and int_mulesoft_apisync cartridges must be installed in your storefront and set up in the storefront's cartridge path. To install and set up:

1. Log into the Business Manager (BM) using an account that has administrative permissions to the site that you wish to integrate with the Mule API:
   
   
   
   
2. Import this project into Studio UX or Visual Studio Code:
   
   
   
   
3. Upload the two cartridges to the current active code version within your environment. You can find this in BM under Administration > Site Development > Code Deployment:
   
   
   
   
   
   
4. In Business Manager, select Administration > Sites > Manage Sites:
   
   
   
   
5. Select the site you wish to integrate to the Mule API (e.g., RefArch):
   
   
   
   
6. Select the Settings tab:
   
   
   
   
7. Update the cartridge path to include the plugin_mulesoft_apisync and int_mulesoft_apisync cartridges. Be sure to include the cartridges near the front of the cartridge path before any core cartridges (e.g., plugin_mulesoft_apisync:int_mulesoft_apisync:app_storefront_base):
   
   
   
   
8. Click Apply to save your changes to the cartridge path.

Create the service definition

The B2C Commerce instance requires a service definition that must be configured to interact with the Mule API.

Upload the service definition

The following instructions provide guidance on how to import and configure the service definition for a site called RefArch. If your site ID is different, you must edit the endpoints.xml file to adjust the references accordingly.

1. In Business Manager, select Administration > Operations > Import & Export:
   
   
   
   
   
   
2. Click Upload in the 'Import & Export Files' section.
   
   
3. Click Choose File displayed in the 'Upload Import Files' section:
   
   
   
   
4. Locate and select the endpoints.xml definition file in the 'cartridges' source directory.
   
   
5. After you select the import file, click Upload to upload the import file:
   
   
   
   

Import the service definition

The following instructions describe how to import the service definition leveraged by the Customer Sync Cartridge.

Note: You must first upload the endpoints.xml import file to Business Manager first, as described in the previous section.

1. In Business Manager, select Administration > Operations > Import & Export:
   
   
   
   
2. Click Import in the 'Services' section:
   
   
   
   
3. Select the file named endpoints.xml and then click Next:
   
   
   
   
4. After the import process validates the file, confirm that the file has validated without any errors and then click Next to continue:
   
   
   
   
5. On the 'Import' step, select Merge as the import mode and then click Import to process the uploaded file:
   
   
   
   
6. Allow the import file to complete its processing and then confirm that the import has succeeded:
   
   
   
   

Note: The 'Status' section shows the import progress of the file being processed. Click Refresh to update. A successful import has a process status of Success. You can ignore any warnings about "Communication logging" when importing to sandbox environments:

Configure the service definition

The following describes how to configure the service definition for the cartridge so that it can communicate with the B2C Commerce Experience API deployed in CloudHub.

Set credentials for deployment

To change the credentials for all deployments:

1. In Business Manager, select Administration > Operations > Services:
   
   
   
   
2. Click the Credentials tab:
   
   
   
   
3. Edit the mule.auth-RefArch service credentials by clicking the credential name.
   
   
4. If your site ID is not RefArch, update the suffix of the credential name and then replace RefArch with your site name.
   
   
5. Use the following properties to configure the credentials for the service:

After the service credentials properties are updated, click Apply to save your changes, and then click the << Back to List button:

Adjusting your SiteId

Use the following instructions if your site ID is not RefArch and you did not edit the endpoints.xml file before importing.

1. Select the Services tab.
   
   
2. Edit the mule.auth-RefArch service definition by clicking on the service name.
   
   
3. Update the suffix of each service name and the log-prefix definition by replacing SiteId with your site name.
   
   
4. Update the suffix of the credential name and replace *SiteId with your site name:
   
   
   
   
5. Repeat steps 2-4 for the mule.rest-RefArch service.

This completes the configuration. There is no need to modify the associated profile-mule profile.

Configure custom preferences

The Customers and Orders sync processes can be enabled or disabled by setting
the muleSyncCustomersEnabled and muleSyncOrdersEnabled custom preferences,
respectively. By default, the sync process will not execute if not set. To
create and set the preferences:

1. Select Administration > Site Development > System Object Types
2. Select SitePreferences.
3. Click the Attribute Definition tab.
4. Click New and define the following custom site attribute:

   ID: muleCustomerSyncEnabledDisplay Name: Sync Customers to MuleHelp Text: Enable or disable publishing of customer profile updates to MuleValue Type: Boolean

5. Click Apply
6. Set the default value to True and click Apply
7. Click << Back and repeat the above steps for the second attribute:

   ID: muleOrderSyncEnabledDisplay Name: Sync Orders to MuleHelp Text: Enable or disable publishing of new customer orders to MuleValue Type: Boolean

8. Click the Attribute Grouping tab.
9. Add a new attribute group as follows:

   ID: MuleName: Mule SettingsDescription: Custom settigns for Mule integrations

10. Click apply and then click the Edit link for the new group
11. Click the ellipsis (...) to the left of the Add button
12. In the search area, type Mule and click Find
13. Select both Mule custom preferences and click Select
14. Click << Back to return to the Site Preferences object settings page

Configure custom properties

The synchronization process requires the addition of custom properties to
associate a global identifier with each of the Profile and Order objects.
These properties must be created as follows:

1. Click Administration > Site Development > System Object Types
2. Click on the Order object link
3. Select the Attribute Definitions tab
4. Click the New button and add the following attribute:

   ID: globalSalesOrderIdDisplay Name: Global Sales Order IDHelp Text: Identifies the global sales order an item is associated with.Value Type: String

5. Click Apply
6. Select << Back to List and click on the Product object link
7. Select the Attribute Definitions tab
8. Click the New button and add the following attribute:

   ID: globalProductIdDisplay Name: Global Product IDHelp Text: Identifies the global product an item is associated with.Value Type: String

9. Click Apply
10. Select << Back to List and click on the Profile object link
11. Select the Attribute Definitions tab
12. Click the New button and add the following attribute:

    ID: globalPartyRoleIdDisplay Name: Global Party Role IDHelp Text: Identifies the global party role a customer profile is associated with.Value Type: String

13. Click Apply

This completes the configuration.

Additional resources

The following links provide more details on how to develop and deploy Salesforce B2C Commerce cartridges:

• Salesforce B2C Commerce Cartridges - describes how to develop cartridges
• Develop for Salesforce B2C Commerce - describes how to set up the cartridge development environment
• Eclipse 4.6 (Neon) - UX Studio plugin installation location