Cordial Salesforce Cartridges
Cordial’s integration with Salesforce supports SiteGenesis (SG) and Storefront Reference Architecture (SFRA) storefronts. To integrate successfully, you must upload and activate three cartridges -- the shared core functionality cartridge, the cartridge that corresponds with your storefront software architecture, and the Cordial Business Manager module cartridge.
Integration cartridges:
- Int_cordial_core - shared core functionality required for both SG and SFRA storefronts
- Int_cordial - for SG based storefronts only
- Int_cordial_sfra - for SFRA based storefronts only
- bm_cordial - Cordial Business Manager module
Upload cartridges to Salesforce Commerce Cloud
You can upload Cordial cartridges using an IDE that supports a connection with the SFCC development server. This example demonstrates how to upload cartridges using the SFCC UX Studio plugin for Eclipse. Repeat the steps below for each cartridge.
- File > Import > General > Existing Projects into Workspace
- Browse to the directory where you have saved the Cordial cartridges
- Select the compressed cartridge file and click Finish
- Click Yes when prompted to manually link the cartridge to your server
Activate the integration cartridges
To enable the Cordial integration functionality, the newly imported cartridges must be added to the Effective Cartridge Path of your specific site.
- Sign in to Business Manager and navigate to Administration > Sites > Manage Sites > [Site Name] > Settings tab.
If your storefront is based on SiteGenesis infrastructure, add the following at the end of the Cartridges path:
int_cordial:int_cordial_core
If your storefront is based on SFRA infrastructure, add the following at the end of the Cartridges path:
int_cordial_sfra:int_cordial_core
Click Apply and the Effective Cartridge Path will be updated, making the Cordial cartridges available to your selected site.
Activate the Business Manager module cartridge
The Business Manager module cartridge (bm_cordial) will add the Cordial module with links to access the Customer Attribute Key Mapping page and Custom Site Preferences for the Cordial integration.
Once uploaded, this cartridge must be added to the Effective Cartridge Path of your Business Manager instance:
- Navigate to Administration > Sites > Manage Sites and click the Business Manager site link.
- Add bm_cordial at the end of the Cartridges path and click Apply.
The Cordial Business Manager module requires write access permissions that can typically be granted by the administrator role.
- Navigate to Administration > Organization > Roles & Permissions
- Click the Administrator role and on the following page open the Business Manager Modules tab
- When prompted, select all sites for which to edit permissions and click Apply
- From the Business Manager Modules tab, locate the Cordial module and grant it write permissions
- Click Update
You may need to refresh the Business Manager page to see the Cordial module in the Merchant Tools menu.
Add snippets to site templates to enable TrackJS
Site Genesis
Add the following code to the bottom of your footer_UI.isml file:
<isinclude template="cordial/cordialFooter"/>
Include the following in the minicart.isml and any other "minicart" isml files the site uses:
<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction== 'update'}"> <isinclude url="${URLUtils.url('CordialTag-RenderCordialAddToCart')}"/>
</isif>
Include the following in the cart.isml and any other "cart" isml files :
<isinclude url="${URLUtils.url('CordialTag-RenderCordialAddToCart')}"/>
Storefront Reference Architecture (SFRA)
Add the following code to the bottom of your footer_UI.isml file:
<isinclude template="cordial/cordialFooter"/>
Include the following in the minicart.isml, cart.isml and any other "cart" isml files the site uses:
<isinclude url="${URLUtils.url('CordialTag-RenderCordialAddToCart')}"/>
Upload Metadata and Configure Custom Preferences
The metadata file contains Cordial integration services configuration along with jobs and custom site preferences. You must upload and import the metadata file to enable access to these integration settings in Business Manager.
- Navigate to Administration > Site Development > Site Import & Export
- Click Choose file, locate the locally saved metadata.zip file, and click Upload
- Select the radio button next to the newly uploaded metadata.zip file and click Import
- Click OK when prompted to confirm your intent to upload the file
Check the Status section of the page to verify when the file upload status is finished. You can Refresh the page to see the latest status update.

