Action variables

Use variables to store reusable values

When using the API to add (Swagger/ReDoc) or edit (Swagger/ReDoc) an action node, you can declare one or more variables.

A variable stores a value that can be referenced by any node in the workflow (including the current one).

While this provides another way to share data between nodes, it also means that computed values can be reused. You can therefore optimise workflow performance by ensuring that each computation is only performed once, with the result stored in a variable for future reference.

Every variable is defined using a WorkflowActionVariableWebModel:

"variables": [
  {
    "name": "myVariable",
    "value": ...
  }
]

The name property determines the identifier of the variable. Set this to a string that conforms to camelCase.

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

Computation type	Value model
Input to current/previous node	`WorkflowSyntaxNodeInputWebModel`
Output from any node	`WorkflowSyntaxNodeOutputWebModel`
Time offset	`WorkflowSyntaxNodeRelativeTimeWebModel`
Result of a script	`WorkflowSyntaxNodeScriptWebModel`
Result of an AQS query	`WorkflowSyntaxNodeAqsWebModel`
Templated string	`WorkflowSyntaxNodeTemplateWebModel`
Trigger parameters	`WorkflowSyntaxNodeTriggerParameterWebModel`

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 MyVariable to a value on the related input item of the 1st parent node.

"variables": [
  {
    "name": "myVariable",
    "value": {
      "inputParent": 1,
      "itemValue": ...
      "discriminator": "WorkflowSyntaxNodeInputWebModel"
    }
  }
]

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 a WorkflowSyntaxNodeInputWebModel to get a value from the output item(s) of any node in the workflow.

For example, populate MyVariable with the IDs of all items outputted by the specified node.

"variables": [
  {
    "name": "myVariable",
    "value": {
      "outputAction": "5f05f85cc3ca920067f1d7a0",
      "outputMode": "All",
      "itemValue": {
        "property": "ItemId",
        "discriminator": "WorkflowSyntaxArgumentItemValueItemPropertyWebModel"
      },
      "discriminator": "WorkflowSyntaxNodeOutputWebModel"
    }
  }
]

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 MyDateTimeVariable to "86400000" milliseconds (24 hrs) after the workflow was scheduled to trigger.

"variables": [
  {
    "name": "MyDateTimeVariable"
    "value": {
      "offsetMilliseconds": 86400000,
      "offsetOrigin": "Scheduled",
      "type": "DateTime",
      "condition": ...
      "discriminator": "WorkflowSyntaxNodeRelativeTimeWebModel"
    }
  }
]

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 totalPoints variable to the sum of the numbers in the taskPoints variable.

"variables": [
  {
    "name": "totalPoints",
    "value": {
      "script": "return Elements(taskPoints).Sum();",
      "returnOptions": {
        "decimalPlaces": 0,
        "discriminator": "DodiAttributeOptionsNumberWebModel"
      }
      "discriminator": "WorkflowSyntaxNodeScriptWebModel"
    }
  }
]

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.

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 archivedBollards variable to the result of an AQS query that fetches all Bollards items with a Collection property of "Archive".

"variables": [
  {
    "name": "archivedBollards",
    "value": {
      "aqs": {
        "type": "Query",
        "properties": {
          "dodiCode": "designs_bollards",
          "collectionCode": ["Archive"],
          "attributes": ["attributes_itemsTitle", "attributes_itemsSubtitle", "attributes_bollardsHeight_63a46ee23bcd9d03a2e208ab"]
        }
      },
      "discriminator": "WorkflowSyntaxNodeAqsWebModel"
    }
  }
]

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.

"variables": [
  {
    "name": "archivedBollards",
    "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"
    }
  }
]

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": "archivedBollards",
    "value": ...
  },
  {
    "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.

"variables" : [
  {
    "name": "myStringVariable",
    "value": {
      "template": "$myOtherVariable is now in a string",
      "discriminator": "WorkflowSyntaxNodeTemplateWebModel"
    }
  }
]

The template property defines the template string that will be used to generate a string at runtime. To reference another 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 declared as variables, so that their values can be accessed by any action in the workflow.

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 save the value of a parameter attribute as a variable.

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

"variables" : [
  {
    "name": "MyVariable",
    "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 variable with the same name as the AQS parameter. It will then be substituted into the AQS query.

Use variables to store reusable values​

Input to current/previous node​

Output from any node​

Time offset​

Result of a script​

Result of an AQS query​

Templated string​

Trigger parameters​

Use variables to store reusable values

Input to current/previous node

Output from any node

Time offset

Result of a script

Result of an AQS query

Templated string

Trigger parameters