Expressions

Action Parameters allow the inputs to an action to be formed from different parts of the flow run-time state. However, the reference approach requires that the exact value must be present in the flow’s state. If the required value is somehow to be derived from multiple values in the flow state, reference parameters are not sufficient. Thus, we introduce expression type parameters which may evaluate multiple parts of the state to compute a single, required value.

The syntax of an expression parameter takes the following form:

{
  "computed_param.=": "<state_val1> <op> <state_val2> <op> ..."
}

The syntax for the expression largely follows what is expected in common expression languages. This includes common arithmetic operators on numeric values as well as operations on strings (e.g. string concatenation via a + operation) and on lists (similarly the + operator will concatenate lists).

The values in the state of the flow may be used in the expression and are denoted as <state_valN> above. For the following description, assume that the input to (or current state of) a flow run is as follows:

{
  "foo": "bar",
  "object_val": {
    "sub_val1": "embedded",
    "sub_val2": "also_embedded"
  }
}

The state_val values can be specified as the simple names of the properties in the state of the running flow and allows for indexing into lists and into embedded objects similar to Python. Thus, the following would be a valid expression: foo + ' ' + object_val.sub_val1 which would yield the string bar embedded. Note the use of + to mean string concatenation and the dot-separated naming of the field of the object.

Constants may also be used between operators, it is important to remember that within an expression, a string type value must be enclosed in quotes (either single quote characters as above which is often easier because they do not need to be escaped within a JSON string or double quotes).

Functions

In addition to basic arithmetic operations, Flows provides a selection of functions to be used inside of expressions.

Functions are invoked with the general form: function_name(param1, param2) and may be composed with other expression elements e.g., val1 + function(param1).

Supported Functions

len(value: str | object | array, /) -> int

The len function computes the length of a JSON string, object, array.

Example Result

len("string")

6 (the length of the string)

len({"a": 5, "c": True})

2 (the number of properties in the object)

len(["mine", "yours", "theirs"])

3 (the number of items in the array)

len(set([1, 2, 3]).intersect(set([3, 4, 5])))

1 (the number of items shared between both sets)

 
pathsplit(path: str, /) -> array[str]

The pathsplit function converts a string into an array of two elements:

  1. The string before the last / character

  2. The string after the last / character

Note

Special Case

If the resultant left-hand string is the specialized globus virtual root (/~/), flows will not trim the trailing / character as in the below example: "/~/path".

Example Result

pathsplit("/foo/bar/blech")

["/foo/bar", "blech"]

pathsplit("/~/path")

["/~/", "path"]

pathsplit("/")

["/", ""]

pathsplit("random")

["", "random"]

 
is_present(key: str, /) -> bool

The is_present function evaluates whether a key exists in the expression’s input.

Example Expression Input Result

is_present('x')

{"x": 5}

true

is_present('x')

{"y": 5}

false

x if is_present('x') else 10

{"y": 5}

10

 
getattr(key: str, default: Any = None, /) -> Any

The getattr function retrieves a value from the expression’s input, returning the default if the requested key is not present.

Example Expression Input Result

getattr('x', 10)

{"x": 5}

5

getattr('x', 10)

{"y": 5}

10

getattr('x')

{"y": 5}

null

ExpressionEval State type

The Action state type provides a method of evaluating expressions to create Parameter values for passing to the action, and the Pass state, defined in the States Language, provides a means of moving or re-arranging the flow’s run-time state by specifying input Parameters and new locations via the ResultPath. In some cases, the combination of the two capabilities is desired: the ability to compute results for Parameters as in the Action state and the simple storage of the new values, as in the Pass state. This is the role of the ExpressionEval state type. It can be thought of as an Action without the action invocation, or a Pass where Parameters may contain expressions.

A primary situation in which this state type will be used is when determining a value to be tested in a Choice state type. The Choice state type can only read single values from the run-time state of the flow, so if, for example, a value on which a Choice condition needs to be applied must be combined from separate parts of the flow run-time state. The computed value can then be referenced in the Variable property of the Choice. Another use is to compute a "final" for the flow to be stored in the state of the flow and therefore seen in the output of the flow upon completion.

An example structure for an ExpressionEval state is as follows:

{
  "Type": "ExpressionEval",
  "Parameters": {
    "constant_val": 10,
    "reference_value.$": "$.Path.To.Value",
    "expression_value.=": "'Constant string ' + `$.Path.To.SuffixString`",
    "nested_value": {
      "child_const_val": true,
      "child_ref_val.$": "$.Child.Val.Path"
    },
    "secret_value": "MyPassword",
    "__Private_Parameters": [
      "secret_value"
    ]
  },
  "ResultPath": "$.final_result",
  "End": true
}

All properties of the ExpressionEval state have the same meaning as described in the Action state. The ExpressionEval state cannot use the InputPath property (Pass is appropriate if moving state from an InputPath to a ResultPath is needed), so Parameters must always be present. Just like in Action the Parameters may have constant, reference or expression types and portions of the state can be protected using a __Private_Parameters list. Like Action, this state must have either a Next or an End: true.