Merge branch 'dev' into Enhancement/2167

Author: surendrababuravella

changelogs/fragments/2386-simple_role_to_get_job_status.yaml

@@ -0,0 +1,3 @@
+trivial:
+  - zos_job_query - Enhanced to return proper status of a job_id.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2386).

docs/Makefile

@@ -119,6 +119,7 @@ role-doc:
 		ansible-doc-extractor --template templates/role.rst.j2 source/roles ../roles/$$role_name/docs/doc_$$role_name.py; \
 		echo "Deleting generated metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
 		rm -rf ../roles/$$role_name/docs/doc_$$role_name.py; \
+		rm -rf ../roles/$$role_name/docs/doc_$$role_name.py-e; \
 	fi; \
 	done
 

docs/source/ansible_content.rst

@@ -28,4 +28,5 @@ expedite their proficiency in record time.
 
    plugins
    modules
-   filters
+   filters
+   roles

docs/source/roles.rst

@@ -0,0 +1,28 @@
+.. ...........................................................................
+.. © Copyright IBM Corporation 2021, 2025                                    .
+.. ...........................................................................
+Roles
+=======
+
+An Ansible role is a primary mechanism for organizing and reusing automation
+content in a modular and portable way. A role contains a set of related tasks,
+handlers, variables, and other Ansible artifacts that are packaged together to
+perform a specific function. Ansible executes the contents of the role when it
+is called from a playbook, allowing for the automation of complex,
+multi-step processes.
+
+The **IBM z/OS core** collection provides a set of roles designed to simplify
+automation on **z/OS**. These roles can be used in playbooks to identify and
+recommend migration actions between version 1 and version 2, collect
+diagnostic facts for support and debugging, and easily determine whether a job
+is currently running.
+
+The **IBM z/OS core** provides many roles.
+Reference material for each role contains documentation on how to use certain
+roles in your playbook.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   roles/*

docs/source/roles/job_status.rst

@@ -0,0 +1,77 @@
+
+:github_url: https://github.com/IBM/ibm_zosmf/tree/master/plugins/roles/job_status
+
+.. _job_status_module:
+
+
+job_status -- Role that query, extract job status and if is running.
+====================================================================
+
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- The **IBM z/ibm_zos_core collection** provides an Ansible role, referred to as **job_status**, to query a particular job with a given job_id and parse the response to return as a msg the job status and if the job is currently running or not.
+
+
+
+
+
+
+
+Variables
+---------
+
+
+ 
+
+job_id
+  The job id that has been assigned to the job.
+
+  A job id must begin with `STC`, `JOB`, `TSU` and are followed by up to 5 digits.
+
+  When a job id is greater than 99,999, the job id format will begin with `S`, `J`, `T` and are followed by 7 digits.
+
+  | **required**: True
+  | **type**: str
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+   
+   - name: Query the job status and if is running of the job STC00001
+     hosts: sampleHost
+     gather_facts: no
+     collections:
+       - ibm.ibm_zos_core
+     tasks:
+       - include_role:
+           name: job_status
+         vars:
+           job_oid: STC00001
+
+
+
+
+Notes
+-----
+
+.. note::
+   - The role tolerate the asterisk (`*`) as wildcard but only retrieve information from the first job returned that math the patter.
+
+
+
+
+
+
+
+

docs/templates/role.rst.j2

@@ -1,8 +1,10 @@
 {# ------------------------------------------------------------------------ #}
-{# © Copyright IBM Corporation 2020, 2021                                   #}
+{# Copyright (c) IBM Corporation 2021, 2025                                 #}
 {# ------------------------------------------------------------------------ #}
 
-.. _{{ module }}_role:
+:github_url: https://github.com/IBM/ibm_zosmf/tree/master/plugins/roles/{{ module }}
+
+.. _{{ module }}_module:
 
 {# ------------------------------------------------------------------------ #}
 {# Generate the title based on the role name and doc description            #}
@@ -12,13 +14,6 @@
 {{ title }}
 {{ '=' * title | length }}
 
-{# Disble this syle formatting in leu of list style #}
-{#    {%   for desc in description %}
-    {{ desc | rst_ify }}
-
-    {%   endfor %}
-#}
-
 {# ------------------------------------------------------------------------ #}
 {# Generate top level links                                                 #}
 {# ------------------------------------------------------------------------ #}
@@ -33,19 +28,17 @@
 
 Synopsis
 --------
-{% if description -%}
-
+{% if description %}
 {%   for desc in description %}
 - {{ desc | rst_ify }}
 {%   endfor %}
-
 {% endif %}
 
 {# ------------------------------------------------------------------------ #}
 {# Generate the dependencies based on the doc description                   #}
 {# ------------------------------------------------------------------------ #}
 
-{% if dependencies -%}
+{% if dependencies %}
 Dependencies
 ------------
 
@@ -57,7 +50,6 @@ The below requirements are needed on the host that executes this role.
 
 {% endif %}
 
-
 {# ------------------------------------------------------------------------ #}
 {# Parse options and format function                                        #}
 {# ------------------------------------------------------------------------ #}
@@ -66,27 +58,26 @@ The below requirements are needed on the host that executes this role.
 {# Control the order of options: true: ordered by name; false: keep source order #}
 {%   set sorted = false %}
 {%   for name, spec in (opts | dictsort if sorted else opts.items()) if not name.startswith('_') %}
-{%     set req = "required" if spec.required else "optional" %}
-
-{# if its a boolean we need to convert to a string for html #}
-{% if spec.type == 'bool' %}
-     {% set default_str = (spec.default | string | lower ) %}
-{% elif spec.type == 'int' %}
-     {% set default_str = (spec.default | string ) %}
-{% else %}
-     {% set default = ", default: " + spec.default if spec.default else "" %}
-{% endif %}
+
+{# Need to convert defalut value from bool or int to string for html display #} 
+{%     if spec.type == 'bool' or spec.type == 'int' %}
+{%       set default_str = (spec.default | string ) %}
+{%     else %}
+{%       set default_str = spec.default if spec.default else "" %}
+{%     endif %}
 
 {{ "  " * level }}{{ name }}
 {%     for para in spec.description %}
   {{ "  " * level }}{{ para | rst_ify }}
 
 {%     endfor %}
-
-  {{ "  " * level }}| **required**: {{ spec.required | default("False") }}
+  {{ "  " * level }}| **required**: {{ spec.required | string | default("False") }}
   {{ "  " * level }}| **type**: {{ spec.type | default("str") }}
-{%     if spec.default %}
-  {{ "  " * level }}| **default**: {{ spec.default }}
+{%     if spec.elements %}
+  {{ "  " * level }}| **elements**: {{ spec.elements }}
+{%     endif %}
+{%     if default_str != "" and default_str != "None" %}
+  {{ "  " * level }}| **default**: {{ default_str }}
 {%     endif %}
 {%     if spec.choices %}
   {{ "  " * level }}| **choices**: {{ ", ".join(spec.choices) }}
@@ -102,9 +93,9 @@ The below requirements are needed on the host that executes this role.
 {# Generate the options doc                                      #}
 {# ------------------------------------------------------------- #}
 
-{% if options -%}
-Parameters
-----------
+{% if options %}
+Variables
+---------
 
 {{ option_generation(options, 0) }}
 {% endif %}
@@ -120,92 +111,109 @@ Examples
 
 {{ examples | indent(3, True) }}
 
-
 {# ------------------------------------------------------------- #}
 {# Generate the notes doc                                        #}
 {# ------------------------------------------------------------- #}
 
-{% if notes -%}
+{% if notes %}
 Notes
 -----
 
 .. note::
 {%   for note in notes %}
-   {{ note | rst_ify }}
+   - {{ note | rst_ify }}
 
 {%   endfor %}
+
 {% endif %}
 
 {# ------------------------------------------------------------- #}
-{# Generate the see also doc                                     #}
+{# Generate the set also doc                                     #}
 {# ------------------------------------------------------------- #}
 
-{% if seealso -%}
+{% if seealso %}
 See Also
 --------
 
 .. seealso::
-
-{% for item in seealso %}
+{%   for item in seealso %}
    - :ref:`{{ item.module }}_module`
-{% endfor %}
+
+{%   endfor %}
+
 {% endif %}
 
 {# ------------------------------------------------------------- #}
 {# Return doc macro                                              #}
 {# ------------------------------------------------------------- #}
 
 {% macro result_generation(results, level) %}
+{%   for entry in results %}   
+{%     set _description  = results[entry].description %}
+{%     set _returned     = results[entry].returned %}
+{%     set _type         = results[entry].type %}
+{%     set _elements     = results[entry].elements %}
+{%     set _contains     = results[entry].contains %}
+{%     set _sample       = results[entry].sample %}
+
+{{ "  " * level }}{{ entry }}
+{%     if _description is iterable and _description is not string %}
+{%       for _para in _description %}
+  {{ "  " * level }}{{ _para | rst_ify }}
+
+{%       endfor %}
+{%     else %}
+  {{ "  " * level }}{{ _description | rst_ify }}
 
-   {% for entry in results %}
+{%     endif %}
+{%     if _returned %}
+  {{ "  " * level }}| **returned**: {{ _returned }}
+{%     endif %}
+{%     if _type %}
+  {{ "  " * level }}| **type**: {{ _type | default("str") }}
+{%     endif %}
+{%     if _elements %}
+  {{ "  " * level }}| **elements**: {{ _elements }}
+{%     endif %}
+{%     if _sample %}
+{%       if _sample.sample1 %}
+{%         if _type != 'str' and _type != 'int' %}
+  {{ "  " * level }}| **sample**:
 
-      {%  set _description  = results[entry].description %}
-      {%  set _returned     = results[entry].returned %}
-      {%  set _type         = results[entry].type %}
-      {%  set _contains     = results[entry].contains %}
-      {%  set _sample       = results[entry].sample %}
+{%           for _samplex in _sample %}
+  {{ "  " * level }}   .. code-block:: json
 
-      {{ entry | indent(level, True) }}
-      {% if _description is iterable and _description is not string %}
-{{ "  " * (level) }}| {{ _description[0] }}
-      {% else %}
-{{ "  " * (level) }}| {{ _description }}
-      {% endif %}
+  {{ "  " * level }}      {{ _sample[_samplex] | tojson(4) | indent(2*level+8) }}
 
-      {% if _returned %}
-{{ "  " * level }}| **returned**: {{ _returned }}
-      {% endif %}
-{{ "  " * level }}| **type**: {{ _type  }}
+{%           endfor %}
+{%         else %}
+  {{ "  " * level }}| **sample**:
 
-      {%- if _sample -%}
-      {% if _type != 'str' and _type != 'int' %}
-      
-      {{ "  " * level }}| **sample**:
+{%           for _samplex in _sample %}
+  {{ "  " * level }}  {{ _sample[_samplex] }}
 
-              .. code-block::
+{%           endfor %}
+{%         endif %}
+{%       else %}
+{%         if _type != 'str' and _type != 'int' %}
+  {{ "  " * level }}| **sample**:
 
-                       {{ _sample | tojson }}
-      {% else %}
+  {{ "  " * level }}   .. code-block:: json
 
-      {{ "  " * level }}| **sample**: {{ _sample }}
+  {{ "  " * level }}      {{ _sample | tojson(4) | indent(2*level+8) }}
 
-      {% endif %}
-      {% endif %}
+{%         else %}
+  {{ "  " * level }}| **sample**: {{ _sample }}
 
-      {% if _contains %}
-        {{ result_generation(_contains, level + 1) }}
-      {% endif %}
+{%         endif %}
+{%       endif %}
+{%     endif %}
+{%     if _contains %}
+{{ result_generation(_contains, level + 1) }}
+{%     endif %}
+{%   endfor %}
+{% endmacro %}
 
-      {% endfor  %}
-  {% endmacro %}
 {# ------------------------------------------------------------- #}
 {# Generate the return values doc                                #}
 {# ------------------------------------------------------------- #}
-
-{% if returndocs -%}
-Return Values
--------------
-
-{{ result_generation(returndocs,1) }}
-{% endif %}
-