Relay functions
Relay provides functions that help you manipulate data as it passes through your workflow. You can invoke a function in a workflow using the following syntax: !Fn.<function> [<arguments>]
. Most functions are "utility" functions, meaning they can be used anywhere a hard-coded value can appear. There are also a pair of special functions (equals
and notEquals
) for evaluating conditionals.
Utility Functions
append
The append
function adds one or more values to the end of an array. For example:
targets: !Fn.append
- a.example.com
- b.example.com
coalesce
Returns the first resolvable non-null value from the arguments.
Arguments:
- 0..n: The values to consider, in order
!Fn.coalesce [!Output [step, nonexistent], 42] # => 42
!Fn.coalesce [!Output [step, nonexistent]] # => null (used to ignore non-resolvable values)
!Fn.coalesce [!Output [step, nonexistent], !Parameter someParameterWithNullValue, 42] # => 42
concat
The concat
function joins two or more elements together. For example:
domains:
- !Fn.concat [foo, 3, bar, ".com"] # => "foo3bar.com"
- !Fn.concat [!Parameter environment, .example.com]
convertMarkdown
The convertMarkdown
function converts Markdown into comparable syntax for similar specifications. For example:
description: !Fn.convertMarkdown [jira, !Parameter markdown]
Currently supported specifications:
jsonUnmarshal
The jsonUnmarshal
function converts serialized JSON into an executable data type. For example:
certs: !Fn.jsonUnmarshal [!Secret certs]
Because Relay secrets are always stored as strings, the jsonUnmarshal
function is useful when you need to pass the contents of a secret into a function that requires a data type other than a string.
merge
The merge
function iteratively merges together two map arrays. For example:
api: !Fn.merge
- image:
tag: !Secret api.image.tag
- storage:
address: 10.11.12.13
Output:
api:
image:
tag: !Secret api.image.tag
storage:
address: 10.11.12.13
path
Looks up a path using a query in an object, optionally returning a default value if the path is unresolvable or nonexistent.
Arguments: 1. The object to traverse 2. The query to use 3. optional: The default to use instead if the object does not contain a value at the query or cannot be resolved
!Fn.path [{foo: bar}, foo] # => "bar"
!Fn.path [{foo: bar}, baz] # => (invocation error)
!Fn.path [{foo: bar}, baz, quux] # => "quux"
!Fn.path [{foo: {bar: [{baz: quux}]}}, "foo.bar[0].baz"] # => "quux"
!Fn.path [{foo: !Output [step, nonexistent]}, foo] # => (unresolvable)
!Fn.path [{foo: !Output [step, nonexistent]}, foo, 42] # => 42
toString
Converts its argument to a string if possible, and returns an error otherwise.
Argument: 1. The scalar value to convert to a string
!Fn.toString [foo] # => "foo"
!Fn.toString [42] # => "42"
!Fn.toString [42.424242] # => "42.424242"
Conditional Functions
These functions are only useful in the context of a when:
statement for conditionally executing a step.
For more information, see Conditional step execution.
equals
The equals
function compares two arguments and returns the boolean true
if the type and value of the arguments are equal.
when:
- !Fn.equals [!Parameter env, production]
Accepts the following expressions and types:
- a parameter:
!Parameter example-parameter
- an output:
!Output stepName outputName
- a string:
"Just a normal string."
- a boolean:
true
orfalse
- an integer:
10
,100
,35
- a float:
10.5
,1.0
,54.99999
- an array:
["apple", "banana", "orange", "peach"]
- a map:
{"vegetable": "carrot", "fruit": "apple"}
notEquals
The notEquals
function compares two arguments and returns the boolean true
if the type and value of the arguments are not equal.
when:
- !Fn.notEquals [!Parameter env, development]
Accepts the following expressions and types:
- a parameter:
!Parameter example-parameter
- an output:
!Output stepName outputName
- a string:
"Just a normal string."
- a boolean:
true
orfalse
- an integer:
10
,100
,35
- a float:
10.5
,1.0
,54.99999
- an array:
["apple", "banana", "orange", "peach"]
- a map:
{"vegetable": "carrot", "fruit": "apple"}