Automation / Tasks and Schedule Tasks

REST Endpoints

Tasks : REST API documentation
Schedule Tasks : REST API documentation

Dependencies / in-Parameters

`in_project_shortid`

The task is only executed if the event node is in this project.

`in_catalogue_shortid`

Execute task if node of event is in this catalogue.

`in_node_shortid`

Execute task if the node of event is 'in_node_shortid'

`event_category`

The task is execute if the category of an event matches.

`min_event_count`

An associated task if executed only if the number of valid events reaches this number. If this number is set, member 'out_authorization' supports 'creator' (of the task) only.

`max_event_age`

Conditions

out-Parameters

out_authorization
Call the out-endpoint with this user authetication/authorization. Could be one of [ 'creator' of task , 'generator' of event ]

Variable Interpolation in `preflight` and `out_requestbody`

The property out_requestbody defines the request-body that an event will pass to the allocated endpoint ( out_service_url ).
In many cases our output depends on various informations given by an event.
To reference this information we can use a simple syntax to be interpolated by the Taskrunner executing a task.

To reference variables available for interpolation one can use the '%%'-Prefix.

In most cases the following list of Variables should be available:

- %%project_shortid - The shortId of the Project the event occured in
- %%catalogue_shortid - The id of the catalogue the event occured in
- %%node_shortid - The id of the node the event occured in
- **%%node_path** - The path of the node the event occured in
- **%%full_path** - the full path of the node the event occured in
- **%%object_type** - the type ot the object the event occured in
- **%%url_path** - the url of the endpoint that documented the event
- **%%verb** - the Operation (read: Rest-Verb; POST, GET, etc...) that was called on the endpoint that documented the event
- **%%response_data** - the response that was issued on the event
- **%%preflight_data** - the response that was issued on the event
- %%status_code - the status-code that the event resulted in
- %%event_category - the events category.

Possible values are:
object, node , property, file, annotation, project, catalogue, permissions, role, group

- **%%createdon** - the iso date of when the event was created
- **%%createdby** - the user who commited the action that led to the creation of the event
- **%%updatedon** - since events should not ever be modified: this should effectivly be the same as createdon
- **%%updatedby** - since events should not ever be modified: this should effectivly be the same as createdby

One notable properties here are **%%response_data** and **%%preflight_data**, since this will most likely be a JSON Body containing relevant data.
To access properties of this data we can simply use the dot-notation to traverse the object.

As an example: Let's say we created a task that should fire, when a special type of object is updated and the aim of the task was to send an email to a given recipient containing the name of the object that has been update.
If the Response given to the update request locked as follows:

    { 
          "status": 200,
          "data": {
              "new": { },
              "updated": { 
                "name": "MyCollection" ...[SOME_PROPS]: [SOME_VALUES] 
              } 
          }    
    }

The properties can referenced by using the variable %%response_data and traversing it via dot-notation, i.e if we were to fetch the name we could do so by using this expression:

      %%response_data.data.updated.name

For our example the out_requestbody property could look something like this: \n\n ` \"out_requestbody\": \"{ recipient: [\"max@colneo.email\"], \"subject\": \"%%response_data.data.updated.name changed\" \"message\": \"FYI: Inside your Project %%project_shortid the object %%response_data.data.updated.name was updated by %%createdby.\" }\" ` \n\n ## Data Operations
There may be cases in which the Data of a Property needs to be transformed. Currently there is one such operation implemented:
the transformation of an Array of objects into a List where each object is represented by a key property.
As an example, let's say the response_data of a fileupload looks like this: \n\n `{ [...] \"response\": { \"status\": 201, \"data\": {\"message\": \"Files uploaded.\", \"files\": [{ \"file_name\": \"file01.txt\" ...[OTHER_PROPS]: OTHER_VALUES }]}}} ` \n\n We can try to output a list of filenames using the following syntax: \n\n `%%response_data.response.data.files::LIST::file_name` \n\n The first part is, as we have seen above, depicting the Property to be used. The experimental advanced syntax allows us to define, which Data-Mutation is called on the property. The Syntax works as follows: \n\n ` %%path.to.property::OPERATION::argument` \n\n At the moment the **only** operation existing is the **LIST** operation.
The Argument it expects, depicts which property of the given array-elements it should use to construct the text-list. Given the input above (LIST::file_name), the *LIST* operation would traverse the array and for each object, add the given property *file_name* to the list. It would then construct a html text-string to replace our placeholder like so:

