Salsify connector

The Salsify connector is a KeyShot owned and build connector following the Managed integrations architecture.

The connector is bi-directional and supports

Creating and updating Digital assets in Salsify
- Setting metadata on Digital assets
- Uploading / Replacing the files on the Digital asset
Linking Digital assets to Products
Updating metadata back into KeyShot Dock

Setting it up

The connector is deployed by the KeyShot CSM team as part of a Keyshot Dock installation. Once deployed the connector is available through Administration → System → Integrations → Managed Integrations as follows

The general configuration options are described in greater detail in the Managed integrations section and this documentation focuses on the custom configuration for the Salsify connector

The custom configuration is found when editing the connector under Custom configuration. The following parameters are available

Parameter	Description
`OrganizationId`	Salsify is a multi-tenant system and so the organization id describes the tenant.
`ApiKey`	Api key generated for the API user - see https://developers.salsify.com/reference/token-based-authentication
`SalsifyUniqueId`	Unique identifier used to create the asset in Salsify. It supports the following properties AssetId Metafield guid (I.e use a metafield value is unique identifier) SourceFilename This must be unique for the assets in Salsify!
`SalsifyProductDigitalAssetField`	This is the Digital asset field on the product on which the uploaded asset should be mapped. This supports Metafield guid (i.e. grab the string value from a metafield to find the mapping. Use this for dynamic mapping) Hard coded name (e.g. “Main image”)
`FailIfNoProductMappingExist`	Boolean (true/false) value indicating if the asset should be failed if the product, on which the asset should be linked, does not exists.
`CustomMetadata`	Array containing the metadata to be sent to Salsify (i.e. this is the metadata that is linked on the Digital asset). Explained in more detail later.
`ProductMapping`	Object for describing how the Digital asset should be mapped to a product. Explained in greater detail later.
`DigizuiteMetadataToUpdate`	The metadata that is fetched the product and written back to KeyShot Dock

The CustomMetadata is an array of field mappings used to define which metadata fields in KeyShot Dock should be included on the uploaded Digital asset in Salsify. Each entry must have the following parameters

Parameter	Description
`SalsifyMetadataId`	This is the name of the field in Salsify that the metadata from KeyShot Dock must be put in
`MetafieldItemGuid`	This is the guid of the metafield in KeyShot dock from which the value must be extracted
`SalsifyMetadataType`	This is the type of field in Salsify. See https://developers.salsify.com/reference/metadata#salsifydata_type--property-type-values for a list of available options

The ProductMapping is used to determine which product(s) the Digital asset should be mapped to. This must map to a KeyShot metafield. It supports different field types and as such can both be a simple string value, but also a Combo type.

For non-simple types (like Combo) it also supports multiple values if one asset should be mapped to multiple products. Similarly for the simple types (like string) it supports a delimiter separated list of values.

This gives us the following parameters that must be filled out

Parameter	Description
`ProductMetafield`	Guid of the metafield in KeyShot Dock from which the product ids must be extracted
`Delimiter`	Only relevant if the field contains a delimiter separated list of values (e.g. Sku 1;Sku 2; Sku 3). This is optional

It is very important that any mapped KeyShot Dock metadata field is included in the Additional metadata fields property in the general configuration for the integration - see Managed integrations

With the above documentation this gives us the following example JSON to be created

{
  "OrganizationId": "<Organization Id>",
  "ApiKey": "<Api key>",
  "SalsifyUniqueId": "AssetId",
  "SalsifyProductDigitalAssetField": "<Digital asset field on product>",
  "FailIfNoProductMappingExist": <true / false>,
  "CustomMetadata": [
    {
      "SalsifyMetadataId": "<name of field>",
      "MetafieldItemGuid": "<Guid of KeyShot metafield>",
      "SalsifyMetadataType": "<Salsify metadata type>"
    },
    {
      "SalsifyMetadataId": "<name of field>",
      "MetafieldItemGuid": "<Guid of KeyShot metafield>",
      "SalsifyMetadataType": "<Salsify metadata type>"
    }
  ],
  "ProductMapping": {
    "ProductMetafield": "<Guid of SKU field>",
    "Delimiter": "<Delimiter if there are more products (e.g. ;)>"
  },
  "DigizuiteMetadataToUpdate": [
    {
      "MetafieldItemGuid": "<Guid of KeyShot metafield>",
      "SalsifyMetadataId": "<name of field>",
      "MetaFieldDataType": "<KeyShot metadata type>"
    },
    {
      "MetafieldItemGuid": "<Guid of KeyShot metafield>",
      "SalsifyMetadataId": "<name of field>",
      "MetaFieldDataType": "<KeyShot metadata type>"
    }
  ]
}