Delivery Configuration

Overview

Delivery configuration allows you to determine where messages are to be delivered.  Two types of delivery configurations exists: Custom and Known integrations.

Custom integrations allow you to have 100% control over the integration and allows you to deliver these messages to:

• A Kafka instance

• An EventHub instance

• An Http endpoint

• An Azure Blob

• Azure Tables

• A CosmosDb database

• A Message Sender

To leverage out-of-the-box integrations, you make use of the following Known integrations.

• The SearchIngestion API

• The Discover Event API

• The Send Event API

• The Mandrill API

• The Content Hub Integration

Known integrations can only be used with specific OrderCloud integrations points.  For example:

• The Search Ingestion API can only be used with the ProductSync feature.

• The Discover and Send Event API can only be used with the TrackingEvent feature.

• The Content Hub integration can only be used with the ProductSync feature.

All Custom integrations can be used with any of the above integrations.

When defining a delivery configuration you can send messages to multiple Custom Integrations with a single known integration.  For example, you could send the Send Event message to the Send collector API and also decide to send it to none, all or any of the custom integration endpoints.

The delivery configuration will be expanded in the future to support other known OrderCloud integrations.

Delivery Configuration Endpoints

Models

DeliveryConfig

1{ 
2  "ID": "", 
3  "Name":"", 
4  "Enabled": true | false, 
5  "DeliveryTargets": { } 
6}

 DeliveryTargets

1{ 
2  "Kafka": { }, 
3  "Http": { }, 
4  "EventHub": { }, 
5  "SendEvent": { }, 
6  "DiscoverEvent": { },
7  "AzureBlob": { } 
8}

Kafka

1{ 
2  "BootstrapServers" : "", 
3  "SaslUsername" : "", 
4  "SaslPassword" : "", 
5  "Topic" : "" 
6}

Http

1{ 
2  "Endpoint": "",
3  "Secret": ""
4}

The Secret enables the same functionality as defined for Webhooks.

EventHub

1{ 
2  "ConnectionString": "", 
3  "EventHubName": "" 
4}

AzureBlob

1{ 
2  "ConnectionString": "", 
3  "OverrideContainerName": ""
4}

The ConnectionString represents the storage account connection string.

AzureTable

1{ 
2  "ConnectionString": "", 
3  "OverrideTableName": ""
4}

The ConnectionString represents the storage account connection string.

CosmosDB

1{ 
2  "ConnectionString": "", 
3  "OverrideDatabaseName": ""
4}

MessageSender

1{
2  "Secret": "",
3  "EndPoint": ""
4}

The Secret enables the same functionality as defined for Webhooks.

SearchIngestion

1{
2  "Domain": "",
3  "Source": "",
4  "Endpoint": "",
5  "Entity": "",
6  "ApiKey": "",
7  "Content": {
8    "Locales": ["", ""],
9    "Http": {
10      "Endpoint": "",
11      "CustomAuthHeaderName": "",
12      "CustomAuthHeaderValue": ""
13    }
14  }
15}

In Sitecore Search, the locals are separated by an underscore character "_". Examples: "en_us", "fr_ca", "en_au"

The optional "Content" attribute provides support for Search locales. It allows customers to supply an endpoint that can supply locales and locale-specific attributes before sending the payload to the Search Ingestion API.

Initially, we support an HTTP endpoint that can provide the attributes.

The URL format is as follows: GET <endpoint>/{entity}/{ID}.

If the CustomAuthHeaderName and CustomAuthHeaderValue are specified, they will be passed in the header of the HTTP call.

For example, if the following is called: GET mycustomendpoint.com/product/P01.

The payload returned by this API must adhere to the following format:

1{
2  "DocumentID": "P01",
3  "EntityType": "product",
4  "Data": [
5    {
6      "locale": "en_us",
7      "fields": {
8        "name": "Name of the product.",
9        "description": "Description of the product."
10      }
11    },
12    {
13      "locale": "fr_ca",
14      "fields": {
15        "attribute1": "Le nom du produit.",
16        "attriubut2": "La description du produit."
17      }
18    }
19  ]
20}

The Data array has one entry for each of the supported locales of this product.

The following are reserved attributes names and will be removed from the API response if they are specified.

• active

• allsupplierscansell

• autoforward

• buyers

• catalogs

• categories

• category_names

• ccids

• defaultpriceschedule

• defaultpricescheduleid

• defaultsupplierid

• quantitymultiplier

• inventory

• inventoryrecords

• isparent

• marketplace

• ownerid

• party_price

• partypriceschedules

• returnable

• sellerdefaultpriceschedules

• shipfromaddressid

• shipheight

• shiplength

• shipweight

• shipwidth

• speccount

• suppliers

• supplier_inventory

• specs

• usergroups

• variantcount

SendEvent

1{ 
2  "SiteID" : "", 
3  "ServiceEndpoint": "" 
4}

 DiscoverEvent

1{
2  "ApiKey" : "" 
3  "ClientID": "", 
4  "ServiceEndpoint":  "" 
5}

Mandrill

1{
2  "ApiKey": ""
3}

AWS S3 Bucket

1{	
2  "AccessKeyId": "",	
3  "SecretAccessKey": "",	
4  "SystemName": "",	
5  "OverrideBucketName": "",	
6  "StreamEvents": true|false
7}

• StreamEvents appends a the current date/time stamp as part of the file name therefore avoiding file overwrites. This allows to use S3 Buckets as event streams or logs.

New Endpoints

• GET integrations/deliveryconfig

• GET integrations/deliveryconfig/{deliveryConfigId}

• POST integrations/deliveryconfig

• PUT integrations/deliveryconfig/{deliveryConfigId}

• PATCH integrations/deliveryconfig/{deliveryConfigId}

• DELETE integrations/deliveryconfig/{deliveryConfigId}

Custom Implementation Payloads and Models

If you decide to handle the integration, you will need to know what you will be receiving from OrderCloud. Each of the custom configurations used to trigger custom integrations will be composed of protocol specific information along with Common Models depending on the operation that triggered the event.

The event type is also transmitted as part of the data. This tells you what operation triggered the event and is also key to determine the type of model that is included in the payload. In OrderCloud the event type is represented as a namespace with the following values:

Delivery Target Payloads Structure

Http

1{ 
2  "Headers": {"type":"<value>"}, 
3  "ConfigData": {},
4  "Payload": {} 
5}

This configuration will transmit the payload and models to your implementation via a HTTP(s) post.

The ‘type’ can be found in the Header section of the body of the message.

The “ConfigData” represents any additional information you provided when you enabled the event to be published.

The Payload is dependent on the given ‘type’ as per the table described before.

The http header will contain the following:

• X-oc-hash - computed hash value using the provided secret as described for Webhooks.

EventHub

Enabling the EventHub config will transmit the payload via an EventData structure defined by Microsoft.

The ‘Properties’ collection contains the following information:

• type

• sitecoreorg

• marketplace

• tenant

The Payload is dependent on the given ‘type’ and is found in the EventBody of the EventData.

Kafka

Enabling the Kafka config will transmit the payload via a Kafka structure.

The libraries will prefix the extended properties with “ce_” and are the following:

• ce_type

• ce_sitecoreorg

• ce_marketplace

• ce_tenant

The Payload is dependent on the given ‘type’ and the name of the property is base on the Kafka library you use.

MessageSender

The payload is identical to the one described in the Message Sender documentation.

AzureBlob Containers

 The following containers are used when an AzureBlob delivery configuration target has been specified.

Still have questions?
Ask in our Community Channel

Content Powered By