Workflow Expressions

Workflow model parameters can use expressions to select/manipulate workflow and/or state data.

Note that different data filters play a big role as to which parts of the states data are to be used when the expression is evaluated. Reference the State Data Filtering section for more information about state data filters.

By default, all workflow expressions should be defined using the jq version 1.6 syntax. You can find more information on jq in its manual.

Serverless Workflow does not mandate the use of jq and it's possible to use an expression language of your choice with the restriction that a single one must be used for all expressions in a workflow definition. If a different expression language needs to be used, make sure to set the workflow expressionLang property to identify it to runtime implementations.

Note that using a non-default expression language could lower the portability of your workflow definitions across multiple container/cloud platforms.

All workflow expressions in this document, specification examples as well as comparisons examples are written using the default jq syntax.

Workflow expressions have the following format:

${ expression }

Where expression can be either an in-line expression, or a reference to a defined expression function definition.

To reference a defined expression function definition the expression must have the following format, for example:

${ fn:myExprFuncName }

Where fn is the namespace of the defined expression functions and myExprName is the unique expression function name.

To show some expression examples, let's say we have the following state data:

{
  "applicant": {
    "name": "John Doe",
    "age"      : 26,
    "email": "[email protected]",
    "address"  : {
      "streetAddress": "Naist street",
      "city"         : "Nara",
      "postalCode"   : "630-0192"
    },
    "phoneNumbers": [
      {
        "type"  : "iPhone",
        "number": "0123-4567-8888"
      },
      {
        "type"  : "home",
        "number": "0123-4567-8910"
      }
    ]
  }
}

In our workflow model we can define our reusable expression function:

{
"functions": [
  {
    "name": "is-adult-applicant",
    "operation": ".applicant | .age > 18",
    "type": "expression"
  }
]
}

We will get back to this function definition in just a bit, but now let's take a look at using an inline expression that sets an input parameter inside an action for example:

{
"actions": [
    {
        "functionRef": {
            "refName": "confirm-applicant",
            "arguments": {
                "applicantName": "${ .applicant.name }"
            }
        }
    }
]
}

In this case our input parameter applicantName would be set to "John Doe".

Expressions can also be used to select and manipulate state data, this is in particularly useful for state data filters.

For example let's use another inline expression:

{
   "stateDataFilter": {
       "output": "${ .applicant | {applicant: .name, contactInfo: { email: .email, phone: .phoneNumbers }} }"
   }
}

This would set the data output of the particular state to:

{
  "applicant": "John Doe",
  "contactInfo": {
    "email": "[email protected]",
    "phone": [
      {
        "type": "iPhone",
        "number": "0123-4567-8888"
      },
      {
        "type": "home",
        "number": "0123-4567-8910"
      }
    ]
  }
}

Switch state conditions require for expressions to be resolved to a boolean value (true/false).

We can now get back to our previously defined "IsAdultApplicant" expression function and reference it:

{
  "dataConditions": [ {
    "condition": "${ fn:is-adult-applicant }",
    "transition": "start-application"
  }]
}

As previously mentioned, expressions are evaluated against certain subsets of data. For example the parameters param of the functionRef definition can evaluate expressions only against the data that is available to the action it belongs to. One thing to note here are the top-level workflow definition parameters. Expressions defined in them can only be evaluated against the initial workflow data input.

For example let's say that we have a workflow data input of:

{
   "inputVersion" : "1.0.0"
}

we can use this expression in the workflow "version" parameter:

{
   "name": "my-sample-workflow",
   "description": "Sample Workflow",
   "version": "${ .inputVersion }",
   "specVersion": "0.8"
}

which would set the workflow version to "1.0.0". Note that the workflow "name" property value is not allowed to use an expression. The workflow definition "name" must be a constant value.