Skip to main content

Action parameters

Use parameters to populate action attributes

The attributes of each workflow action are defined by its design.

When using the API to add (Swagger/ReDoc) or edit (Swagger/ReDoc) an action node, supply a parameter for each attribute required by the action's design, along with any other attributes you want to populate.

A parameter can be defined using one of three web models:

  • Constant - set a known static value.

  • Computed - set a computed value using data from the current node, another node, time offset or computation script.

  • Virtual (deprecated) - use a templated string to set a value using data from the current node, another node or time offset.

Every parameter includes a discriminator property to indicate the model used.

Constant web model

Use WorkflowConstantItemAttributeWebModel to define a parameter that sets a known static value.

For example, set MyNumberAttribute to "42".

"parameters": [
{
"attribute": {
"attributeCode": "attributes_designMyNumberAttribute_5f06170ac3ca920067f1d829",
"value": 42
},
"discriminator": "WorkflowConstantItemAttributeWebModel"
}
]

Computed web model

Use WorkflowComputedItemAttributeWebModel to define a parameter that sets a computed value.

"parameters": [
{
"attribute": {
"attributeCode": "attributes_designMyExampleAttribute_64062f0a690787036ea78a04",
"value": {
...
"discriminator": ...
}
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

The value property can hold one of several models, depending on the type of computation.

Computation typeValue model
Input to current/previous nodeWorkflowSyntaxNodeInputWebModel
Output from any nodeWorkflowSyntaxNodeOutputWebModel
Time offsetWorkflowSyntaxNodeRelativeTimeWebModel
Result of a scriptWorkflowSyntaxNodeScriptWebModel
Result of an AQS queryWorkflowSyntaxNodeAqsWebModel
Templated stringWorkflowSyntaxNodeTemplateWebModel
Trigger parametersWorkflowSyntaxNodeTriggerParameterWebModel

Input to current/previous node

Use a WorkflowSyntaxNodeInputWebModel to get a value from the input item(s) of the current node or one that preceded it.

For example, set MyGeometryAttribute to the value of the Geometry attribute on the related input item of the 1st parent node.

"parameters": [
{
"attributeCode": "attributes_designMyGeometryAttribute_5f06170ac3ca920067f1d829",
"value": {
"inputParent": 1,
"itemValue": {
"attributeCode": "attributes_itemsGeometry",
"discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel"
},
"discriminator": "WorkflowSyntaxNodeInputWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

The inputParent property determines the number of parent hops from the current node. To reference the input of the current node, set this to 0.

The itemValue property can hold one of several models:

WorkflowSyntaxArgumentItemValueAttributeWebModel

Use this model to get the value of an attribute on the input item(s).

"itemValue": {
"attributeCode": "attributes_itemsGeometry",
"discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel"
}
WorkflowSyntaxArgumentItemValueItemPropertyWebModel

Use this model to get the value of a property on the input item(s):

  • ItemId - get the item's ID, e.g. 66a3bfa76b3182e633118a72

  • DesignCode - get the item's design code, e.g. designs_projects

  • Implements - get an array containing the interface(s) implemented by the item's design, e.g. ["designInterfaces_projects", "designInterfaces_items"]

"itemValue": {
"property": "ItemId",
"discriminator": "WorkflowSyntaxArgumentItemValueItemPropertyWebModel"
}
WorkflowSyntaxArgumentItemValueVariableWebModel

Use this model to get the value of a variable that's been declared on the specified node.

"itemValue": {
"variableName": "variableOnThisNode",
"discriminator": "WorkflowSyntaxArgumentItemValueVariableWebModel"
}

Output from any node

Use WorkflowSyntaxNodeOutputWebModel to get a value from the output item(s) of any node in the workflow.

For example, set MyGeometryAttribute to the combined values of the Geometry attribute on the output item(s) from a specific node.

"parameters": [
{
"attributeCode": "attributes_designMyGeometryAttribute_5f06170ac3ca920067f1d829",
"value": {
"outputAction": "5f05f85cc3ca920067f1d7a0",
"outputMode": "All",
"itemValue": {
"attributeCode": "attributes_itemsGeometry",
"discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel"
},
"discriminator": "WorkflowSyntaxNodeOutputWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

The outputAction property determines the target node in the workflow. Set this to the node's ID.

The outputMode property determines which output items are processed:

  • All - all items outputted by the specified node.

  • Input - only the output items that follow the current input chain.

outputMode example

Imagine three items of MyDesignA with a DesignAString attribute set to "item1", "item2" and "item3" respectively. A fourth item of MyDesignB has a DesignBLink attribute linking to item2 and item3.

Now imagine a workflow is triggered on those three items. The trigger node passes them to a Relation action, which follows the DesignBLink attribute to the parent item4. item4 passes to a Message action, which gets the output items of the trigger node. A message is sent containing each output item's DesignAString attribute.

If outputMode is set to "All", the message will contain item1, item2, item3.

If outputMode is set to "Input", the message will contain item2, item3.

The itemValue property can hold one of several models:

WorkflowSyntaxArgumentItemValueAttributeWebModel

Use this model to get the value of an attribute on the output item(s).

"itemValue": {
"attributeCode": "attributes_itemsGeometry",
"discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel"
}
WorkflowSyntaxArgumentItemValueItemPropertyWebModel

Use this model to get the value of a property on the output item(s):

  • ItemId - get the item's ID, e.g. 66a3bfa76b3182e633118a72

  • DesignCode - get the item's design code, e.g. designs_projects

  • Implements - get an array containing the interface(s) implemented by the item's design, e.g. ["designInterfaces_projects", "designInterfaces_items"]

"itemValue": {
"property": "ItemId",
"discriminator": "WorkflowSyntaxArgumentItemValueItemPropertyWebModel"
}
WorkflowSyntaxArgumentItemValueVariableWebModel

Use this model to get the value of a variable that's been declared on the specified parent node.

"itemValue": {
"variableName": "variableOnThisNode",
"discriminator": "WorkflowSyntaxArgumentItemValueVariableWebModel"
}

Time offset

Use a WorkflowSyntaxNodeRelativeTimeWebModel to compute a value by offsetting either the current date/time (of which there are several definitions) or a stored date/time value.

For example, set MyDateTimeAttribute to "86400000" milliseconds (24 hrs) after the workflow was scheduled to trigger.

"parameters": [
{
"attributeCode": "attributes_designMyDateTimeAttribute_5f06170ac3ca920067f1d829",
"value": {
"offsetMilliseconds": 86400000,
"offsetOrigin": "Scheduled",
"type": "DateTime",
"condition": ...
"discriminator": "WorkflowSyntaxNodeRelativeTimeWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

The offsetMilliseconds property determines the duration before (negative) or after (positive) the origin time.

The offsetOrigin property defines the start time for the offset. Set this to:

  • Started - when the workflow started running.

  • Triggered - when the workflow was triggered.

  • Scheduled - when the workflow was scheduled to run.

  • Specified - a date and time value specified in the itemValue property.

The itemValue property is only relevant for Specified. It can hold one of several models:

WorkflowSyntaxArgumentItemValueAttributeWebModel

Use this model to get the value of an attribute on the input item(s).

"itemValue": {
"attributeCode": "attributes_itemsGeometry",
"discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel"
}
WorkflowSyntaxArgumentItemValueItemPropertyWebModel

Use this model to get the value of a property on the input item(s):

  • ItemId - get the item's ID, e.g. 66a3bfa76b3182e633118a72

  • DesignCode - get the item's design code, e.g. designs_projects

  • Implements - get an array containing the interface(s) implemented by the item's design, e.g. ["designInterfaces_projects", "designInterfaces_items"]

"itemValue": {
"property": "ItemId",
"discriminator": "WorkflowSyntaxArgumentItemValueItemPropertyWebModel"
}
WorkflowSyntaxArgumentItemValueVariableWebModel

Use this model to get the value of a variable that's been declared on the specified node.

"itemValue": {
"variableName": "variableOnThisNode",
"discriminator": "WorkflowSyntaxArgumentItemValueVariableWebModel"
}

The type property lets you format the computed time offset as an attribute type, e.g. Date, DateTime, Time, Seasonal, String, Number, Json. This is useful if you intend to store the value or compare it with another of the same type. If left blank, the outputted value will be a raw integer.

The condition property holds a WorkflowTimeConditionWebModel that determines how the offset will be computed (no discriminator required).

WorkflowTimeConditionWebModel

Use this model to specify days or time periods that should be ignored when computing the offset.

  "condition": {
"workingDaysTimeConditionType": "OnWorkingDays",
"exceptions": [
{
"start": "2023-09-06T10:41:22Z",
"end": "2023-09-06T12:41:22Z"
}
]
}

The workingDaysTimeConditionType property determines which days the offset applies to. Set this to OnWorkingDays, OnNonWorkingDays or Both.

The exceptions property lets you define one or more time periods where the offset doesn't apply.

When the offset is computed at runtime, it will skip over any days or time periods that it doesn't apply to. For an illustration, see Dynamic action values.

Result of a script

Use a WorkflowSyntaxNodeScriptWebModel to compute a value from a script. The script syntax is a subset of C# with limited access (for security purposes). A set of helper functions are available in the class that the script executes.

For example, set the Total Points attribute to the sum of the numbers in the taskPoints variable.

"parameters": [
{
"attributeCode": "attributes_designTotalPoints_5f06170ac3ca920067f1d829",
"value": {
"script": "return Elements(taskPoints).Sum();",
"returnOptions": ...
"discriminator": "WorkflowSyntaxNodeScriptWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

The returnOptions property can hold one of several DodiAttributeOptionsWebModels that specify extra information about the return type of the script. For details, see Swagger/ReDoc.

Example - Load items from a variable

The output of a variable can be ambiguous. If it returns a list of Item IDs, their design is unknown unless explicitly stated. In these situations, use the returnOptions property to . Otherwise, this will result in an error at runtime.

For example, imagine a tasks variable is declared on a Create Item action. It gets the task items from the project item received as input on the parent node.

"variables": [
{
"name": "tasks",
"value": {
"inputParent": 1,
"itemValue": {
"discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel",
"attributeCode": "attributes_projectsTasks"
},
"discriminator": "WorkflowSyntaxNodeInputWebModel"
}
}
]

Using a parameter, we want to add those tasks to the Tasks attribute of the new Projects item. From the script's perspective, the stored Item IDs relate to the basic Items interface. However, the attribute only accepts Item IDs from designInterfaces_tasks, not from designInterfaces_items. Therefore, we must reclassify them accordingly.

"parameters": [
{
"attributeCode": "attributes_projectsTasks",
"value": {
"script": "return tasks",
"returnOptions": {
"code": "designInterfaces_tasks",
"graph": "Project",
"discriminator": "DodiAttributeOptionsLinkWebModel"
},
"discriminator": "WorkflowSyntaxNodeScriptWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

Result of an AQS query

Use a WorkflowSyntaxNodeAqsWebModel to get a value from the item(s) fetched by an AQS query. This can be useful for fetching a set of items that isn't defined anywhere else in the workflow.

For example, set the Archived Bollards attribute to the result of an AQS query that fetches all archived Bollards items.

"parameters": [
{
"attributeCode": "attributes_designArchivedBollards_5f06170ac3ca920067f1d829",
"value": {
"aqs": {
"type": "Query",
"properties": {
"dodiCode": "designs_bollards",
"collectionCode": ["Archive"],
"attributes": ["attributes_itemsTitle", "attributes_itemsSubtitle", "attributes_bollardsHeight_63a46ee23bcd9d03a2e208ab"],
}
},
"discriminator": "WorkflowSyntaxNodeAqsWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

The aqs property holds a standard AqsJsonNode model that defines an AQS query. To learn more, see Alloy Query Syntax (AQS).

Variables as AQS parameters

If the supplied AQS query contains any AQS parameters, any variables with matching names will be substituted into the AQS query at runtime.

Taking the above example further, we'll modify the AQS query to fetch only archived Bollards items whose Height attribute equals a heightVar parameter.

"parameters": [
{
"attributeCode": "attributes_designArchivedBollards_5f06170ac3ca920067f1d829",
"value": {
"aqs": {
"type": "Query",
"properties": {
"dodiCode": "designs_bollards",
"collectionCode": ["Archive"],
"attributes": ["attributes_itemsTitle", "attributes_itemsSubtitle", "attributes_bollardsHeight_63a46ee23bcd9d03a2e208ab"],
"parameters": [
{
"name": "heightVar",
"type": "Number",
"defaultValue": []
}
]
},
"children": [
{
"type": "Equals",
"children": [
{
"type": "Attribute",
"properties": {
"attributeCode": "attributes_bollardsHeight_63a46ee23bcd9d03a2e208ab"
}
},
{
"type": "Number",
"properties": {
"parameterName": "heightVar"
}
}
]
}
]
},
"discriminator": "WorkflowSyntaxNodeAqsWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

We'll then define a new variable named heightVar on the same node. Its value is derived from the Height attribute on the related input item of the node's parent.

"variables": [
{
"name": "heightVar",
"value": {
"inputParent": 1,
"itemValue": {
"attributeCode": "attributes_bollardsHeight_63a46ee23bcd9d03a2e208ab",
"discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel"
},
"discriminator": "WorkflowSyntaxNodeInputWebModel"
}
}
]

As the AQS property and variable have the same name, the AQS parameter will be substituted with the variable's value at runtime.

Templated string

Use a WorkflowSyntaxNodeTemplateWebModel to compute a string from a template.

"parameters" : [
{
"attributeCode": "attributes_designMyStringAttribute_5f06170ac3ca920067f1d829",
"value": {
"template": "$myVariable is now in a string",
"discriminator": "WorkflowSyntaxNodeTemplateWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]

The template property defines the template string that will be used to generate a string at runtime. To reference a variable in the current node, prefix its name with $.

Note

To reference a variable on another node, define a new variable on the current node and set its value to the other variable.

Trigger parameters

If any parameters are defined for a manual workflow's trigger, they can be passed through to an action. When the workflow's parametersDesignCode is set, the attributes of the referenced design serve as trigger parameters. These are set at runtime, either by supplying values via the API, or by automatically displaying a dialog to collect user input.

Use a WorkflowSyntaxNodeTriggerParameterWebModel to pass the value of a parameter attribute to a target attribute.

For example, set MyNumberAttribute to the value of the InputNumber attribute on the My Trigger Parameters design.

"parameters" : [
{
"attributeCode": "attributes_myExampleDesignMyNumberAttribute_667ad67c535060cadd25fa57",
"value": {
"parameterCode": "attributes_myTriggerParametersInputNumber_667ad6f2535060cadd2614be",
"inputMode": "Each",
"discriminator": "WorkflowSyntaxNodeTriggerParameterWebModel"
},
"discriminator": "WorkflowComputedItemAttributeWebModel"
}
]
The inputMode property

This optional property is only relevant if you intend to reference the manual workflow in other workflows.

If dynamic parameter values are supplied via a manual workflow reference (MWR) in another workflow (instead of running the manual workflow directly), you can control how they are used.

If inputMode is undefined, the default value is Each. This means each item receives its own parameter value. If inputMode is set to All, each item receives all the parameter values.

For example, imagine a manual workflow that's referenced by another workflow. It receives three items of the Tasks interface from the other workflow, plus parameter values for each task's title. For each task item, the manual workflow sends a message containing the task's title. If the inputMode is "All", three messages will be sent that each contain all three task titles.

Note

To use a manual trigger parameter as an AQS query parameter, define it as a variable instead, with the same name as the AQS parameter. It will then be substituted into the AQS query.

Virtual web model

This web model is deprecated but remains for backwards compatibility. Its entire functionality can be achieved using the Computed models described above.

The WorkflowVirtualItemAttributeWebModel was introduced as a precursor to Workflow Computations for setting attributes using dynamic values. Many of the mechanisms for accessing data are available in the virtual item through the use of the $context$expression$ syntax.

Description of $context$expression$ syntax

The context describes where to get the data from and the expression describes the data to reference.

Context

Virtual items support the following functions:

  • $input$[AttributeCode]$- substitute the value of an attribute from the input to the action.

  • $input$itemId$- substitute the ItemId of the input item to the action.

  • $input(N)$[AttributeCode]$ - substitute the value of an attribute from the Nth preceding input to the action (0 is the current action).

  • $output([ActionId])$[AttributeCode]$ - substitute the value of an attribute from a specific action within the workflow.

  • $utcnow(OnWorkingDays)$[signed integer milliseconds]$ - substitute the current time of execution, offset by a number of milliseconds.

These terms can be combined, resulting in a concatenated string. The resulting string will then be attempted to be parsed back to the specified attribute type. This allows templating of AQS queries, or simple building of string attributes:

{
"attributeCode": "attributes_designMyStringAttribute_5f06170ac3ca920067f1d829",
"virtualDefinition": "$input(0)$attributes_name$ has £$input(1)$attributes_balance$",
"discriminator": "WorkflowVirtualItemAttributeWebModel"
}

Expression

To access the data from a context, you must define an expression. The following expressions are available:

  • Item Id - access the Item Id of a context, e.g. $input(0)$itemId$.

  • Attribute value - access the value of any attribute from the output of a node, e.g. $output(8765432)$attributes_myName$ _gets the value of the myName attribute from the action whose ID is 8765432.

  • UTC time + offset - add an offset to the current time of execution, e.g. $utcnow$[3600].