Managed integrations

Managed integrations are essentially webhook integrations pushing events to external recievers over https. It support pushing asset events on the below actions

Create
Update
Delete

The reason for the naming managed integration is because the system keeps a state on the assets that is being syncrhonized which means the system can be intelligent on when the asset event is important for the given integration (i.e. if nothing of interest has been updated, disregard the event).

On top of this managed integration allows the integration to provide a custom configuration model (i.e. a Json scheme) that can be populated through the KeyShot management UI.

This type of integration should be used for automatic integration running in the background that does not require user interaction. Typically this type of integration is used to syncrhonize data between two systems. An example of this is Product information management systems (PIM).

Architecture

Managed integrations are following the below execution pattern

Everything is initiated from KeyShot Dock by a change. This change is reflected in an event and can be anything happening to assets such as

Uploads / replaces
Metadata updates
Security updates

The reason for the name managed is that the integration keeps track on what assets has been syncchronized and based of the event determines if the integration should be notified or not. If the event is not relevant, for instance because the metadata changed is not included in the request to the integration, then the event is skipped.

If the event is relevant, the integration code is notified.

The integration code exposes a https endpoint that receives the event which includes

A state of the asset if the asset has previously been updated
Configuration defined by the integration
The asset data
An event type
- Create / Update events (determined by the state)
- Delete events

The integration code varies from integration to integration, but does something in an external system based of the event. Once the event has been processed by the integration, the integration responds back with an updated state which can be used later to determine if the asset event is an update or create event. The state is custom data defined by the integration code. Examples of this could be the unique identifier in the external system allowing the integration to lookup the asset if it is already synced into the system.

Setup a managed integration

Setting up a managed integration can be done through API or UI.

In both cases the following things are available

Property	Description

Property	Description
Name	Display name for the integration
Enabled	Flag for enabling the integration
Endpoint URL	The URL on which the integration is invoked
Additional metadata fields	If more than the standard asset event is needed, this can be used to pass additional metadata to the integration. This is also checked to validate if the event should be sent in the first place. If the change happened on a metadata field which is not included here, then the event is skipped
Trigger on format change	This is used to determine if the event should be sent of not. If it has a value, then the integration is invoked if the format is (re)generated for the asset
Always trigger integration	If true, all event validation is skipped and the event is always sent.
Asset filter	A set of filters setup to determine if the event is relevant or not. This can be used to only trigger the integration if the asset is published to a given distribution channel
Custom headers	Add additional headers in the request. As an example this can be used for security headers.
Language	The language in which the metadata is needed. If multiple languages are needed, then either setup two Managed integrations or fetch the additional data in the integration code. Defaults to system language
Max batch size	How many assets to bulk in one request. Defaults to 200
Request timeout	Timeout on the https request. Defaults to 100
API User	The user with which the asset data is requested. The asset data that is requested for the integration is done by impersonating a user. This is done to not leak any data and ensure security is respected. Defaults to the logged in user
Integration configuration schema*	A Json schema defining the configuration used by the integration
Integration configuration	The configuration for the integration. This could be API keys, behavioral properties and more. If a configuration json schema is provided, the UI uses this to validate that the provided configuration is correct.

*Not available through UI

KeyShot does not guarantee the security for custom integration and as such this must be considered by the implementor. Remember to secure all endpoints!

API Docs for the above endpoints are available on

http(s)://<company KeyShot Dock api>/DigizuiteCore/IntegrationService/api-dpcs

See reference for /api/v1/managed-integrations

Tracking assets

Once the integration has been registered all assets that are synchronized are tracked. The tracked assets can all be found in the Actions column in the Managed integration overview in KeyShot Dock

The warning triangle gives all the failed assets. In this view the reason for the failure can be seen and the asset can be retried.

The list icon provide all the successfully tracked assets. Similarly to the failed overview the assets may be forced to re-sync. Additionally this view provides a Sync all assets button. Be careful when clicking this as this executes a full re-synchronization of all assets matching the provided asset filters for the integration.

Rest API

The API that must be made available configured to receive events on the Endpoint URL must follow the below description.

It must be a POST API that takes the following JSON input

{
    "actions": [
        {
            "type": "<sync type>",
			"asset": <the full asset response object>
            "integrationState": <integration state as json string>,
            "assetStateHash": <hash of the saved integration state>,
            "assetId": <asset id>
        }
    ],
    "configuration": <the configuration object provided when registering the endpoint>
    "tenantId": <tenant id>,

where the parameters are described as follows

Parameter	Description

Parameter	Description
`actions`	An array of asset sync actions. See below
`Configuration`	If custom configuration is supplied. This is included in this property.
`TenantId`	Value controlled by KeyShot describing the tenant.

The actions are defined as follows

Parameter	Description

Parameter	Description
`type`	The sync type. Can be sync delete where sync covers both create and update. If the state is not null then the asset is tracked and hence the sync can be considered an update
`asset`	This is the full asset response object. See example in API documentation DC 5.10 Getting assets by Id
`integrationState`	This is a state managed by the integration. See description below
`assetStateHash`	This is a hash of the above state
`assetId`	The assetId of the asset being synced

The integrationState is an object controlled by the integration. For the KeyShot API it is just serialized into a json string and saved in the database. This state is then parsed along in the API request if the asset has already been synchronized before. This means that the integration it self controls what is in the state and it receives it on update to be used to determine what should happen with the asset.

Examples of what could be included in the state

Unique identifiers of external system
Asset hash (to determine if files should be updated)

And other properties that can be used to determine how the sync should be handled.

The response to the API must return a 200 OK status code and the following JSON output

{
    "Items": [
        {
            "AssetId": <assetid of sync>
            "IntegrationState": <Json string of integration state>
        }
    ]
}

Where each item corresponds to a sync action and must contain the assetid and the JSON string value of the corresponding sync state.