Index SAP Commerce Cloud

This is for:

Developer

This article explains how to index SAP Commerce Cloud [1] catalog by using either a pull or push approach. The indexed data can be used in a Coveo-powered search interface built with the SAP Commerce Cloud composable storefront (previously SAP Spartacus).

Note

The examples provided in this article are for a simple use case that involves products only.

Your final structure will vary depending on how you set up your catalog within SAP.

Prerequisites

To index your commerce content, you need a Coveo organization. Coveo lets you create a source which is the bridge to your commerce data.

If you have never used the Cloud Platform before, log in now.

Notes

  • Contact your sales representative to enable Coveo for Commerce features in your organization.

  • You can review your Coveo organization license limits.

  • Ensure that you set the Required privileges for your commerce organization.

Pull vs push

Depending on your needs and SAP Commerce configuration, one of the approaches will be more suitable for you.

The following table presents pros and cons of these indexing methods.

Pull Push

🟢

Partially takes care of indexing logic.

 

Simplifies data mapping.

Doesn’t require Integration Objects.

 

SOLR has predefined Resolvers and Providers suitable to implement indexing logic.

❌

Requires the use of Integration Objects

Requires custom Java code to work with the Coveo Stream API

See the dedicated sections below for details and required steps.

Pull: pros and cons

The pull approach implies usage of the Coveo SAP connector that maps data being sent from SAP Commerce to your Coveo organization.

However, this approach requires adjusting the configuration on SAP’s end

  • creating Integration Objects, which may be non-trivial if you’re unfamiliar with these objects

  • creating new scripts to calculate computed attributes. Doing so may mean rewriting business logic that is already present in a Solr provider

Push: pros and cons

The push approach is mainly handled on SAP’s end and does not require Integration Objects but creating a new Provider and Exporter instead.

However, this approach requires you to take care of mapping the data being sent from SAP Commerce to your Coveo organization. This micromanagement is the downside of this approach.

Pull implementation

Step 1: Expose your SAP catalog

SAP Commerce Cloud’s Integration API Module exposes a set of interfaces used for data integration. You’ll need to create a Product Integration Object to expose your products. Here are a few leading practices to consider when creating the product integration object:

To get OData2 representation through this API, see The OData2 GET API.

This is an example of what Coveo receives when calling the API:

{
  "d": {
    "results": [
        {
            "__metadata": {
                "id": "https://api.acmestore.com/odata2webservices/CoveoInboundProduct/Products",
                "uri": "https://api.acmestore.com/odata2webservices/CoveoInboundProduct/Products",
                "type": "HybrisCommerceOData.Product"
                },
            "code": "137220",
            "name": "Camcordertape DV 60min (2)",
            "manufacturerAID": "2DVM60PR-BT",
            "manufacturerName": "Sony",
            "case_color": "red",
            "description": "<br/><br/>Perfect digital picture with a resolution that exceeds 500 lines.<br/><br/>Infinite range of possibilities to edit and share your videos.<br/><br/>Possibility to record up to 50% more in LP mode.<br/><br/>Cleaning Tape: DVM12CLD.<br/><br/>",

…

            "integrationKey": "Online|electronicsProductCatalog|137220",
            "stockLevels": {
                "__deferred": {
                "uri": "https://api.acmestore.com/odata2webservices/CoveoInboundProduct/Products"
                }
            },
...
        }
    ],
"__next": "https://api.acmestore.com/odata2webservices/CoveoInboundProduct/Products?$filter=catalogVersion%2FintegrationKey%20eq%20%27Online%7CelectronicsProductCatalog%27&$top=1&$skiptoken=2"
    }
}
//...

Step 2: Fetch catalog content in Coveo

To index data accessible through an exposed REST API, you must create an SAP source. The attributes specified in the REST configuration ensure that the corresponding fields will appear in your indexed catalog.

While creating an SAP source, make sure to

  • Complete the authentication section for the method used by the API you want to retrieve content from.

  • Create fields in the index for each metadata you want to retrieve with the SAP source.

  • Map your source with all the fields you want to populate. If a field doesn’t have a mapping, you must create one.

You can adapt the values based on your API response, as each use case will be different.

{
  "services": [
    {
      "url": "https://api.acmestore.com/odata2webservices", 1
      "headers": {
        "Accept": "application/json",
        "Application-Interface-Key": "xxxxxxxx" 2
      },
      "paging": {
        "pageSize": 10,
        "offsetStart": 0,
        "offsetType": "item",
        "nextPageKey": "__next",
        "parameters": {
          "limit": "$top",
          "offset": "$skip"
        }
      },
      "endpoints": [ 3
        {
          "path": "/Product/Products", 4
          "method": "GET",
          "queryParameters": {
            "$filter": "catalogVersion/integrationKey eq 'Online%7CpowertoolsProductCatalog' and approvalStatus/code eq 'approved'",
            5
            "$expand": "supercategories,thumbnails,picture,thumbnail,unit,catalogVersion/catalog,europe1Prices,europe1Prices/currency,bundleTemplates,localizedAttributes,supercategories/localizedAttributes,approvalStatus"
            6
          },
          "itemPath": "d.results", 7
          "itemType": "product", 8
          "uri": "https://accstorefront.commerce.ondemand.com/coveob2bstorefront/powertools/en/USD/%[url]",
          9
          "clickableUri": "https://accstorefront.commerce.ondemand.com/coveob2bstorefront/powertools/en/USD/%[url]",
          "metadata": { 10
            "objecttype": "Product", 11
            "ec_brand": "%[brand]",
            "ec_name": "%[name]",
            "name": "%[name]",
            "ec_item_group_id": "%[code]",
            "ec_shortdesc": "%[summary]",
            "ec_description": "%[description]",
            "ec_price": "%[europe1Prices.results[0].price]",
            "ec_thumbnails": "https://accstorefront.commerce.ondemand.com%[thumbnail.URL]",
            "ec_in_stock": "%[stock]",
            "ec_images": "https://accstorefront.commerce.ondemand.com%[picture.URL]",
            "ec_category": "%[supercategories.results[:].name]",
            "ec_pricerange": "%[priceRange]",
            "ec_configurable": "%[configurable]",
            "ec_code": "%[code]",
            "ec_url": "https://accstorefront.commerce.ondemand.com/coveob2bstorefront/powertools/en/USD/%[url]"
          }
        }
      ]
    }
  ]
}
//...
1 url. The URL of your SAP Commerce Cloud OData2 GET API.
2 Application-Interface-Key. A unique Application Interface Key (Application Interface Register, AIR). It defines Coveo as a partner of SAP and once set, it shouldn’t be changed or removed.
3 endpoints. You can specify as many endpoints as you need.

By default, the SAP source JSON configuration contains three endpoints, one for:

  • product (e.g., "path": "/Product/Products")

  • variant (e.g., "path": "FootWearVariant/GenericVariantProducts")

  • availability (e.g., "path": "/Availability/Warehouses")

You can remove or add endpoints depending on your use case. In the example above, there’s only one endpoint for products.
4 path. The path to your products. It’s made in the format of /name of the integration object created in the Backoffice/the type of the object+s
5 filter. The expression that specifies the products to be indexed. Must be URL-encoded.
6 expand. The list of entries associated with a single integration object or a collection of integration objects.
7 itemPath. Specifies the object with results. Its value should be d.results, according to the response structure.
8 itemType. The type of item that the resource contains. Coveo uses this data to organize the indexed content.
9 uri. The URI of the product’s PDP page.
10 metadata. Maps attributes from the integration object to the Coveo fields.

Some ecommerce fields are created and mapped by default. You can add customs fields in the Coveo Administration Console (platform-ca | platform-eu | platform-au).
11 objecttype. The mandatory field for indexing via the SAP source.

It indicates whether the document is a product, variant, or availability.

Once you have rebuilt your source, you can inspect the items with the Content Browser (platform-ca | platform-eu | platform-au).

Push implementation

SAP Commerce uses the Solr Search engine for search, facets, PLP results sorting, boosting, and query suggestions. The facet search configuration can be done through the graphical interface of the Backoffice Administration Cockpit.

Advantages of using existing Solr cronjobs

SAP Commerce uses cronjobs to initially index products into Solr and update that index after.

Warning

To push products from SAP Commerce to Coveo, we strongly recommend using existing Solr cronjobs.

You can create your own, new cronjobs, but it would require you to:

  • rewrite all the queries used to index products

  • recreate all the business logic that’s already present in value providers

  • add new attributes to the indexed products, which may require code changes

It all can be non-trivial to implement and the final solution may be more error-prone. This is why using the existing cronjobs is the best practice here.

Push implementation guides

Depending on the SAP Commerce version you’re using, follow the appropriate guide:

1. SAP Commerce Cloud previously called Hybris.