Expression functions

Basic functions

All expressions (${{ <expression }}) support a set of pre-built functions:

Function name	Description
len()	Return the length of the argument.
keys()	Return the keys of the dictionary.
lower()	Convert a string to lowercase.
upper()	Convert a string to uppercase.
fmt()	Perform string formatting.
to_json()	Convert an object to a JSON string.
from_json()	Convert a JSON string to an object.
upload()	Upload a volume to the Apolo storage.
parse_volume()	Parse a volume reference string to an object.
hash_files()	Calculate a SHA256 hash of given files.
values()	Get values from a dictionary.
str()	Convert any object to a string.
replace()	Replace all occurrences of a symbol sequence in a string with a new one.
join()	Concatenate an array of strings by inserting a separator between them

len(s)

Return the length of an object (the number of items it contains). The argument may be a string, a list, or a dictionary.

Example:

${{ len('fooo') }}

keys(dictionary)

Get the list of keys in a dictionary.

Example:

${{ keys(env) }}

lower(string)

Convert a string to lowercase.

Example:

${{ lower('VALue') == 'value' }}

upper(string)

Convert a string to uppercase.

Example:

${{ upper('valUE') == 'VALUE' }}

fmt(format_string, arg1, ...)

Perform a string formatting operation. The format_string can contain text or replacement fields delimited by curly braces {}. The replacement field will be replaced with other arguments' string values in order they appear in the format_string.

Example:

${{ fmt("Param test value is: {}", params.test) }}

This function can be useful in situations when you want to get a value from a mapping using a non-static key:

${{ needs[fmt("{}-{}", matrix.x, matrix.y)] }}

to_json(data)

Convert any data to a JSON string. The result can be converted back using from_json(json_string).

Example:

${{ to_json(env) }}

from_json(json_string)

Parse a JSON string to an object.

Example:

${{ from_json('{"array": [1, 2, 3], "value": "value"}').value }}

upload(volume_ctx)

Upload the volume to the Apolo storage and then return the passed argument back. The argument should contain an entry of the volumes context. The function will fail if the local attribute is not set for the corresponding volume definition in the workflow file.

This function allows to automatically upload a volume before a job runs.

Example:

volumes:
  data:
    remote: storage:data
    mount: /data
    local: data
jobs:
  volumes:
    - ${{ upload(volumes.data).ref_rw }}

parse_volume(string)

Parse a volume reference string into an object that resembles an entry of the volumes context. The id property will be set to "<volume>", and the local property will be set to None.

Example:

${{ parse_volume("storage:data:/mnt/data:rw").mount == "/mnt/data" }}

hash_files(pattern, ...)

Calculate the SHA256 hash of the given files.

File names are relative to the flow's root (${{ flow.workspace }}).

Glob patterns are supported:

Pattern	Meaning
*	matches everything
?	matches any single character
[seq]	matches any character in seq
[!seq]	matches any character not in seq
**	recursively matches this directory and all subdirectories

The calculated hash contains hashed filenames to generate different results when the files are renamed.

Example:

${{ hash_files('Dockerfile', 'requiremtnts/*.txt', 'modules/**/*.py') }}

inspect_job(job_name, [suffix])

Fetch info about a job in live mode. The suffix argument should be used with multi jobs. The returned object is a JobDescription.

Example:

${{ inspect_job('test_job').http_url }}

values(dict_instance)

Get values from a dictionary. This is similar to Python's dict_instance.values().

Example:

${{ values(dictionary) }}

str(any)

Convert any object to a string.

Example:

${{ str(list_of_values) }}

replace(string, old, new)

Replace all occurrences of old in string with new.

Example:

${{ replace("5tring 5tring 5tring", "5", "S") }}

join(separator, array)

Concatenate an array of strings by inserting a separator between them.

Example:

${{ join(", ", ["1", "2", "3"] }}

Task status check functions

The following functions can be used in the tasks.enable attribute to conditionally enable task execution.

Function name	Description
success()	True if given dependencies succeeded.
failure()	True if some of the given dependencies failed.
always()	Mark a task to be always executed.

success([task_id, ...])

Returns True if all of the specified tasks are completed successfully. If no arguments are provided, checks all tasks form tasks.needs.

Example:

tasks:
  - enable: ${{ success() }}

Example with arguments:

tasks:
  - id: task_1
  - enable: ${{ success('task_1') }}

failure([task_id, ...])

Returns True if at least one of the specified tasks failed. If no arguments are provided, checks all tasks form tasks.needs. This function doesn't enable task execution if a dependency is skipped or cancelled.

Example:

tasks:
  - enable: ${{ failure() }}

Example with arguments:

tasks:
  - id: task_1
  - enable: ${{ failure('task_1') }}

always()

Returns a special mark so that Apolo Flow will always run this task, even if some tasks in tasks.needs have failed or were skipped, or the workflow was cancelled.

Example:

tasks:
  - enable: ${{ always() }}