file01.txt
file02.txt
fileXY.txt

Special Keywords: %%ROLE::ID and %%GROUP::ID

Two further special interpolation properties are the **%%GROUP::ID** and **%%ROLE::ID** Keywords The **ROLE** Keyword fetches a list of all users that have that Role while the **GROUP** Keyword returns a list of all users that are currently part of the given Group The Keywords both expect the respective **ID** to be given after the **::** \n\n ` E.g: %%ROLE::123456 ` \n\n The List is interpolated into an array of strings, so it could be used like so: \n\n ` \"out_requestbody\": \"{ recipient: \"%%ROLE::SOME_ID\" } ` \n\n \n\n
# Variable Interpolation in conditions \n The property conditions can be used to define further conditions on a task execution.
These conditions are checked before a task execution. If the conditions are statisfied, the task is executed, otherwise the event is ignored and an execution with the StatusCode -1 is written, so that the event does not have to be checked again.

The basic form of one of these expressions is an array in the following format: \n\n ` [ prop, operator, value ] ` \n\n **prop** and **value** can both be values of type *'string'*, *'number'* or *'boolean'*.

Additionaly they can both contain the same interpolation attributes that are available inside the **out_requestbody** property *(see Paragraph above)*.

Supported operators are: **'=','!=','>','>=','<','<=','in'**
They correspond to their Javascript Counterpart whereas the 'in' operator corresponds to the 'includes'-Function

On String Properties: * '=' : Asserts strong equality (is string a equal to string b) \n * '<' : Makes a character by character comparision on the characters (char) values \n * '>' : Makes a character by character comparision on the characters (char) values \n * 'in': Checks if the prop-string can be found as substring in the value-string. Corresponds to JS string.includes funtion \n
On Number Properties: * '=' : Asserts strong equality (is a equal to b) \n * '<' : Works as the Less-then operator is expected to \n * '>' : Works as the Greater-then operator is expected to \n * 'in': will always evaluate to false if used with a number value-attribute \n
On Boolean Properties * '=' : Asserts strong equality (is a equal to b) \n * '!=' : Asserts strong equality (is a equal to b) \n
Using the **%%ROLE::ID** or **%%GROUP::ID** Keywords we can also create a FilterExpression using an Array Data-type. *The only sensible use for this is to use the Keywords as **'Value'-Expression** with the **'in'** Operator* Here we could, for example, use it to construct something like the following constain: \n\n ` ['%%createdby', 'in', '%%GROUP::RELEVANT_GROUP_ID'] `

## Constructing the FilterStatement from Expressions and Logical-Operators The Statements are expected to contain a double layerd structur in which Expressions can be chained with Logical-Operators.

The Available Operators are:
\"or\" & \"and\"
Double Layerd means, that the Datastructure is a two dimensional array (an array of arrays, so to speak) wherein the inner Array alternatingly contains FilterExpressions and Logical-Operator and the outer Array thus alternatingly contains Sets of FilterExpressions and Logical-Operators.
To make it clearer Consider this simple example:

` [ [ ['%%createdby', '=', 'max@colneo.email'], 'or', ['%%createdby', '=', 'mia@colneo.email'] ], 'and', [ ['%%enabled', '=', true] ] ] ` \n\n The expresions for the %%createdby Property are both group into one inner set so we can connect them with the 'or' condition whilst connecting both with an additional 'and' condition in that the property 'enabled' is true In effect the inner Expression-Set depicts a set of braces to structure the boolean logic that is used to evaluate the filter.
The above example would thus effectively result in an expression like this. \n\n ` if ( (createdby === 'max@colneo.email' || createdby === 'mia@colneo.email') && (enabled = true)) `

"

Automation / Tasks and Schedule Tasks

REST Endpoints

Dependencies / in-Parameters

in_project_shortid

in_catalogue_shortid

in_node_shortid

event_category

min_event_count

max_event_age