Syntax of the conditional deployment

You can enter loop, when, failed_when, jumps_when, or rescue instructions in the deployment method to specify conditions on an activity, an action, or a step.

Most of these instructions require to specify a condition that is evaluated during the execution of the deployment plan. The conditional deployment instructions can be used on the activity, action, or step level of the deployment plan.

If these instructions are specified on the same activity, action, or step, they are processed in the following order: loop, when, failed_when, and jumps_when. The rescue instruction is called only if an exception occurs.

Available attributes for specifying conditions

Several types of attributes are available to indicate what the deployment condition applies to:
  • The environment variables from the environment variables files.

    The environment variables are entered directly in the environment variables file or are declared as extra vars in The Python deployment command or The Ansible deployment command. These two types of variables are merged. The extra vars overwrite the variables that are entered directly in the environment variables file.

    To create a condition on an environment variable, enter the environment keyword and enter the variable name or the path to the variable in the environment file. Separate each level with a period.

    For example, you can add a condition on a variable that is defined in the environment file in var_folder/var1. To indicate that the condition applies to this variable, enter the following attribute:
    environment.var_folder.var1
  • The deployment plan.

    You can access any information of the deployment plan by using the deployment_plan keyword and by specifying the information that you want to reach. You can also indicate one of the ready-to-use keywords to access the current activity, action, or step of the deployment plan.

    The following keywords are available:
    • deployment_plan, which is the entry point into the deployment plan file. To apply a condition to a specific level in the structure of the deployment plan, enter the deployment_plan keyword followed by a period and a JMESPath query that reflects the structure of the file. For more information about JMESPath queries, see Syntax of a complex query.
      For example, to add a condition on an activity whose name is PACKAGE, enter the following attribute:
      deployment_plan.activities[?name=="PACKAGE"]
    • current_plan_activity for the current activity of the deployment plan.
    • current_plan_action for the current action of the deployment plan.
    • current_plan_step for the current step of the deployment plan.
  • The evidences from The evidence file.

    You can access any evidence of the evidence file by using the evidences keyword and by specifying the evidence that you want to reach. You can also indicate one of the ready-to-use keywords to access the evidence that is collected by the previous step or the current activity, action, or step.

    The following keywords are available:
    • evidences, which is the entry point into the evidence file that is being created by the current deployment. To apply a condition to a specific level in the structure of the evidence file, enter the evidences keyword followed by a period and a JMESPath query that reflects the structure of the file. For more information about JMESPath queries, see Syntax of a complex query.
      For example, to add a condition on an action whose name is ADD in an activity whose name is DEPLOY, enter the following attribute:
      evidences.activities[?name=='DEPLOY_MODULES'] | [0].actions[?name=='ADD']
    • previous_ev_step for the evidence that the previous step returned to the evidence file.
    • current_ev_activity for the evidence that the current activity is returning to the evidence file. This information is available and updated as the actions of the current activity are running.
    • current_ev_action for the evidence that the current action is returning to the evidence file. This information is available and updated as the steps of the current action are running.
    • current_ev_step for the evidence that the current step returned to the evidence file. This information is available only after the step completed. This is the reason why it must be used only by the failed_when and jumps_when instructions.

Syntax of a simple query

A simple query is based on the Jinja2 syntax. Refer to the following input formats.

Examples of simple queries are provided in Examples.

Table 1. The instructions for the conditional deployment
Instruction Description Syntax
loop To iteratively run the activity, action, or step. 
loop: 
   loop_query: query to run
   loop_var: name of the loop variable
Note:

The variable name in loop_var successively holds each item of the query.
when To specify a condition that must return True for the activity, action, or step to run.

If this instruction is used on the same activity, action, or step as a loop instruction, then the loop is restricted to the items that meet the condition.

 
when: my condition
or
when:
-  my first condition
-  my second condition
Note: Enter the following elements to write a condition:
  • The type of attribute, such as evidences or environment. Use single quotation marks.
  • A comparison operator (==, <, <=, >, >=, or !=)
  • The value that the attribute must have for the condition to return True.
failed_when To set the status of the current activity, action, or step result to Failed or Successful if the condition is met. You can indicate that the status is Successful even if the activity, action, or step fails ; in this case, the deployment continues. You can also indicate that the status is Failed even if the activity, action, or step is successful ; in this case, the deployment stops.

The deployment stops at the step level, except if the status of the failed_when condition on the action and activity is forced to Successful.

The deployment stops at the action level, except if the status of the failed_when condition on the activity is forced to Successful.

 
failed_when: my condition
or
failed_when:
-  my first condition
-  my second condition
Note: Enter the following elements to write a condition:
  • The type of attribute, such as evidences or environment. Use single quotation marks.
  • A comparison operator (==, <, <=, >, >=, or !=)
  • The value that the attribute must have for the condition to return True.
jumps_when To jump to the specified target location at the end of the current activity, action, or step if the condition returns True.

Use short_name to designate the target location. This target location must have a short_name in its attributes.

The target must be located after the activity, action, or step that contains the jumps_when condition in the deployment method. A jump backwards is impossible.

 
jumps_when:
  - condition: my condition 1
    location:
      activity_short_name: target activity
      action_short_name: target action
      step_short_name: target step
    exit_return_code: n
  - condition: my condition 2
    location:
      activity_short_name: target activity
      action_short_name: target action
      step_short_name: target step
    exit_return_code: n
Note:
  • To know how to enter a condition, see Condition.
  • activity_short_name is mandatory if you want to specify an action_short_name.
  • activity_short_name and action_short_name are mandatory if you want to specify a step_short_name.
  • If only location is specified, the deployment jumps to this target location and continues from there.
  • If location and exit_return_code are specified, the deployment jumps to this target location. Then, the exit occurs after the target activity, action, or step if the result of this target activity, action, or step corresponds to the specified value of the exit_return_code.
rescue To go to a target activity, action, or step if an exception occurs during the current activity, action, or step. No condition is to be indicated.

Use short_name to designate the target location. This target location must have a short_name in its attributes.

The target location must be located after the activity, action, or step that contains the rescue condition in the deployment method. 

rescue
  - location:
      activity_short_name: target activity
      action_short_name: target action
      step_short_name: target step  
    exit_return_code: n
Note:
  • activity_short_name is mandatory if you want to specify an action_short_name.
  • activity_short_name and action_short_name are mandatory if you want to specify a step_short_name.
  • If only location is specified, the deployment jumps to this target location and continues from there.
  • If location and exit_return_code are specified, the deployment jumps to this target location. Then, the exit occurs after the target activity, action, or step if the result of this target activity, action, or step corresponds to the specified value of the exit_return_code.

Examples

Loop
You want to specify that a step is to run iteratively on each file of a list.
In the environment variables file, define a variable (include_vars_list in the example) that represents a list of file names.
include_vars_list:
  - files_list:
     - vars/vars1.yml
    files_must_exist: True
  - files_list:
    - vars/vars2.yml
    files_must_exist: True
  - files_list:
    - vars/vars3.yml
    files_must_exist: True
You can define a loop condition on a step to indicate that the step is to run iteratively with each value of the variable. So, in the following example, the include_vars variable will successively contain each member of the include_vars_list variable and the step will run with each of these members. 
activities:
  - name: INCLUDE_VARS
    actions:
        - name: INCLUDE_VARS
          steps:
          - name: INCLUDE_VARS
            properties:
            - key: var_include_vars
              value: include_vars
            loop:
              loop_query: environment.include_vars_list
              loop_var: include_vars
    is_artifact: False
