The Constructor Salesforce Cartridge facilitates synchronizing catalog data from your Salesforce instance (SFRA / SFCC) to Constructor.

This cartridge simplifies the connection and upload of your Salesforce product catalog to Constructor, enabling seamless integration of all product data from Salesforce into Constructor solutions. It empowers an e-commerce team in real time by identifying optimization opportunities. Additionally, the cartridge can be customized to suit specific requirements.

This article illustrates how to setup and use the cartridge.

📘

Heads up

This documentation covers the catalog integration for SFRA.

If you're using Site Genesis, please refer to this page.

Requirements

First of all, you need to obtain the source code for the cartridge. You can download it through our official Salesforce AppExchange Listing, and see all details on Installing the Constructor Connect cartridge.

For assistance with the installation process, please contact our team at [email protected]. We’ll be glad to guide you through the installation steps beyond what is covered in this document.

Cartridge jobs

To use the cartridge, go to Administration > Operations > Jobs. There, you'll find that the cartridge exposes three main jobs:

• Constructor.SyncCategories: Sends all category data to Constructor.
• Constructor.SyncProducts: Sends all product data (products, variants, etc) to Constructor.
• Constructor.PatchProducts: Sends partial product data to Constructor. Can be used to update any fields, such as prices, inventories, facets or metadata.

You can easily create more jobs if needed by customizing the cartridge, depending on your needs.

📘

Job execution order matters

Pay attention to the order you're going to run the jobs on.

Initially, make sure to run the categories job first so that when you send products, your category data is already available and populated in Constructor.

That's it. You can run these jobs manually or set up a schedule to run it periodically. Each time the job is run, the selected data for this site will be synced to Constructor.

Constructor.SyncCategories

This job will send all category data to Constructor. Category hierarchy will be preserved.

Parameters can be provided via job steps:

• Locale: The locale to fetch data from. Falls back to the site's default locale.
• ApiKeyOverride: Allows overriding the API key provided in the site preferences to send data to a different index.

Constructor.SyncProducts

This job will send all product data to Constructor. This includes simple products, product sets, master products and variants.

Note that variation groups will not be sent. If you want to expose variation group data to your catalog, you should add it as facets or metadata to your master products or variations during the data transformation.

Parameters can be provided via job steps:

• PartialByLastSyncDate: Toggles the partial sync by last sync date. See the partial syncs section below for more details.
• SendOfflineVariants: If enabled, the cartridge will send all variants that belong to a master product if here are any matches. This will impact performance.
• IncludeMasterProductsOutOfStock: If enabled, the cartridge will send all online master products, even if they are out of stock. This will heavily impact performance.
• IngestionStrategy: Determines the ingestion strategy to use. See the ingestion strategies section below for more details.
• ApiKeyOverride: Allows overriding the API key provided in the site preferences to send data to a different index.
• Locale: The locale to fetch data from. Falls back to the site's default locale.
• Section: The index section to write data to. Defaults to Products.
• Force: Defines if ingestions should be forced if they are going to delete or inactivate more than 50% of the records. Defaults to false.
• Filters.Ids: Filter to only send products that match a list of ids (comma separated). You can use IDs for master products, product sets, variation groups or variations. Can have a maximum of 30 IDs.
• Filters.CategoryId: Filter to only send products that belong to a specific category. Will include all subcategories.
• Filters.SearchPhrase: Filter to only send products based on a search phrase.

Constructor.PatchProducts

This job will send partial product data to Constructor. It's capable of sending any product data present in the full products job, such as prices, inventories, normal fields, any facets or metadata.

Parameters can be provided via job steps:

• PartialByLastSyncDate: Toggles the partial sync by last sync date. See the partial syncs section below for more details.
• SendOfflineVariants: If enabled, the cartridge will send all variants that belong to a master product if here are any matches. This will impact performance.
• IncludeMasterProductsOutOfStock: If enabled, the cartridge will send all online master products, even if they are out of stock. This will heavily impact performance.
• IngestionStrategy: Determines the ingestion strategy to use. See the ingestion strategies section below for more details.
• ApiKeyOverride: Allows overriding the API key provided in the site preferences to send data to a different index.
• Locale: The locale to fetch data from. Falls back to the site's default locale.
• Section: The index section to write data to. Defaults to Products.
• Force: Defines if ingestions should be forced if they are going to delete or inactivate more than 50% of the records. Defaults to false.
• Filters.Ids: Filter to only send products that match a list of ids (comma separated). You can use IDs for master products, product sets, variation groups or variations. Can have a maximum of 30 IDs.
• Filters.CategoryId: Filter to only send products that belong to a specific category. Will include all subcategories.
• Filters.SearchPhrase: Filter to only send products based on a search phrase.

Partial updates by last sync date

The cartridge will expose a custom site preference to track the last time a sync job was ran without filters, for each specific locale. This is used to support partial syncs, where it'll only send information from records that were updated
since the last relative job completed to achieve maximum performance.

Those dates are updated automatically, so you should not update this field manually. Only update these fields if you want to manually force a full sync, by clearing up the last sync date for a given job.

Note that all dates stored on this field are defined in UTC.

Ingestion strategies

As you can see, the jobs to send product data offer a couple of ingestion strategy options. Those define how data is updated at Constructor:

• Full (Replace): Will replace the entire catalog with the data sent. Records not present on the feed will be deleted in Constructor.
• Patch (Update): Will update only the items that were sent by the cartridge. Does not delete any records.
• Patch Delta (Fail in case of additional items): Similar to a patch, will partially update the catalog with the data sent, but does not require all fields. Fails if additional items are sent.
• Patch Delta (Create additional items): Similar to a patch, will partially update the catalog with the data sent, but does not require all fields. Will create any additional items sent.
• Patch Delta (Ignore additional items): Similar to a patch, will partially update the catalog with the data sent, but does not require all fields. Will ignore any additional items sent.

Customizing your catalog data

Normally, when using the cartridge you'll need to customize your catalog data to some extent. This can mean adding facets and metadata, customizing other fields (for example the product urls or image urls), indexing new data (such as blog posts or recipes) and so on.

The cartridge supports a huge flexibility on customizations. To do this, you'll want to create overlays to modify portions of the source code while still maintaining the original source code available, which makes updating the cartridge easy.

The out of the box installation already provides a base cartridge to add your overlays on, called link_constructor_connect_custom. You'll want to add your customizations there.

❗️

Disclaimer

While you can directly modify the cartridge files and customize them, we highly recommend implementing any customizations using overlays.

This will make future updates much easier to perform as you won't have to sort through diffs between many versions.

To add any overlays, look for the file responsible for the behavior you want to change. Files are organized in minor behavior actions, such as getting a product URL, image or description.

For instance, if you're looking to customize how products are transformed:

• getCategories.js
• getImage.js
• getUrl.js

📘

Don't forget to re-upload

When you add an overlay or any other customization, don't forget to re-upload the cartridge so that your changes take effect.

Adding facets and metadata

Adding facets and metadata to items and variations is as easy as changing function to customize them for items or variations.

The cartridge exposes two files to handle this:

• getFacetsAndMetadata.js
• getFacetsAndMetadataForVariation.js

While the first one handles these attributes for master products, product sets and simple products, the second one handles them for variations.

For example, let's say you want to sync the attributes price and color:

var getAttributeValue = require('*/cartridge/scripts/helpers/products/getAttributeValue');

module.exports = function getFacetsAndMetadata(product) {
  return {
    facets: [
      {
        key: 'price',
        value: getAttributeValue(product, 'price')
      }
    ],
    metadata: [
      {
        key: 'color',
        value: getAttributeValue(product, 'color')
      }
    ]
  };
};