Overview

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 to 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

Download the Cordial Salesforce cartridges: SFCC_cartridge_v1.1.6.zip

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 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.

Ensure all cartridge names in the Cartridges field are separated by a colon.

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.

Cartridges can be shared across multiple sites. Simply apply the Cordial cartridges to the effective cartridge path for each 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.

6. 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 access the Cordial integration custom preferences from the Business Manager.

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

GMT is used for all time settings and schedules.

Customer attribute key mapping

You can 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.

All contact attributes you intend to map must already exist in your Cordial account.

Use 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 visit our Embedded JavaScript Listener v2 article.

Using your vanity domain, the content of the Modified Cordial Javascript Listener preference should look like this:

(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.

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 three hours timeout by default. Job execution will be stopped when the timeout is reached. If a job should run longer, its timeout can be configured in int_cordial_core/steptypes.json file using the timeout-in-second setting.

Test jobs

Test exports

When in comes to exporting customers, products and orders to Cordial there are two things to test: recurring jobs and one-time jobs.

Test recurring jobs

A recurring job takes a list of all not-yet-exported-to-Cordial entities (customers/products/orders) that have been modified or created since a date specified. The job then exports the entities (found one by one) to Cordial.

It's important to limit the number of entities to export, otherwise it might take hours to export them all. You can do so by setting the corresponding Export Last Modified Date setting.

Use case

When testing a 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 allow for a few tens of thousands of customers to be found. After that, run the Recurring Customers Export. Wait until the job executes and verify in Cordial Administration that the customers modified after the date you set are correctly exported.

Test one-time jobs

One-time jobs export all available customers/products/orders. Exporting all of those entities might take a while. It could be hours for millions of records. To shorten the feedback loop by limiting the number of customers/products/orders that are exported, each one-time job 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 Administration that 1000 entities were correctly exported to Cordial.

Test events

To test that events are correctly generated from your storefront, log in to your storefront with an already exported-to-Cordial customer and navigate to a product. In Cordial Administration, see the 'product_view' event generated for the contact.

Run 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 and password and confirm your email address.

4. Click Assign and then the Run Now button in the top-right corner.

Before scheduling a recurring export job, ensure that Export as of Last Modified Date fields in Custom Preferences have a date for how far back each job should look for new and updated customer records.

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 the Schedule and History tab

Time-based execution of custom schedules is disabled on sandbox instances. Scheduled jobs won’t execute in the sandbox, but you can run your jobs manually.

Wish list export

Customer wish list items are exported to the Cordial supplement data collection sfcc__wishlist. Each wish list item is therefore a supplement collection record that's 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. Here's a 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 or disable emails for orders state changes

In order to disable email send when order’s state changes, you should add code into the function that sends email. Usually it's 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.