Expressions

Overview

Instead of hard-coding every value, a protocol.yml can use expressions to programmatically control the workflow at run time. Expressions are written by enclosing them in $( ... ), and within an expression a small set of contexts and functions are available. These can be combined freely within a single expression.

Contexts

workflow

Data about the current workflow run.

Value

Contents

workflow.id

ID of the current workflow

workflow.inputFile

Pointer to the file that triggered the workflow

workflow.startedAt

ISO 8601 datetime string of when the workflow started

workflow.pipeline.id

ID of the pipeline that triggered this workflow

config

Data configured by the pipeline’s user, keyed by the config IDs declared under config in protocol.yml (see protocol.yml field reference). Given:

config:
  foo:
    label: Foo
    type: string
  bar:
    label: Hey Bear
    type: object

$( config.foo ) and $( config.bar ) are valid; $( config.baz ) errors, because baz was never declared.

constants

All constant values defined under constants in protocol.yml. If a constant contains an expression, it’s evaluated before access. Given:

constants:
  foo: "bar"
  baz:
    - 1
    - 2

$( constants.foo ) and $( constants.baz ) are valid; $( constants.qux ) errors.

protocol

Reads back the manifest-mirror fields declared at the top level of protocol.yml (see the manifest fields table in protocol.yml field reference) — for example $( protocol.name ) or $( protocol.version ). Returns null if the field wasn’t specified.

steps

Contains every step’s result. A step is only readable in this context once it has run or been skipped. A step can be addressed by its id or by its list index:

  • steps[0]

  • steps['stepOne']

  • steps.stepOne

Prefer the named-ID form over the numeric-index form. The compiler itself warns Using a number to access a step instead of an id is prone to error and not recommended — the expression still compiles, but give every step an id and address it by name. Use the bracket form (steps["some-step-id"]) when the ID contains a hyphen.

Value

Contents

steps.<id>.output

Whatever the task-script function returned

steps.<id>.error

Only populated when that step set continueOnError: true

steps.<id>.status

One of success, failed, skipped

steps.<id>.isSuccess

true if the step succeeded

steps.<id>.isFailed

true if the step failed

steps.<id>.isSkipped

true if the step was skipped (via if)

Functions

A deliberately small list — anything beyond this belongs in a task script, not the protocol. There is no foreach, parallel, or loop construct in v3.

Function

Description

Example

coalesce(...args)

First value that isn’t null, or null if all are null

coalesce(null, null, "foo", "bar") → "foo"

not(value)

Negates the value

not(true) → false

isNumber(value)

true if a number

isNumber(5) → true; isNumber("5") → false

isString(value)

true if a string

isString("5") → true

isBoolean(value)

true if a boolean

isBoolean(false) → true; isBoolean("false") → false

isNull(value)

true if null

isNull(null) → true

or(...args) (added TDP v4.3.0)

true if any value is true

or(false, true, false) → true; or() → false

and(...args) (added TDP v4.3.0)

false if any value is false

and(true, false, true) → false; and() → true

See also

For the fields these expressions read from and write to — config, constants, steps, successWhen, onFailed — see protocol.yml field reference.