Delivery Configuration
Published by Marc Bednar on June 28, 2023
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}
SendEvent
1{2 "SiteID" : "",3 "ServiceEndpoint": ""4}
DiscoverEvent
1{2 "ApiKey" : ""3 "ClientID": "",4 "ServiceEndpoint": ""5}
Mandrill
1{2 "ApiKey": ""3}
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:
Namespace | Description |
---|---|
Sent when a product has been created or updated. | |
Sent when a product is deleted. | |
Sent when a line item is added to an order. | |
Sent when a line item is updated in an order. | |
Sent when an order is submitted. | |
Sent when a user logs in and has been identified. | |
Sent when an order is updated and OrderSync has been enabled. | |
Sent when an order is deleted and OrderSync has been enabled. | |
Sent with a category has been updated. | |
Sent when a category is deleted. | |
Sent when an admin user is updated. | |
Sent when an admin user is deleted. | |
Sent when a buyer user is updated. | |
Sent when a buyer user is deleted. | |
sitecore.ordercloud.messages.entitysync.inventoryrecord.updated | Sent when a single inventory record has been changed. |
sitecore.ordercloud.messages.entitysync.inventoryrecord.full.updated | Sent when a full inventory record sync has been initiated. |
sitecore.ordercloud.messages.entitysync.supplieruser.updated | Sent when a supplier user is updated. |
sitecore.ordercloud.messages.entitysync.supplieruser.deleted | Sent when a supplier user is updated. |
Sent when a supplier is updated. | |
Sent when a supplier is deleted. | |
sitecore.ordercloud.messages.messagesender.{MessageType} | Send when a message sender is triggered. Represents one of the message types defined in the Message Sender documentation. |
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.
Container | Description |
---|---|
entitysync | Entities synched via EntitySync located. Sub folders are created for the various entity types. |
logs | ErrorConfig logs. |
orders | OrderSync orders. |
products | ProductSync products. |
trackingevents | TrackingEvents events. |
webhooks | Webhook payloads when webhooks are configured to use delivery configurations to deliver messages. |
Still have questions?
Ask in our Community Channel