General information

The Integration Service provides an API where integration endpoints can register for notifications regarding predefined sets of changes in the Digizuite.

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, a notification will be sent to the URL registered for the integration endpoint each time a corresponding internal event occurs. Thus, an AssetCreated and an AssetDeleted event will, for instance, both trigger an identical AssetChanged notification to all endpoints that subscribe to AssetChanged events.

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.

Detailed Swagger documentation can be found at “/api-docs”.

Notifications

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

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

The value of the “ChangeType” parameter is an integer, which is used to identify a change type. The mapping between ChangeTypes and their integer representations can be retrieved at “/IntegrationService/ChangeTypes”. For each of the change types, an additional data parameter is provided. The additional IDs are: