Custom automations steps

KeyShot has a customizable automation engine which allows complex tasks to be executed automatically in the background based of events. Automations has three main building blocks

Triggers – Initiate the automation based of an event
Filters – Execute this branch of the automation only if a condition is true or false
Actions – Do something (e.g. set metadata)

Custom automation steps allows creation of custom Filters and Actions.

Behind all of this a custom automation step is a https request to a hosted endpoint which allows the implementor to either create a custom filter or custom action that can be utilized in the existing Automation engine setup.

This type of integration is used typically for the smaller tasks that would require some degree on automations. Examples of this could be

Validating that a product exists in an external system (e.g. PIM)
Enriching metadata with AI
Enriching uploaded content (e.g. Remove background with AI)

Architecture

Custom automation steps are following the below execution pattern

Similarly to managed integration then everything is initiated by a change in KeyShot Dock. Changes spawn events that can be used to trigger automations. Automations are configurable flows allowing for very complex automated tasks to be executed.

When hooking in to the automation engine it allows the integrator to make

Filters
Actions

But not triggers.

Filters are used to determine if a branch in the automation should be executed or not. For that reason a custom filter defines are set of input parameters that are used in the custom code to determine a true/false value that must be returned.

Actions are used to execute a task. Actions defines a set of input parameters that are used for the integration to execute an automated task. In contrast to Filters, actions can also define one or more output parameters which can be sent back to KeyShot Dock and used for further execution in the Automation.

The actual integration, regardless of it being a filter or action, is a rest API endpoint that can either be a proxy or an actual system responsible for delegating or doing the custom filtering or action based of the given input.

Setup a custom automation step

Setting up a custom automation step is only available through API and hence the custom step must register it self on start up.

The API doc is available on the following url, see custom-step-definitions

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

The following input must be defined

Property	Description

Property	Description
Name	The name of the step. This is used in the UI
Description	A small description of the step. This is used in UI
InvocationURI	This is the URL to the rest API endpoint.
SecretHeaderValue	Optional value which will be sent in the headers. This is used for security headers
RuleType	Action (3) or Filter (2)
InvocationTimeout	Defaults to 30000ms
Parameters	See below

Parameters contains a list of all the parameters used in the Automation. These are defined as follows

Property	Description

Property	Description
Key	Name of the parameter. Must be snake_case!
Description	A small description of the step. This is used in UI
Type	Defines the input type. The following values are available `public enum CustomStepParameterType { String, Bool, Int, Double, Guid, DateTime, ComboValue, TreeValue, MetaField }`
IsList	Defines if the parameter is a list or not
Exported	If true, this is an output value and if false it is used for input

Rest API

The Rest API that is executed must be a simple POST endpoint on the configured invocationUri. The body must include all the parameters where exported is defined as false as follows

{
  {
    "input_parameter_1":"value1",    
    "input_parameter_2":"value2",    
    "input_parameter_3":3,      
  }
}

The return value depends on the ruleType where 2 is a filter and 3 is an action

For filters rest API must return the following json

{  
  "Passed":<true / false>,              
}

Indicating whether the filter has passed or not.

For actions the rest API must return a value for each of the parameters where exported is defined as true. If no parameters are marked as true

If the automation should fail, the API must return something outside of the 200 status codes.