Integrating Bizzkit CMS and Ecommerce Search

Setup

Follow these steps to set up the integration between Ecommerce Search and Bizzkit CMS

1. Using the Courier API
   1. Create an API key (POST /courier-api/bizzkit-cms/api-keys).
2. In Bizzkit CMS.
   1. Go to the model in Bizzkit CMS containing pages.
   2. In the Fields tab, add the following fields: title, description, openGraphTitle, openGraphDescription. These will be imported into Ecommerce Search as title and description. Open Graph fields will be used if filled, with a fallback to title and description (Optional).
   3. In the Fields tab, add the custom fields that should be imported as attributes on the content pages, and make a note of their names. See Importing custom fields as attributes (Optional).
   4. Go to "Advanced"
   5. Make a note of the Model id and Unique identifier
   6. Add a Webhook under "Webhook" -> "Edit"
   7. Enter the url: "/courier-api/bizzkit-cms/content-web-hook".
   8. Add Custom Header, and Enter "api-key" and the secret from the first step as the value.
   9. Press "Done".
   10. Press "Save".
   11. Go to "Settings" and find the "Public API Key". Make a note of it.
3. Using the Courier API
   1. Using the Bizzkit CMS settings endpoint (POST /courier-api/{segmentId}/bizzkit-cms/settings). Create the Bizzkit Cms Setting using the Model id, Unique identifier, public API Key, and the locale of the chosen segment. Leave the locale empty if the page models only contain one language. It is possible to use more than model. If there are url conflicts between the models, then the order of the models are the tie breaker. If there are multiple sites in the same space, set the required targets on the settings model. Note all pages must have all the required targets otherwise they are ignored. Each model can also declare the fields to import as attributes, see Importing custom fields as attributes.
   2. To change an existing integration, use the update endpoint (PUT /courier-api/{segmentId}/bizzkit-cms/settings/{settingId}). It replaces the settings with the values in the request, so the request must carry the complete settings. Omitting the required targets, or the fields of a model, removes them. The changes take effect on the next synchronization.

Page creation, updates and deletions are now synced from Bizzkit CMS to Ecommerce Search.

Importing custom fields as attributes

Besides the fields that are always imported, each content model in the Bizzkit CMS settings can declare which of its custom fields to import. A declared field becomes an attribute on every content page imported from that model, and can then be used for filtering and faceting the content pages. Fields that are not declared are not imported.

A field is declared with three properties:

• name is the name of the field in Bizzkit CMS. It is also the id of the attribute in Ecommerce Search.
• label is the name of the attribute in Ecommerce Search.
• type is the type of the attribute, either String or Number. It defaults to String.

Field types

The type must match the type of the field in Bizzkit CMS:

Fields of type Long text, Boolean, Reference, and File are not imported. Neither are title, description, openGraphTitle, openGraphDescription, and the blocks of the page, as the integration already imports those.

For a string attribute the value is also the id of the value, so a string value can be at most 64 characters long.

Declaring the fields

The fields are declared on the model they belong to, on the settings sent to POST /courier-api/{segmentId}/bizzkit-cms/settings or PUT /courier-api/{segmentId}/bizzkit-cms/settings/{settingId}:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
    "publicApiKey": "1a2b3c4d5e6f7890abcdef1234567890",
    "models": [
        {
            "modelId": "a1b2c3d4e5f67890abcdef1234567890",
            "modelName": "article",
            "fields": [
                { "name": "topic", "label": "Topic", "type": "String" },
                { "name": "publishedAt", "label": "Published at", "type": "Number" }
            ]
        }
    ],
    "locale": "da-DK"
}

An article whose topic is "Logistics" then has a string attribute topic with the value "Logistics", and a number attribute publishedAt holding the timestamp.

A model can declare at most 50 fields, and the name of a field must be unique within the model.

Values that are not imported

Ecommerce Search does not ask Bizzkit CMS for the type of a field, so a type that does not match the field is only visible as a missing attribute. Each value is imported on its own, and a value is skipped when

• it is not of the configured type,
• it is a string longer than 64 characters, or
• it is empty.

The page itself is still imported, and a field whose values are all skipped results in no attribute on the page.

A localized field is imported with the value for the locale on the settings, falling back to the default value in Bizzkit CMS. A localized field with neither of the two contributes nothing.

Limitations

The integration between Ecommerce Search and Bizzkit CMS has the following limitations

• Pages with Targeting other than UrlPath and required targets will be ignored and will not be searchable.
• Split testing is not supported.
• Custom fields of type Long text, Boolean, Reference, and File are not imported.