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')}"/>
Add snippets to pass contacts subscription status to Cordial
To pass contacts' subscribeStatus to Cordial, the following code should be added to your Account.js file, where users are registered and their profile is updated.
On registering a new customer, additionally to other fields set cordialSubscribed field:
newCustomerProfile.custom.subscribed = registrationForm.customer. addtoemaillist.checked;
newCustomerProfile.custom.cordialSubscribed = newCustomerProfile.custom. subscribed ? 'subscribed' : 'none';
On saving a customer set cordialSubscribed field:
profile.custom.subscribed = profileForm.customer.addtoemaillist.checked;
profile.custom.cordialSubscribed = profile.custom.subscribed ? 'subscribed' : 'none';
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 API Endpoint
Cordial API endpoint that SFCC instance communicates with is configured on Administration > Operations > Services > cordialCredentials page. On the page you will see the Cordial API endpoint field. For production set it to 'https://api.cordial.io/v2/'. User and password fields are not used and should be left blank.
The name of the service should always be 'cordial.rest'. Profile name 'cordialProfile' and credentials name 'cordialCredentials' can be changed and in that case the changes should be reflected in 'cordial.rest' service configuration.
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.

Using vanity domains with JavaScript listener
You can use vanity domains with JavaScript listener.
- Navigate to Merchant Tools > Site Preferences > Custom Preferences > Cordial
- Enable
Modified Cordial Javascript Listener
preference - Specify
Javascript Listener Base Script
with vanity domains in it

For details on how to specify the script so that it uses vanity domains see https://support.cordial.com/hc/en-us/articles/360016285852
For example, the content of the Modified Cordial Javascript Listener preference should look like this using your vanity domain:
(function(C,O,R,D,I,A,L){
C.CordialObject=I,C[I]=C[I]||function(){(C[I].q=C[I].q||[]).push(arguments)};
C[I].l=1*new Date,C[I].q=[],A=O.createElement(R);
L=O.getElementsByTagName(R)[0],A.async=1,A.src=D,L.parentNode.insertBefore(A,L);
})(window, document, "script", "//track.cordial.io/track.v2.js", "crdl");
crdl("connect", "YOUR_ACCOUNT_KEY_HERE", {
trackUrl: "//se.email.example.com",
connectUrl: "//d.email.example.com",
cookieDomain: "email.example.com", cookieLife: 365
});
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 |
Configure Jobs Timeouts
Each export job is configured with 3 hours timeout by default. Job execution will be stopped when the timeout is reached. If a job should run longer than that its timeout can be configured in int_cordial_core/steptypes.json file using the timeout-in-second setting.
Testing Jobs
Testing Exports
When in comes to exporting customers, products and orders to Cordial there are two things to test: testing recurring jobs and testing one-time jobs.
Testing Recurring jobs
A recurring job takes a list of all not yet exported to Cordial entities (customers/products/orders) modified or created since a date specified. Then the job exports the entities found one by one to Cordial. Thus it is important to limit the number of entities to export otherwise it might take hours to export them all.
To test a recurring job, make sure you limit the number of entities to export by setting the corresponding Export Last Modified Date setting. For example, when testing Recurring Customers export job, update 'Contact Export Last Modified Date' to a date that would indicate how far back to go for new and updated customers. A good date would be a date that would allow to have a few tens of customers found. After that, run 'Recurring Customers Export'. Wait until the job executes and check in Cordial admin that the customers modified after the date you set are correctly exported.
Testing One-Time jobs
One-time jobs export all available customers/products/orders. Exporting all of those entities might take a while (hours for millions of records). To shorten the feedback loop by limiting the number of customers/products/orders that are exported, each one-time jobs has its TEST RUN counterpart. Each TEST RUN one-time job will take only 1000 of the first entities to export. Run TEST RUN One-Time Customers Export job and check in Cordial admin that 1000 of entities got correctly exported to Cordial.
Testing events
To test that events are correctly generated from your storefront, log in to your storefront with an already exported customer to Cordial and navigate to a product. In Cordial admin see the 'product_view' event generated for the contact.
Running Jobs
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, the order event is fired. The event contains the status property the value of which is the new state of the order. List of supported order 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.