Task

Task varieties

Tasks are run by stages. There are four varieties of task.

  • Type tasks
  • Collection tasks
    • Group
    • Try
    • Concurrent

The Type tasks use a type property to identify the specific type of task being executed. The collection tasks all contain one or more task definitions. Tope level stage tasks inherit parameters and environment variables from the stage. Sub tasks of a collection task inherit the parameters and environment variables the collection. In this way parameters and environment definitions are hierarchical where child nodes in the tree can replace values provided by their parents.

All tasks, regardless of variety or type share a set of common properties. Additional properties can be defined for each variety and type task implementations can add their own additional configuration properties.

Variable types

There are three different types of variable storage in ciirocket:

  • Environment variables. Inherited from the shell process Environment variables and passed into child processes. Environment variables are evaluated at prepare time. (The run task type reevaluates variables immediately prior to executing ht sub process.) The variables are readonly once defined. The env definitions are template expanded, but only have access to parent params.
  • Parameters are read only values either passed into the program as command line arguments or defined in configuration. Parameters are evaluated during the preparation phase. Values are scoped to the specific item defining them and their child definitions. Iif a child sets a new value for a parameter it does not effect their parent or sibling’s values.
  • Variables are dynamic values evaluated before, during or after a task’s execution phase. Variables can be used to share output from a task with its parent’s and sibling tasks. Th prevars are evaluated after the prepare phase but prior to executing a task. The values are local to the task. The postvars are evaluated after the task has executed and are shared with the parent and sibling tasks.

Variables are not defined during the prepare phase so should not be used as part of a env or param template value.

Common Task Properties

basicEnv

Map of environment variables where the values are not template expanded.

The basicEnv variables are loaded prior to the env variables. The env value takes prescience`

The variables are scoped to the specific task.

Feature Used
Mandatory No
Template Expanded No 
basicEnv:
  THRUSTERS: GO{{Not expanded}}
  TELEMETRY: GO

description

Free text description of the task.

This property, along with comments can be used to document the task.

Feature Used
Mandatory No
Template Expanded No

env

Map of environment variables where the values are template expanded.

The basicEnv variables are loaded prior to the env variables. The env value takes prescience`

All Environment variables are loaded prior to params.

The task inherits the stage’s environment variables.

Feature Used
Mandatory No
Template Expanded Yes

exports

The exports definition is a list of variables that should be shared with as variables with their parent and sibling tasks. All postvars are exported automatically, but the prevars need to be listed in the exports section to be shared with parents/siblings.

Feature Used
Mandatory No
Template Expanded No

filter

The filter property is an optional filter on the stage. If the filter criteria are not met the task will be skipped.

Feature Used
Mandatory No
Template Expanded No

if

The if condition is evaluated immediately prior to starting execution of the task’s operations. If the supplied expression does not evaluate to a boolean true expression the task will be skipped.

When no if property is supplied the task will default the if condition to true.

Feature Used
Mandatory No
Template Expanded Yes

must

List of parameters that must be passed into the task from the stage or task parent. If any of the parameters are missing the task will fail preparation and no stage, task or onFail will be run.

Feature Used
Mandatory No
Template Expanded No

name

Name of the task. If supplied the name must be unique across all tasks sharing the same parent task or stage.
Tasks that are not named are refereed to by their ordinal position in the list of tasks.

Feature Used
Mandatory No
Template Expanded No

noTrust

The noTrust property indicates the task should not inherit environment variables or parameters from its parent.
This can be used with a run task where you do not want the child process to receive API tokens etc. that are stored in the parent environment.

Feature Used
Mandatory No
Template Expanded No

params

The params property is a map of param definitions. Params are readonly values that are template expanded during the preparation phase of a mission.

When params are expanded they have access to:

  • environment variables passed from the stage or task parent and not overwritten by basicEnv or env entries
  • environment variables defined in basicEnv or env entries.
  • params passed from the task’s parent stage or task.

See Param definition for more info.

Feature Used
Mandatory No
Template Expanded Yes

prevars

The prevars property is map of variable key names and temp;ate expanded values that are evaluated after the prepare phase has completed but before the defining task has started execution. The variables are local to the defining task and any child tasks that it may have.

Feature Used
Mandatory No
Template Expanded Yes

postvars

The postvars property is map of variable key names and temp;ate expanded values that are evaluated after the task has successfully completed. The variables are exported and shared with their parent and sibling tasks.

Feature Used
Mandatory No
Template Expanded Yes

ref

The ref property allows a task to reference another task’s definition. If a ref property is provided it mast identity another named task. The target and referenced task must share the same immediate parent. If the task referenced does not exist the mission wll fail at the prepare phase.

When a target task references another task the properties of the referenced task are copied and merged into the target task’s properties. Any properties defined in the target task take precedence over the referenced task. Tasks references are transitive so a referenced task may reference other tasks. The mission fails if a circular reference is detected however.

The ref property is useful to avoid needing to repeat definitions for the onFail task etc.

Feature Used
Mandatory No
Template Expanded No

Type Tasks

type

The type property identifies a task as the Type variety. The type value is the identifying name of the task type running this task.

The type identifier must be registered with cirocket. Unknown task types will cause the mission to fail.

Task types may define their own additional properties that can be included in the task configuration.

Feature Used
Mandatory Type determinant
Template Expanded No

Collection Tasks

concurrent

A concurrent property identifies the task as being of the Concurrent variety, A concurrent task is itself just a list of tasks to execute concurrent. Each of the tasks will run concurrently, if a task fails cirocket will attempt to cancel the other running tasks. A concurrent task completes when all the child tasks have completed.

All the tasks will inherit any environment or parameter settings defined in the concurrent definition.

Feature Used
Mandatory Type determinant
Template Expanded No

group

A group property identifies the task as being of the Group variety, A group task is itself just a list of tasks to execute sequentially.

The task group is similar to the stage tasks property in that tasks will be sequentially executed in the order they are defined. All the tasks will inherit any environment or parameter settings defined in the group definition.

Feature Used
Mandatory Type determinant
Template Expanded No

onFail

The onFail property defines a task to run if during a group task’s execution phase an error occurs. The task can be used to perhaps clean up resources etc. The onFail task is not run if the stage fails during the preparation phase.

onFail only applies to group and concurrent tasks, other task types will ignore this property.

Feature Used
Mandatory No
Template Expanded No

try

A try property identifies the task as being of the Try variety, A try task is itself just a list of tasks to execute sequentially.

The try list is similar to the group list where tasks are sequentially executed in the order they are defined. the tyy list differs that should any sub task fail the remaining tasks in the list will not be run, but no failure error will be raised and tasks proceeding the try block will continue to be run.

All the tasks will inherit any environment or parameter settings defined in the group definition.

Feature Used
Mandatory Type determinant
Template Expanded No