DC 5.9 Automations

Introduction

Automations allow administrators to make the Digizuite™ DAM Center do things automatically - triggered as other things happen in the system. 
Automations replace the existing ItemWatcher workflows (And anything else that used to depend on the retired Digimonitor).

To interact with an automation, a Media Manager with at least version 5.2.0 is required. 

Automation construction

Automations are built with "steps". A step can be either an "action", a "trigger", a "filter", or a "foreach loop". 

Triggers

An automation is always started by a trigger. A trigger is a special kind of step that listens for events in the overall system, such as an asset being uploaded, or metadata changing.

Actions

To actually do something your automation needs actions. Actions all do one single thing, such as: updating a metadata field, or, triggering an asset publish event. 

Filters

To prevent the automation from firing all actions without any logic, a filter must be used.

Filters check that a condition in the Digizuite is met, e.g. that the asset type of an asset is an image, or that a member has a certain role.

If the condition is not met, the subsequent filters and action below it will not be executed.

Foreach loops

Lastly, there are loops, which is a special construct that allows for repeating a certain set of steps, over a set of data, executing the steps for each data point in the set. (This is very similar to how foreach loops are in other programming languages)

Creating a new automation

First of all, you need the proper roles to be able to access the automation menu point

To create a new automation, please do the following:

1. Press "Settings" in upper-right corner of the page
2. Next click on "Automation"

       3. Select "Create", and then either "Create new automation" or "Create automation from DSL" (the second option is for more advanced users)

       4. A menu will open to the left, where you can search for the desired trigger.

       5. In this menu, press "insert" on the type of trigger you want.

What each trigger does is documented at the bottom of this document. 

Using the visual editor

Once an automation has been opened in the editor, a flowchart-like view is shown.

If you selected "Create new automation" - only the trigger you choose will be shown.

If you selected "Create automation from DSL", the code editor will be shown instead.

Adding a new step

To add a new step to the automation, drag from the colored circle on the bottom of an existing step.

When you start dragging, a new node placeholder will appear. Drag your cursor onto this placeholder, and let go. 

When you let go, a pane will open on the left, where the step to insert must be selected. In this way, you can select all types of steps.

The step should now be inserted where the placeholder was.

For the step to be valid, you need to fill out the step's parameters.

This is done by pressing the "more" button on the step - and selecting "edit".

A dialog will now open to the right. 

In this dialog fill out the parameters, and select "apply" when done. 

Automation text syntax

Behind the flowchart-like UI, code is being generated by the actions you perform with the steps.

This code can be accessed by going pressing the "Text mode" button:

The code could, for example, look like the following:

trigger "Asset Uploaded" {
    type = "Asset Created Trigger"
    resolves = ["Move to User Profile Images", "Move to channel user profile folder"]
    upload_computer = "Digizuite Media Manager profile"
}

Each step is identified first by a keyword "trigger", "filter", "action", or "foreach", and then followed by a name in quotes. This name must be unique in the automation: trigger "Asset Uploaded"

The parameters for each step are saved in between the curly brackets: {}

Each parameter is identified by a key, an equal (=) sign, and then the value in quotes: upload_computer = "Digizuite Media Manager profile"
It is possible to have a set of values (aka. lists, arrays), by putting the values inside square brackets "[ ]", as seen from the "resolves" parameter: resolves = ["Move to User Profile Images", "Move to channel user profile folder"] 

A more formal version of the format can be seen in the following railroad diagram:

Most of the parameters for each step are dynamically generated. However, 3 parameters almost always appear (depending on the keyword used for the step).

"type" is required on all steps. It refers to the action or filter that should be run. In the example above "Asset Created Trigger" is the type, which means that it will trigger when an asset is created. The specified types available, are documented at the bottom of this document. 

Next we have "resolves", as seen in the above example. "resolves" is specified on all triggers, and refers to the last step in a chain of steps, that should be executed. 

Lastly, we have "needs", which is used on actions and filters. It refers to steps that should be executed before the step with the "needs"; thus creating a chain of dependencies (This must run before that).

Foreach loops

Foreach loops are a bit special since they allow for the repeated execution of a set (chain) of steps within an automation. To implement a foreach loop, you have to specify 5 parameters (The can, of course, be done from the visual, flowchart-like, UI):

• "type", which should be set to "ForEach".
• "resolves", which should be the last step in the chain of steps to execute. 
• "needs", which specifies all steps that must have run before entering the foreach loop. 
• "variable", which specifies which variable to iterate over. This accepts both one ("test 1") and many values (["test 1", "test 2", "test 3"])
• "as", specifies what "variable" should be available as, in each iteration of the foreach loop. I.e. the current variable in the list to interact with.

Variables

Automations use variables in order to pass data between different steps. Variables are identified by starting with an at-sign (@), for example, "@sourceAssetItemId". 

Triggers usually emit some variables, such as; the asset that triggered the automation.

To pass a variable to an action or filter, just write the variable name, such as "@sourceAssetItemId".

If you try to use a variable before it's ready, you will get an error when you run the automation. 

Some actions have "exported" variables. This means that rather than reading a variable before it executes, it sets the variable after it has executed. 

Tips and tricks

Required metadata fields (logic gate operators)

AND operator

"filter" steps below each other.

If two or more metadata fields are required before a given step should execute, you should position the filters below each other (i.e. make the automation linear rather than branching).

OR operator

"filter" steps beside each other.

If you have multiple fields, but only one of them is required, you should position the filters beside each other.