...
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 |
|---|---|
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
| Info |
|---|
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.