Index SAP Commerce Cloud

This is for:

Developer System Administrator

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.

1. SAP Commerce Cloud previously called Hybris.

Prerequisites

To index your commerce content, you need a Coveo organization. The Coveo Platform 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 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, either the SAP catalog pull source or the SAP catalog push integration will be more suitable for you.

  • SAP catalog pull source: You can use the SAP source to index product catalogs from SAP Commerce Cloud.

    Tip

    Follow this approach if you have a simpler setup where your catalog data doesn’t change often, for example, a POC or demo. Also, if you’re familiar with integration objects, this approach is faster to get up and running.

  • SAP catalog push integration: You can use the Coveo SAP Commerce indexer push extension to send the indexed data to your Coveo organization.

    Tip

    Choose this if you operate at scale or have frequent changes to your catalog data. This approach is better for handling lots of sources and gives customers greater control at pushing more frequent updates.

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

Pull Push

🟢

Partially takes care of indexing logic.

Doesn’t require integration objects.

 

Easier to keep the catalog up to date by pushing the changed data only when needed.[1]

 

Includes the value providers for both retrieving values as is and transforming them. This makes it easier to push required data.[1]

 

Easier to scale when you have many sources because it allows for pushing data to many sources to handle locales and availability.[1]

❌

Requires the use of integration objects which may be non-trivial if you’re unfamiliar with these objects.

 

To keep the catalog up to date, you must constantly poll the SAP Commerce Cloud database for changes.

 

Requires creating new scripts to calculate computed attributes. Doing so may mean rewriting business logic that’s already present in pre-defined value providers.

Requires custom Java code if the available value providers aren’t enough for your needs.

1. This feature is only supported for SAP Commerce Cloud 2011 or later.

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. See Commerce fields for details on field management in a Coveo for Commerce use case.

  • Map the fields you want to populate. See Map commerce fields for details on field mapping in a Coveo for Commerce use case.

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 (for example, "path": "/Product/Products")

  • variant (for example, "path": "FootWearVariant/GenericVariantProducts")

  • availability (for example, "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.
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).

About the catalog entity

Behind the scenes, the SAP source uses the Stream API to push content to the Coveo index. Therefore, SAP sources must be associated with a catalog entity to ensure a complete configuration. This allows the source to accurately build a product vector space.

For instructions on how to create a catalog entity, see Commerce catalog entity.

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: