template

With this building block, you can write templates to create shell scripts, JCLs, or any type of file. This building block is not related to artifacts.

You create your own templates in the folder of your choice. You must write them in Jinja2. For more information, see the Jinja2 documentation.

Then, you run the template building block to transform the Jinja2 files into the target files.

To trigger the execution of this building block, you can enter the following code in the deployment method from which the deployment plan is generated. See How to trigger the execution of a building block. The following code is an example.

actions:
    - name: CREATE FILES FROM A TEMPLATE
      short_name: CREATE_FROM_TEMPLATE 
      steps:
      - name: TEST STEP FOR TEMPLATE
        short_name: TEST_TEMPLATE
        properties:
        - key: template
          value: template
        - key: var_template_name
          value: templ01jcl

In this example, the value of the var_template_name property is templ01jcl, but it can be any other string.

If you do not indicate a var_template_name property in the deployment method, then the default value for this property (the template_name_default variable) is used.

In both cases, this value (templ01jcl or template_name_default) must be declared in the environment variables file. For Python, the entire path to this file is indicated in the --envFile argument of The Python deployment command.

To run correctly, this building block requires environment variables. Indicate them in a .yml file. Indicate The generic environment variables for the Ansible and Python building blocks and adapt their values to your target z/OS environment. Indicate also the variables that are specific to this building block.

The Ansible variables

The value of the var_template_name property or template_name_default variable must contain the following variables:

delegate
Boolean

Variable related to the dest variable. If you set the delegate variable to True (default value), the dest variable indicates a path on the Ansible controller. If you set the delegate variable to False, the dest variable indicates a path on the z/OS environment.

dest
String
Required

The full or relative path to the target file to be created on the Ansible controller or the z/OS environment, according to the value of the delegate variable.

group
String

The default name of the group that the target file belongs to.

mode
String

The permissions on the target file. For example, it can be '0755'.

owner
String

The default name of the user that the target file belongs to.

src
String
Required

The full or relative path to the Jinja2 source file, named a Jinja2 template, on the Ansible controller.

To know how to define the variables in your Jinja2 template, see The variables in the Jinja2 templates.

For example, in the deployment method sample code, you declared templ01jcl as the value of the var_template_name property. So, you can enter the following lines in the variables file. In this example, the target file is on the Ansible controller.
templ01jcl:
  src: "source_templates/test01-jcl.j2"
  dest: "source_templates/test01.jcl"
  mode: '0777'
  owner: testuser
  group: test_team
For example, you can declare the template_name_default variable with the following values in the environment variables file. In this example, the target file is on the z/OS environment.
template_name_default:
   src: "spec_templates/ex01-sh.j2"
   delegate: False
   dest: "/tmp/ex01.sh"
   owner: user01
   group: wd_devteam
   mode: '0755'

The Python variables

The value of the var_template_name property or template_name_default variable must contain the following variables:

dest
String
Required

The full or relative path to the target file to be created.

mode
Integer

The permissions on the target file. For example, it can be 0755.

search_paths

List

The variable that indicates the list of paths where included Jinja2 templates are stored.

src
String
Required

The full or relative path to the Jinja2 source file, named a Jinja2 template, on the local file system.

To know how to define the variables in your Jinja2 template, see The variables in the Jinja2 templates.

For example, in the deployment method sample code, you declared templ01jcl as the value of the var_template_name property. So, you can enter the following lines in the variables file. In this example, the target file is on the Ansible controller.
templ01jcl:
  src: "source_templates/test01-jcl.j2"
  dest: "wd_test/inventory_hostname_test01.jcl"
  mode: 0777
For example, you can declare the template_name_default variable with the following values in the environment variables file:
template_name_default:
   src: "HELLO-jcl.j2"
   dest: "/tmp/my_jcl/HELLO.jcl"
   mode: 0755
   search_paths:
   - "{{working_folder}}/include"

Return values

The result of each building block task is displayed in the evidence file, in The results level that is embedded in step_result.