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).

Basic Functions

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

Timestamp Functions

Flows offer a suite of functions for working with the specialized timestamp type. These functions enable flow authors to compute future deadlines, format human-readable date/time strings, and translate between different API timestamp serialization formats.

Creating and Loading Timestamps

now(tz: str = "UTC", /) -> timestamp

The now function returns a timestamp representing the current date and time, expressed in tz (an IANA time zone name, e.g. America/Chicago), which defaults to UTC. See the "TZ identifier" column of this table for a list of accepted values.

Example Result[1]

now()

2020-01-01T00:00:00+00:00

now(tz='UTC')

2020-01-01T00:00:00+00:00

now(tz='America/Chicago')

2019-12-31T18:00:00-06:00

now(tz='Etc/GMT+5')

2019-12-31T19:00:00-05:00

 
strptime(serialized: str, formatstring: str, /) -> timestamp

The strptime function parses serialized, according to formatstring, into a timestamp.

Common format strings are detailed in the following table. A full list of directives can be found here.

Example Accepted Format

ISO 8601

strptime(input_string, '%Y-%m-%dT%H:%M:%S%:z')

"2024-01-15T10:30:00+00:00"

Date Only

strptime(input_string, '%Y-%m-%d')

"2024-01-15"

Date and Time

strptime(input_string, '%m/%d/%Y %H:%M:%S')

"01/15/2024 10:30:00"

 
from_epoch(value: str | number, /) -> timestamp

The from_epoch function parses value, a Unix epoch timestamp given as a string or number, into a timestamp.

value may be given in seconds or milliseconds since the epoch; the unit is inferred from the magnitude of the value.

Example Result[1]

from_epoch(1705311000)

2024-01-15T10:30:00+00:00

from_epoch(1705311000.0)

2024-01-15T10:30:00+00:00

from_epoch(1705311000000)

2024-01-15T10:30:00+00:00

from_epoch('1705311000')

2024-01-15T10:30:00+00:00

Serializing Timestamps

strftime(timestamp: timestamp, formatstring: str, /) -> str

The strftime function provides a way to format a timestamp with a custom formatstring to match a desired output format.

Common format expressions are detailed in the following table. A full list directives can be found here.

Example Result

ISO 8601 (no formatting required)

now()

"2020-01-01T00:00:00+00:00"

Date and Time

strftime(now(), '%Y-%m-%d %H:%M:%S')

"2020-01-01 00:00:00"

Date Only

strftime(now(), '%Y-%m-%d')

"2020-01-01"

Time Only

strftime(now(), '%H:%M:%S')

"00:00:00"

Natural Language Time

strftime(now(), '%A, %B %d, %Y at %I:%M %p')

"Wednesday, January 01, 2020 at 12:00 AM"

 
to_epoch(timestamp: timestamp, /) -> int

The to_epoch function converts timestamp into a Unix epoch integer, given in seconds since the epoch.

Example Result

to_epoch(now())

1577836800

to_epoch(add_time(now(), days=1))

1577923200

Manipulating Timestamps

add_time(
  timestamp: timestamp,
  *,
  weeks: number = 0,
  days: number = 0,
  hours: number = 0,
  minutes: number = 0,
  seconds: number = 0,
  milliseconds: number = 0,
  microseconds: number = 0,
) -> timestamp

The add_time function returns a new timestamp computed by adding the given duration to timestamp. All duration arguments are optional, keyword-only, and default to 0; any combination of them may be supplied together.

Example Result[1]

add_time(now(), days=5)

2020-01-06T00:00:00+00:00

add_time(now(), weeks=1, hours=2)

2020-01-08T02:00:00+00:00

add_time(now(), hours=1)

2020-01-01T01:00:00+00:00

 
sub_time(
  timestamp: timestamp,
  *,
  weeks: number = 0,
  days: number = 0,
  hours: number = 0,
  minutes: number = 0,
  seconds: number = 0,
  milliseconds: number = 0,
  microseconds: number = 0,
) -> timestamp

The sub_time function returns a new timestamp computed by subtracting the given duration from timestamp. All duration arguments are optional, keyword-only, and default to 0; any combination of them may be supplied together.

Example Result[1]

sub_time(now(), days=5)

2019-12-27T00:00:00+00:00

sub_time(now(), weeks=1, hours=2)

2019-12-24T22:00:00+00:00

sub_time(now(), days=7)

2019-12-25T00:00:00+00:00

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.

1. Unquoted timestamp results are shown for clarity; the actual result is a timestamp instance, not a string.