Integrating Salesforce Commerce Cloud

Importing pricebook from Salesforce Commerce Cloud

The process for pricebook mapping is almost same as of catalog mapping. For more information, read the Catalog Mapping tutorial.

You have to provide the pricebook mapping for SFCC only once.

Create a mapping configuration file and upload it to NewStore S3 bucket using the Mapping Configuration API    

Use case

The following is an example of the mapping configuration file for the SFCC pricebook. You can provide mappings for multiple pricebooks simultaneously.

  {
    "config": {
        "pricebook-sfra-apparel-catalog-en-eur": {
            "catalog": "sfra-apparel-catalog-en-test",
            "pricebook": "default",
            "shop": "storefront-catalog-en",
            "traits": []
        },
        "pricebook-sfra-apparel-catalog-en-usd": {
            "catalog": "sfra-apparel-catalog-en-test",
            "pricebook": "pricebook-sfra-apparel-catalog-en-usd",
            "shop": "storefront-catalog-en",
            "traits": []
        }
    }
}

The currency is used from a specific SFCC pricebook.

For instance, USD will be used from the pricebook-sfra-apparel-catalog-en-usd.

The following is an example of the XML file for SFCC USD pricebook.

    <pricebook>
        <header pricebook-id="pricebook-sfra-apparel-catalog-en-usd">
            <currency>USD</currency>
            <display-name xml:lang="x-default">Prices USD</display-name>
            <online-flag>true</online-flag>
        </header>
        <price-tables>
            <price-table product-id="640188016716M">
                <amount quantity="1">299.99</amount>
            </price-table>
            <price-table product-id="640188017003M">
                <amount quantity="1">39.99</amount>
            </price-table>
        </price-tables>
    </pricebook>

The following is an example of the JSON file for NewStore-compatible USD pricebook.

  {
  "head": {
    "currency": "USD",
    "pricebook": "pricebook-sfra-apparel-catalog-en-usd",
    "shop": "storefront-catalog-en",
    "catalog": "sfra-apparel-catalog-en-test",
    "traits": []
  },
  "items": [
    {
      "product_id": "640188016716M",
      "value": 299.99
    },
    {
      "product_id": "640188017003M",
      "value": 39.99
    }
  ]
  }

Importing orders using a custom mapping script

A custom mapping script is a single, plain script in JavaScript that accepts data in SalesForce format and publishes the data as output in NewStore format.

Use the script to map specific Salesforce Commerce Cloud attributes to extended attributes within NewStore.

Currently, NewStore supports using a custom mapping script to import orders.

Step 1: Importing the order XML file

1. Request an access token from NewStore.

2. Receive an upload URL using the NewStore SFCC Integration API.

3. Upload the Order XML file to the NewStore's S3 bucket.

Step 2: Transforming SFCC XML file to NewStore JSON file

1. Download the Order XML file.

2. Using JavaScript mapping, convert the SFCC XML file to the NewStore-compatible JSON file through an intermediary JSON file.

Step 3: Order mapping using a custom mapping script

The script runs on a virtual machine and it uses the intermediary JSON file as an input to convert that into a NewStore-compatible JSON file.

The following is an example of a custom mapping script to import orders.

/**
 * Define and call your own functions
 */
function formatLanguageForNewstore(sfLocale) {
  if (!sfLocale) {
    return 'en';
  }

  if (!sfLocale.match(/^[a-z]{2}\_[A-Z]{2}$/)) {
    throw new Error('Locale string does not match pattern xx_XX');
  }

  return sfLocale.split('_')[0];
};

/**
 * This is the main function
 */
function transform(sfOrder) {

    const placedAt = formatDateForNewstore(String(sfOrder['order-date']))

    const transformedOrder = {
        external_id: sfOrder['order-no'],
        placed_at: placedAt,
        shop: 'storefront-catalog-en',
        channel_type: 'web',
        channel_name: 'Salesforce Commerce Cloud',
        currency: sfOrder?.currency ?? 'USD',
        customer_name: sfOrder?.customer?.['customer-name'],
        customer_email: sfOrder?.customer?.['customer-email'],
        /* ... */
    }

    return transformedOrder;
}

For additional information, you can read the Boardriders use case.

Step 4: Order import through APIs

SFCC connector triggers the order import using Order Injection API.

Exporting availabilities to Salesforce Commerce Cloud

The SFCC cartridge imports availabilities from NewStore that helps in updating corresponding inventory lists in SFCC. This data import also includes inventory lists which may be used for stores in SFCC.

Process overview    

The SFCC cartridge runs a job that starts the export process in Newstore as follows:

1. Starts the POST: /availabilities/bulk/{group_name} export.

   SFCC provides inventory_list_id and ocapi_callback_url so that NewStore can execute the import job in SFCC later.

2. Fetches the file GET: /availabilities/bulk/{availability_export_id}.

3. Performs the file transformation from NewStore JSON to SFCC XML.

4. Uploads the SFCC XML file to the NewStore's S3 bucket.