Configure Cordial Integration Custom Preferences
You can now access the Cordial integration custom preferences from the Business Manager.
- Navigate to Merchant Tools > Site Preferences > Custom Preferences > Cordial
Option | Description |
---|---|
Cordial API Key |
Your Cordial account API key to authenticate API requests. Learn how to generate the Cordial API key. |
Cordial Account Key |
Unique Cordial account identifier. You can locate the account key from the Cordial Account Settings page. |
Customer Attribute Key Mappings |
Customer attribute key mapping object represented in JSON. Synchronizes with entries on the Customer Attribute Key Mapping page. |
Customer Export as of Last Modified Date |
Indicates how far back to go and look for new and updated customer records. This field will dynamically reflect the date of the last recurring customer export job. Can be set manually when you need to export new and updated customers as of a specific date. |
Wishlist Export as of Last Modified Date |
Indicates how far back to go and look for new and updated wishlists. This field will dynamically reflect the date of the last recurring product export job. Can be set manually when you need to export new and updated products as of a specific date. |
Product Export as of Last Modified Date |
Indicates how far back to go and look for new and updated products. This field will dynamically reflect the date of the last recurring product export job. Can be set manually when you need to export new and updated products as of a specific date. |
Order Export as of Last Modified Date |
Indicates how far back to go and look for new and updated orders. This field will dynamically reflect the date of the last recurring order export job. Can be set manually when you need to export new and updated orders as of a specific date. |
Enable Default JavaScript Listener Script |
Enable the Cordial JavaScript listener base script to post data from your storefront to your Cordial account. |
Enable Modified Cordial JavaScript Listener |
Enable the use of modified Cordial JavaScript listener base script. When set to Yes, takes precedence over the default JavaScript listener base script. |
Cordial JavaScript Listener Base Script |
Modify the Cordial JavaScript listener base script parameters. |
Enable Cordial Logs |
Enable logging of Cordial cartridge messages for debugging/troubleshooting purposes. |
Disable Emails on Order State Change |
Manage automatic emails sendout for order state change by enabling/disabling this option. |
Customer attribute key mapping
You are now ready to map Salesforce customer attribute keys to your Cordial contact attributes. Attribute mappings on this page determine the export file columns for related export jobs.
- Navigate to Merchant Tools > Cordial > Customer Attribute Key Mapping
- Add a row for each attribute mapping
The attribute form fields will automatically suggest available Salesforce and Cordial contact attributes based on the search text provided. Note that all contact attributes you intend to map must already exist in your Cordial account.

Configure Cordial Export Jobs
When synchronizing SFCC storefront data to Cordial, there are two options: manual one-time synchronization of historical data and automated recurring synchronization.
Typically, you will use the manual method to perform one-time synchronization of historical data for each job, and then set up recurring job schedules to automatically synchronize new and updated records thereafter. Note that recurring data synchronizations use API calls to post data.
For a list of integration export jobs, navigate to Administration > Operations > Jobs
Cordial Jobs |
---|
One-time All Customers Export |
Recurring Customers Export |
One-time All Orders Export |
Recurring Orders Export |
One-time All Products Export |
Recurring Products Export |
Recurring Wish List Export |
To manually run a job:
- Select the one-time export job that needs to be run
- Go to the Job Steps tab and click the export job name under Scope
- Enter your SFCC username, password and confirm email address
- Click Assign and then the Run Now button in the top-right corner
To set up an automated job export:
- Select the recurring export job that needs to be scheduled
- Go to the Schedule and History tab
- Select the Enabled checkbox and set the trigger to Recurring Interval
- Set the recurring interval date range and specify the export interval frequency
- Go to the Job Steps tab and click the export job name under Scope
- Click Assign and the job will run on a recurring schedule starting on the date and time you indicated in Schedule and History tab
Wishlist export
Customer wish list items are exported to Cordial supplement data collection sfcc__wishlist. Each wish list item is therefore a supplement collection record that is matched to a specific Cordial contact using a unique identifier such as email address. The wish list supplement collection sfcc__wishlist is contact attribute enabled, allowing you to create Cordial audiences based on whether or not a specific product is on the contact’s wish list.
Messages Support
Transactional messages
When the order's state changes, an event is fired. List of supported states:
- ORDER_STATUS_CANCELLED
- ORDER_STATUS_COMPLETED
- ORDER_STATUS_CREATED
- ORDER_STATUS_FAILED
- ORDER_STATUS_NEW
- ORDER_STATUS_OPEN
- ORDER_STATUS_REPLACED
- SHIPPING_STATUS_PARTSHIPPED
- SHIPPING_STATUS_SHIPPED
Steps to enable/disable emails for orders state changes
In order to disable email send when order’s state changes you should add code into the function which sends email. Usually it is a sendConfimationEmail function. Add the code below to checkout/checkoutHelpers file in the beginning of the function.
if (Site.current.getCustomPreferenceValue('cordialEmailDisable')) {
return;
}
After that you can enable or disable it on the Settings page > Disable Emails on Order State Change.
Comments
0 comments
Please sign in to leave a comment.