Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.