5. Runs a job in SFCC using OCAPI to process the uploaded file and import it.

   During this process, the following attributes are sent to SFCC.

   • InventoryUrl: The url to download the inventory.xml from.

   • InventoryListID: The SFCC Inventory listID. This is sent back to NewStore in the next step 6.

   • LastUpdatedAt: Used for providing deltas from NewStore to SFCC. This value isn’t used by SFCC, only sent back to NewStore when the inventory was successfully imported, so that it can be store and used on the subsequent inventory export processes.

6. SFCC Notifies NewStore about sending LastUpdatedAt and InventoryListID information.

Step 1: Mapping between SFCC inventory list and NewStore group names

An inventory list is an aggregated Newstore availability from multiple fulfillment nodes.

Every inventory list present in SFCC, which needs to be updated with availability data from NewStore, corresponds to an availability group name in NewStore.

Use case 1: SFCC Storefront Reference Architecture (SFRA)    

The SFRA contains the inventory_m inventory list by default. So you can update the inventory list using the following endpoint to specify a group name and which fulfillment nodes will be part of that aggregated availability group.

POST: /availabilities/groups    

Body:

{
  "group_name": "inventory_list_sfcc",
  "fulfillment_nodes": [
    "FulfillmentNode01",
    "FulfillmentNode02"
  ]
}

Use case 2: Store inventory lists    

Each inventory list used by stores corresponds to a group name in NewStore.

However, for stores, you can have only one fulfillment node per group, which is the store itself.

POST: /availabilities/groups    

Body:

{
  "group_name": "store_1",
  "fulfillment_nodes": [
    "FulfillmentNodeStore01"
  ]
}

You can also create a store group name with multiple stores. However, this is not a valid business case.

Step 2: Updating fulfilment location groups

For example, a customer opens a new store and wants to have it added to the main aggregated inventory list.

PUT: /availabilities/groups/{group_name}    

Body:

Specify the new list of fulfilment locations, including the new store:

{
  "group_name": "inventory_list_sfcc",
  "fulfillment_nodes": [
    "FulfillmentNode01",
    "FulfillmentNode02",
    "FulfillmentNode03Store2"
  ]
}

Also, if the customer creates an inventory list in SFCC, you have to create a new corresponding group within Newstore. For more information, see Step 1: Mapping between SFCC inventory list and NewStore group names.

Step 3: Adding tenant-specific mapping configuration

For example, each customer may have a different extended attribute to identify the SFCC productID in NewStore.

POST: /availabilities/bulk generates an availabilities file that can be retrieved and looks like:    

 "atps": [
        {
            "atp": 19991,
            "external_identifiers": [
                {
                    "catalog": "storefront-catalog-en",
                    "identifiers": {
                        "sku": "640188016624M",
                        "upc": "640188016624"
                    },
                    "locale": "en-us"
                },
                {
                    "catalog": "sfra-apparel-catalog-en",
                    "identifiers": {
                        "sku": "640188016624M"
                    },
                    "locale": "en-us"
                }
            ],
            "future_atp": 0,
            "present_atp": 19991,
            "product_id": "640188016624M"
        },
        ...

Any of the external identifiers can be used as a SFCC productID, so that when the inventory XML file is generated, the external identifier being used, matches with the productID in SFCC.

Note

If the external_identifiers attribute is not present in the generated /availabilities/bulk file, then product_id will be used as a default mapping attribute.

Hence, a mapping configuration for each inventory list needs to be provided as follows:

POST: {{SFCC_CONNECTOR_ENDPOINT}}/sfcc-api/v1/mapping_config/availability    

{
  "inventory_list_id": "inventory_m",
  "config": {
    "catalog":"storefront-catalog-en-test",
    "locale":"en-us",
    "external_id":"upc",
    "handling":"preorder"
  }
}

This configuration specifies that for inventory list inventory_m and for catalog storefront-catalog-en-test, the external id upc should be used as a SFCC productID identifier, which generates a file, located at v.sfcc.newstore.transformation.data/inventory/team-sfcc/.

Step 4: SFCC callback to NewStore

The last step in this process to confirm the successful import in SFCC, is an asynchronous call from SFCC to the SFCC NewStore connector. This updates the last_updated_at field, allowing delta exports to be sent for the specified inventory list.

POST: {{SFCC_CONNECTOR_ENDPOINT}}/sfcc-api/v1/inventory/callback    

{
    "cartridge_version":"20.1.0",
    "execution_id":"NewStoreConnectorOrdersExport",
    "job_id":"54564654",
    "site_id":"RefArch",
    "custom":{
        last_updated_at: 123456;
        inventory_list_id: inventory_m;
    }
}

Authentication    

Because NewStore calls the SFCC cartridge using OCAPI, you have to perform the following to allow the authentication:

POST: {{SFCC_CONNECTOR_ENDPOINT}}/sfcc-api/v1/ocapi_credentials    

{
  "client_id": "client id provided by SFCC implementation partner",
  "client_secret": "URL ENCODED client secret id provided by SFCC implementation partner"
}

Note

Remember to URL Encode the password before posting it, otherwise it may not always work.

Step 5: Managing future inventory

In the mapping configuration specified previously, the handling attribute was also provided with the value preorder. Possible values for this attribute are as follows:

• preorder

• backorder

This attribute will be used to populate the preorder-backorder-handling SFCC attribute.

Note

Currently, NewStore manages future availability for Distribution Centers only. Stores don't support future availability.