when
To indicate that an activity is to run only if the evidence file contains an environment_name whose value is zos_host_01, enter the following query:
activities:
  - name: INCLUDE_VARS
    actions:
        - name: INCLUDE_VARS
          steps:
          - name: INCLUDE_VARS
            properties:
            - key: var_include_vars
              value: include_vars
            loop:
              loop_query: environment.include_vars_list
              loop_var: include_vars
            when:
               evidences.metadata.annotations.environment_name == 'zos_host_01'
    is_artifact: False
failed_when

To set the result of the INCLUDE_VARS step as Failed if the environment_name variable is valued to zos_host_01, enter the following query: 

activities:
  - name: INCLUDE_VARS
    actions:
        - name: INCLUDE_VARS
          steps:
          - name: INCLUDE_VARS
            properties:
            - key: var_include_vars
              value: include_vars
            loop:
              loop_query: environment.include_vars_list
              loop_var: include_vars
            when:
              evidences.metadata.annotations.environment_name == 'zos_host_01'
            failed_when:
              current_ev_step.step_result.status == 'Failed'
    is_artifact: False
jumps_when
To indicate that the CUSTOM_INCLUDE_VARS_FAILURE step (included in the INCLUDE_VARS action of the FAILURE activity) is to be run at the end of the current step only if the status of the current step is not OK, enter the following query. Use the short name of the activity, action, and step.
activities:
 - name: INCLUDE_VARS
   actions:
       - name: INCLUDE_VARS
         steps:
         - name: INCLUDE_VARS
           properties:
           - key: var_include_vars
             value: include_vars
           loop:
             loop_query: environment.include_vars_list
             loop_var: include_vars
           when:
              evidences.metadata.annotations.environment_name == 'zos_host_01'
           jumps_when:
             - condition: current_ev_step.step_result.status != 'Ok'
               location:
                 activity_short_name: FAILURE
                 action_short_name: INCLUDE_VARS
                 step_short_name: CUSTOM_INCLUDE_VARS_FAILURE
   is_artifact: False
 - name: FAILURE
   short_name: FAILURE
   actions:
       - name: INCLUDE_VARS
         short_name: INCLUDE_VARS
         steps:
         - name: CUSTOM_INCLUDE_VARS_FAILURE
           short_name: CUSTOM_INCLUDE_VARS_FAILURE
   is_artifact: False
rescue
To indicate that the deployment must jump to the CUSTOM_INCLUDE_VARS_FAILURE step if the current step fails, enter the following query. The exit will occur after this target step and the deployment will end with a -1 return code. 
activities:
 - name: INCLUDE_VARS
   actions:
       - name: INCLUDE_VARS
         steps:
         - name: INCLUDE_VARS
           properties:
           - key: var_include_vars
             value: include_vars
           rescue:
              location:
                 activity_short_name: FAILURE
                 action_short_name: INCLUDE_VARS
                 step_short_name: CUSTOM_INCLUDE_VARS_FAILURE
              exit_return_code: -1
   is_artifact: False
 - name: FAILURE
   short_name: FAILURE
   actions:
       - name: INCLUDE_VARS
         short_name: INCLUDE_VARS
         steps:
         - name: CUSTOM_INCLUDE_VARS_FAILURE
           short_name: CUSTOM_INCLUDE_VARS_FAILURE
   is_artifact: False

Syntax of a complex query

A complex query is the equivalent of a simple query but it is based on the JMESPath open source query language.

For example, you can indicate an array of values or a minimum or maximum value for the condition attributes, or add a sort to a list of attributes. For more information about JMESPath, see https://jmespath.org/.

Enter wd_query at the beginning of each complex query line and frame each condition with double brackets. The query fields are the same as those of a simple condition.
Example: To indicate that the activity, action, or step that contains the when condition is to run if the status of the PACKAGE step (in the PACKAGE action of the PACKAGE activity) is equal to OK, enter the following query:
when:
- wd_query [[evidences.activities[?name=='PACKAGE'] | [0].actions[?name=='PACKAGE'] | [0].steps[?name=='PACKAGE'] | [0].step_result.status]] == 'Ok'