General information

The Integration Service provides an API where integration endpoints can register for notifications regarding predefined sets of changes in the Digizuite. This can conveniently be done through the UI in the settings section in MM5.

When registering an endpoint, a name and a URL where notifications should be sent to must be provided. Furthermore, it must be indicated which of the following change types the integration endpoint should receive notifications for:

An integration endpoint can subscribe to any subset of the four change types, but it must subscribe to at least one change type.

When subscribing to a change type, each time a corresponding internal event occurs, a notification will be sent to the URL registered for the integration endpoint. For instance, both AssetCreated and AssetDeleted events will trigger the same AssetChanged notification on all endpoints that subscribe to AssetChanged events. The events are debounced to avoid receiving too many identical change events over a short period of time. Thus, a small notification delay is to be expected. The debouncing interval can be configured by adding the following section to the appsettings.json file of the Integration Service:

"Debouncing": {
  "Interval": "<TIMESPAN>"
}

TIMESPAN could for instance have the value 00:00:07, if the debouncing interval should be set to 7 seconds. The default value is 5 seconds.

Note that, it is possible to provide custom headers for the notification HTTP messages when registering an integration endpoint. This, however, is optional.

When using the API, make sure that your user has the required roles for the requested endpoint. In particular, the roles “Integration_Endpoints_View” and “Integration_Endpoints_CRUD” are required for a lot of the endpoints.

Note that, it is also possible to get, retry, and delete failed messages with the API.

Notifications

Notifications are, by definition, push-based. Thus, for an integration endpoint to receive notifications it should listen for incoming HTTP POST messages at the registered URL. An integration endpoint should respond with a 200 OK to successfully received notifications. A notification generally has the following JSON-formatted body:

{
  "ChangeType": <the change type of the event>,
  "Data": {
    "ItemId": <itemId of the item that triggered the event>,
    "BaseId": <baseId of the item that triggered the event>
  }
}

The value of the “ChangeType” parameter is an integer, which is used to identify its change type. See the constants in the table above. The value set in “BaseId” depends on the change type:

Error handling

Internal errors can be found in the RabbitMQ error queue of the Integration Service.

If an error occurs while sending a notification to an integration endpoint, e.g. if the integration endpoint is not available, the error does not end up in RabbitMQ but is instead recorded internally. Failed notifications can easily be seen, retried, and deleted through the UI in the settings section in MM5.