Custom templating fix (#156)

* Add integration test for custom templating

* Change template to do_template

* Add doc note for templating limitation and correct ansible-core version in requirements

Author: andrewhughes101

docs/source/modules.rst

@@ -60,6 +60,8 @@ To override the data set location or name for a specific task, you can provide a
 additional parameter to the ``region_data_sets`` group as shown in the example 
 for a global catalog data set below.
 
+N.B. There is a known limitation with ansible-core version 2.15.0 and 2.15.1, where the custom templating may fail.
+
 .. code-block:: yaml+jinja
 
 

docs/source/requirements.rst

@@ -17,7 +17,7 @@ A control node is any machine with Ansible® installed. You can run commands and
 
 The following software must be installed on the control node:
 
-* `Ansible version`_ 2.14 or later
+* `Ansible version`_ 2.15 or later
 * `Python`_ 3.9 or later
 * z/OS core collection 1.5.0 or later, if you want to use the provisioning tasks provided by the **IBM® z/OS® CICS® collection**
 

plugins/plugin_utils/_module_action_plugin.py

@@ -155,7 +155,7 @@ def _template_dsn(_templar, task_vars, var_name, replace_val, template):
         variable_start_string="<<",
         variable_end_string=">>",
         available_variables=cpy,
-    ).template(template)
+    ).do_template(template, overrides=dict(variable_start_string="<<", variable_end_string=">>"))
 
 
 def _check_template(module_args, arg_dict):

tests/integration/targets/cics_templating/playbook.yml

@@ -0,0 +1,19 @@
+# (c) Copyright IBM Corp. 2025
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+---
+- name: Test custom templating
+  hosts: all
+  gather_facts: false
+  environment: "{{ environment_vars }}"
+
+  # The data set path is cretaed from {{ ansible_user }}.{{ data_set_unique }}.<< data_set_name >>
+  # e.g. USER.TEST1.DFHTEMP
+  vars:
+    data_set_unique: "{{ region_data_set_unique }}"
+
+  tasks:
+    - name: Create and delete auxiliary temporary storage data set
+      ansible.builtin.include_role:
+        name: aux_temp_storage
+      vars:
+        aux_temp_region_data_set_hlq: "{{ data_set_unique }}"

tests/integration/targets/cics_templating/roles/aux_temp_storage/action_plugins/process_input.py

@@ -0,0 +1,21 @@
+# (c) Copyright IBM Corp. 2025
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from ansible.plugins.action import ActionBase
+
+
+class ActionModule(ActionBase):
+
+    # Simple action plugin that just returns the ansible_user var
+
+    def run(self, tmp=None, task_vars=None):
+        super(ActionModule, self).run(tmp, task_vars)
+
+        processed_ouput = {
+            "name": task_vars["ansible_user"]
+        }
+
+        return processed_ouput

tests/integration/targets/cics_templating/roles/aux_temp_storage/meta/argument_specs.yml

@@ -0,0 +1,15 @@
+# (c) Copyright IBM Corp. 2025
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+---
+argument_specs:
+  main:
+    short_description: Templating test
+    description:
+      - Test custom templating
+    author:
+      - ibm_zos_cics
+    options:
+      aux_temp_region_data_set_hlq:
+        type: "str"
+        required: false
+        description: "HLQ to create the auxiliary temporary storage data set"

tests/integration/targets/cics_templating/roles/aux_temp_storage/meta/main.yml

@@ -0,0 +1,11 @@
+# (c) Copyright IBM Corp. 2025
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+---
+galaxy_info:
+  author: ibm_zos_cics
+  description: Templating test
+  company: IBM
+  license: Apache-2.0
+  min_ansible_version: "2.1"
+  galaxy_tags: []
+dependencies: []

tests/integration/targets/cics_templating/roles/aux_temp_storage/tasks/main.yml

@@ -0,0 +1,44 @@
+# (c) Copyright IBM Corp. 2025
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+---
+- name: Process Input data
+  process_input:
+  register: processed_input
+
+- name: Delete the DFHTEMP data set if it exists already
+  ibm.ibm_zos_core.zos_data_set:
+    name: "{{ processed_input.name }}.{{ aux_temp_region_data_set_hlq }}.DFHTEMP"
+    state: absent
+
+- name: Create the auxiliary temporary storage data set (DFHTEMP)
+  ibm.ibm_zos_cics.aux_temp_storage:
+    state: initial
+    region_data_sets:
+      template: "{{ processed_input.name }}.{{ aux_temp_region_data_set_hlq }}.<< data_set_name >>"
+  register: result
+
+- name: Assert data set created
+  ansible.builtin.assert:
+    that:
+      - result.failed == false
+      - result.changed == true
+      - result.start_state.exists == false
+      - result.end_state.exists == true
+      - result.msg == ""
+
+- name: Delete the auxiliary temporary storage data set (DFHTEMP)
+  ibm.ibm_zos_cics.aux_temp_storage:
+    state: absent
+    region_data_sets:
+      template: "{{ processed_input.name }}.{{ aux_temp_region_data_set_hlq }}.<< data_set_name >>"
+  register: result
+
+- name: Assert data set deleted (changed is true)
+  ansible.builtin.assert:
+    that:
+      - result.failed == false
+      - result.changed == true
+      - result.start_state.exists == true
+      - result.end_state.exists == false
+      - result.msg == ""
+      - "'executions' in result"

tests/integration/targets/cics_templating/runme.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# (c) Copyright IBM Corp. 2025
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+
+set -eux
+
+VAR_PATH="$ANSIBLE_COLLECTIONS_PATH/ansible_collections/ibm/ibm_zos_cics/tests/integration/variables/provisioning.yml"
+INV_PATH="$ANSIBLE_COLLECTIONS_PATH/ansible_collections/ibm/ibm_zos_cics/tests/integration/inventory_zos.yml"
+ZOS_ENV="$ANSIBLE_COLLECTIONS_PATH/ansible_collections/ibm/ibm_zos_cics/tests/integration/variables/zos.yml"
+
+ansible-playbook -i "$INV_PATH" -e "@$VAR_PATH" -e "@$ZOS_ENV" playbook.yml