Salesforce Commerce Cloud

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.

1. File > Import > General > Existing Projects into Workspace
2. Browse to the directory where you have saved the Cordial cartridges
3. Select the compressed cartridge file and click Finish
4. 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:

1. Navigate to Administration > Sites > Manage Sites and click the Business Manager site link.
2. 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.

1. Navigate to Administration > Organization > Roles & Permissions
2. Click the Administrator role and on the following page open the Business Manager Modules tab
3. When prompted, select all sites for which to edit permissions and click Apply
4. From the Business Manager Modules tab, locate the Cordial module and grant it write permissions
5. 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.

1. Navigate to Administration > Site Development > Site Import & Export
2. Click Choose file, locate the locally saved metadata.zip file, and click Upload
3. Select the radio button next to the newly uploaded metadata.zip file and click Import
4. 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.

1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > Cordial

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. 

1. Navigate to Merchant Tools > Cordial > Customer Attribute Key Mapping
2. 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.

1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > Cordial
2. Enable Modified Cordial Javascript Listener preference
3. 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

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: 

1. Select the one-time export job that needs to be run
2. Go to the Job Steps tab and click the export job name under Scope
3. Enter your SFCC username, password and confirm email address
4. Click Assign and then the Run Now button in the top-right corner

To set up an automated job export: 

1. Select the recurring export job that needs to be scheduled
2. Go to the Schedule and History tab
3. Select the Enabled checkbox and set the trigger to Recurring Interval
4. Set the recurring interval date range and specify the export interval frequency
5. Go to the Job Steps tab and click the export job name under Scope
6. 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:

1. ORDER_STATUS_CANCELLED
2. ORDER_STATUS_COMPLETED
3. ORDER_STATUS_CREATED
4. ORDER_STATUS_FAILED
5. ORDER_STATUS_NEW
6. ORDER_STATUS_OPEN
7. ORDER_STATUS_REPLACED
8. SHIPPING_STATUS_PARTSHIPPED
9. 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.