Merge pull request #267 from stewartfrancis/refresh_tags

Refresh tags sample

zos_subsystems/cics/README.md

@@ -32,6 +32,19 @@ This repository provides a number of samples that show how to use the CICS colle
 
     The `set_ca` sample shows how to use the CMCI modules with a custom CA bundle, typically useful when you have an internal CA.
 
+1. [Refresh tags](cmci/refresh_tags)
+
+    The `refresh_tags` sample shows how to instruct a CICS region to refresh
+    its tags by re-reading the tags file on USS.  This is achieved by using
+    the `cmci_action` module.  This sample also documents how to determine
+    the appropriate parameters for the `cmci_action` module for the action
+    you're trying to run.
+
+1. [Provisioning](provisioning/)
+
+    The `provisioning` sample shows how use the modules in the CICS collection
+    to provision a CICS region from scratch.
+
 ---
 
 These CICS samples are just some of the samples available for the Red Hat Ansible Certified Content for IBM Z. You can find samples covering other aspects at the [root of the repository](https://github.com/IBM/z_ansible_collections_samples).

zos_subsystems/cics/cmci/deploy_program/deploy_program.yml

@@ -29,7 +29,7 @@
           - typing;python_version<"3.5"
 
     ############################################################################
-    # Install module dependencies
+    # NEWCOPY PROGRAM in CICS
     ############################################################################
     - name: NEWCOPY PROGRAM in CICS
       delegate_to: localhost

zos_subsystems/cics/cmci/refresh_tags/README.md

@@ -0,0 +1,54 @@
+# Using the CICS collection to refresh a region's tags
+
+This sample playbook demonstrates how to use the `cmci_action` module from the `ibm_zos_cics` collection to run an action against a CICS resource.
+Additionally, this readme documents how to determine the appropriate Ansible
+module configuration, if you're trying to automate something you know how
+to do in CICS Explorer
+
+## Requirements
+
+- Python 3.5+
+- Ansible 2.15+
+- IBM z/OS CICS Ansible collection 2.1.0+
+
+## Getting Started
+
+As this sample only uses the `cmci_action` module, no inventory is required, as
+it can execute directly on the Ansible control node.
+
+Variables must be supplied for the CMCI connection details.  Dummy variables are
+provided in `group_vars/all.yml`, which you must edit to supply the CMCI 
+connection details:
+
+- `cmci_host` - Target CMCI hostname
+- `cmci_port` - Target CMCI port
+- `cmci_scheme` - CMCI scheme (http or https)
+- `context` - Target CICSplex SM context
+- `scope` - Target CICSplex SM scope
+
+The playbook will prompt for the CMCI user name and password when it executes.
+
+## Usage
+```bash
+ansible-playbook refresh_tags.yml
+```
+
+## How to determine CMCI module parameters
+
+You can use CICS Explorer to tell a CICS region to re-read its tags file 
+by right-clicking on a row in the "Regions" view and selecting "Refresh tags".
+
+From this, we can determine that CMCI request runs against a CICS Region.
+In order to use the `cmci_action` module to execute the same request we 
+need to determine the CMCI resource name, and the action name.
+
+The Regions view corresponds to the `CICSRGN` resource table.  Consulting the
+[documentation](https://www.ibm.com/docs/en/cics-ts/latest?topic=tables-cicsrgn-resource-table) for that table, we can find the 
+"External resource name (CMCI)" information, which is `CICSRegion`.  This is
+the value we've filled in for the `type` parameter of the `cmci_action` module.
+
+The action names can be found on the same page.  By looking at the available
+actions we can identify that `TAGSREFR` is the name of the action we're looking
+to run.  We've filled that in for the `action_name` parameter of the module.
+
+As this action has no further parameters, we're done!  If the action did have parameters, they're also documented on the same page.

zos_subsystems/cics/cmci/refresh_tags/group_vars/all.yml

@@ -0,0 +1,14 @@
+# Target CMCI hostname
+cmci_host: example.com
+
+# Target CMCI port
+cmci_port: 12345
+
+# CMCI scheme (http or https)
+scheme: https
+
+# Target CICSplex SM context
+context: MYPLEX
+
+# Target CICSplex SM scope
+scope: MYRGN

zos_subsystems/cics/cmci/refresh_tags/refresh_tags.yml

@@ -0,0 +1,40 @@
+# (c) Copyright IBM Corporation 2024
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+---
+- name: Refresh region tags
+
+  hosts: localhost
+  gather_facts: false
+
+  vars_prompt:
+    - name: cmci_user
+      prompt: CMCI user name (leave blank for unauthenticated)
+      private: false
+    - name: cmci_password
+      prompt: CMCI password (leave blank for unauthenticated)
+
+  tasks:
+    ############################################################################
+    # Install cmci_action module dependencies
+    ############################################################################
+    - name: Make sure CMCI module dependencies are installed
+      ansible.builtin.pip:
+        name:
+          - requests
+          - xmltodict
+          - typing;python_version<"3.5"
+
+    ############################################################################
+    # Use cmci_action to tell region to refresh tags
+    ############################################################################
+    - name: Refresh tags from tag file on USS
+      ibm.ibm_zos_cics.cmci_action:
+        context: "{{ context }}"
+        scope: "{{ scope }}"
+        cmci_host: "{{ cmci_host }}"
+        cmci_port: "{{ cmci_port | int }}"
+        cmci_user: "{{ cmci_user | default(omit) }}"
+        cmci_password: "{{ cmci_password | default(omit) }}"
+        scheme: "{{ scheme }}"
+        action_name: TAGSREFR
+        type: CICSRegion

zos_subsystems/cics/cmci/reporting/README.md

@@ -55,7 +55,7 @@ You can run the playbook without modification:
 
 ```bash
 ansible-playbook report.yml
-````
+```
 
 The playbook will prompt for required parameters. After parameters have been supplied, the playbook installs the
 CMCI module dependencies to the python environment. The playbook makes a CMCI GET request to regions in the supplied