# How can we help?

## 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_v.1.2.3.zip](https://support.cordial.com/hc/article_attachments/43669446960013)

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](https://documentation.b2c.commercecloud.salesforce.com/DOC3/index.jsp?topic=%2Fcom.demandware.dochelp%2FLegacyDevDoc%2FUsingDemandwareUXStudio.html) plugin for Eclipse. Repeat the steps below for each cartridge.

1. Navigate to **File > Import > General > Existing Projects into Workspace**.
2. Locate the directory where you 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.

1. Sign in to Business Manager and navigate to **Administration > Sites > Manage Sites > [Site Name] > Settings**.

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:

```auto
int_cordial:int_cordial_core
```

- If your storefront is based on SFRA infrastructure, add the following at the end of the Cartridges path:

```auto
int_cordial_sfra:int_cordial_core
```

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

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

```auto
<isinclude template="cordial/cordialFooter"/>
```

Include the following in the minicart.isml and any other 'minicart' isml files the site uses:

```auto
<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:

```auto
<isinclude url="${URLUtils.url('CordialTag-RenderCordialAddToCart')}"/>
```

### Storefront Reference Architecture (SFRA)

Add the following code to the bottom of your footer_UI.isml file:

```auto
<isinclude template="cordial/cordialFooter"/>
```

Include the following in the minicart.isml, cart.isml and any other 'cart' isml files the site uses:

```auto
<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:

```javascript
newCustomerProfile.custom.subscribed = registrationForm.customer.addtoemaillist.checked;
newCustomerProfile.custom.cordialSubscribed = newCustomerProfile.custom.subscribed ? 'subscribed' : 'none';
```

On saving a customer, set **cordialSubscribed** field:

```javascript
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.
5. 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/'](https://api.cordial.io/v2/' "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**.

| **Option** | **Description** |
| --- | --- |
| Cordial API Key | Your Cordial account API key to authenticate API requests. Learn how to generate the [Cordial API key](https://support.cordial.com/hc/en-us/articles/115005365087). |
| Cordial Account Key | Unique Cordial account identifier. You can locate the account key from the Cordial [Account Settings](https://support.cordial.com/hc/en-us/articles/115005365147) 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 wish lists. 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](https://support.cordial.com/hc/en-us/articles/360016285852) 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](https://support.cordial.com/hc/en-us/articles/360016285852) 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](https://support.cordial.com/hc/en-us/articles/360016285852) 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. |

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](https://support.cordial.com/hc/en-us/articles/360016285852).

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

```auto
(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**.

| **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 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](https://support.cordial.com/hc/en-us/articles/115005528468#searchSupplements), 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.

```auto
if (Site.current.getCustomPreferenceValue('cordialEmailDisable')) {

return;
}
```

After that you can enable or disable it on the Settings page: **Disable Emails on Order State Change**.