Skip to content

Commit ab27675

Browse files
AndreMarcel99André Marcel Gutiérrez Benítezfernandofloresg
authored
[Role][1625]simple_role_to_get_job_status (#2386)
* Add folder of structure * First iteration of the role * Add test case * Fix bad imports * Add fragment * Add documentation of the role * Updated role doc generation * Updated makefile to remove residuals * Updated docs * Updated ansible content * Align documentation * Update README.md * To try to validate dependency finder * Fix dependencyfinder * Handle errors and add to job status * Avoid make None all * Update roles/job_status/README.md Co-authored-by: Fernando Flores <[email protected]> * Update roles/job_status/README.md Co-authored-by: Fernando Flores <[email protected]> * Fix sanity * Fix sanity --------- Co-authored-by: André Marcel Gutiérrez Benítez <[email protected]> Co-authored-by: Fernando Flores <[email protected]>
1 parent 79e466e commit ab27675

File tree

12 files changed

+435
-87
lines changed

12 files changed

+435
-87
lines changed

‎changelogs/fragments/2386-simple_role_to_get_job_status.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
trivial:
2+
- zos_job_query - Enhanced to return proper status of a job_id.
3+
(https://github.com/ansible-collections/ibm_zos_core/pull/2386).

‎docs/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,7 @@ role-doc:
119119
ansible-doc-extractor --template templates/role.rst.j2 source/roles ../roles/$$role_name/docs/doc_$$role_name.py; \
120120
echo "Deleting generated metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
121121
rm -rf ../roles/$$role_name/docs/doc_$$role_name.py; \
122+
rm -rf ../roles/$$role_name/docs/doc_$$role_name.py-e; \
122123
fi; \
123124
done
124125

‎docs/source/ansible_content.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,5 @@ expedite their proficiency in record time.
2828

2929
plugins
3030
modules
31-
filters
31+
filters
32+
roles

‎docs/source/roles.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. ...........................................................................
2+
.. © Copyright IBM Corporation 2021, 2025 .
3+
.. ...........................................................................
4+
Roles
5+
=======
6+
7+
An Ansible role is a primary mechanism for organizing and reusing automation
8+
content in a modular and portable way. A role contains a set of related tasks,
9+
handlers, variables, and other Ansible artifacts that are packaged together to
10+
perform a specific function. Ansible executes the contents of the role when it
11+
is called from a playbook, allowing for the automation of complex,
12+
multi-step processes.
13+
14+
The **IBM z/OS core** collection provides a set of roles designed to simplify
15+
automation on **z/OS**. These roles can be used in playbooks to identify and
16+
recommend migration actions between version 1 and version 2, collect
17+
diagnostic facts for support and debugging, and easily determine whether a job
18+
is currently running.
19+
20+
The **IBM z/OS core** provides many roles.
21+
Reference material for each role contains documentation on how to use certain
22+
roles in your playbook.
23+
24+
.. toctree::
25+
:maxdepth: 1
26+
:glob:
27+
28+
roles/*

‎docs/source/roles/job_status.rst‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
2+
:github_url: https://github.com/IBM/ibm_zosmf/tree/master/plugins/roles/job_status
3+
4+
.. _job_status_module:
5+
6+
7+
job_status -- Role that query, extract job status and if is running.
8+
====================================================================
9+
10+
11+
.. contents::
12+
:local:
13+
:depth: 1
14+
15+
16+
Synopsis
17+
--------
18+
- 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.
19+
20+
21+
22+
23+
24+
25+
26+
Variables
27+
---------
28+
29+
30+
31+
32+
job_id
33+
The job id that has been assigned to the job.
34+
35+
A job id must begin with `STC`, `JOB`, `TSU` and are followed by up to 5 digits.
36+
37+
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.
38+
39+
| **required**: True
40+
| **type**: str
41+
42+
43+
44+
45+
Examples
46+
--------
47+
48+
.. code-block:: yaml+jinja
49+
50+
51+
- name: Query the job status and if is running of the job STC00001
52+
hosts: sampleHost
53+
gather_facts: no
54+
collections:
55+
- ibm.ibm_zos_core
56+
tasks:
57+
- include_role:
58+
name: job_status
59+
vars:
60+
job_oid: STC00001
61+
62+
63+
64+
65+
Notes
66+
-----
67+
68+
.. note::
69+
- The role tolerate the asterisk (`*`) as wildcard but only retrieve information from the first job returned that math the patter.
70+
71+
72+
73+
74+
75+
76+
77+

‎docs/templates/role.rst.j2‎

Lines changed: 86 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
{# ------------------------------------------------------------------------ #}
2-
{# © Copyright IBM Corporation 2020, 2021 #}
2+
{# Copyright (c) IBM Corporation 2021, 2025 #}
33
{# ------------------------------------------------------------------------ #}
44

5-
.. _{{ module }}_role:
5+
:github_url: https://github.com/IBM/ibm_zosmf/tree/master/plugins/roles/{{ module }}
6+
7+
.. _{{ module }}_module:
68

79
{# ------------------------------------------------------------------------ #}
810
{# Generate the title based on the role name and doc description #}
@@ -12,13 +14,6 @@
1214
{{ title }}
1315
{{ '=' * title | length }}
1416

15-
{# Disble this syle formatting in leu of list style #}
16-
{# {% for desc in description %}
17-
{{ desc | rst_ify }}
18-
19-
{% endfor %}
20-
#}
21-
2217
{# ------------------------------------------------------------------------ #}
2318
{# Generate top level links #}
2419
{# ------------------------------------------------------------------------ #}
@@ -33,19 +28,17 @@
3328

3429
Synopsis
3530
--------
36-
{% if description -%}
37-
31+
{% if description %}
3832
{% for desc in description %}
3933
- {{ desc | rst_ify }}
4034
{% endfor %}
41-
4235
{% endif %}
4336

4437
{# ------------------------------------------------------------------------ #}
4538
{# Generate the dependencies based on the doc description #}
4639
{# ------------------------------------------------------------------------ #}
4740

48-
{% if dependencies -%}
41+
{% if dependencies %}
4942
Dependencies
5043
------------
5144

@@ -57,7 +50,6 @@ The below requirements are needed on the host that executes this role.
5750

5851
{% endif %}
5952

60-
6153
{# ------------------------------------------------------------------------ #}
6254
{# Parse options and format function #}
6355
{# ------------------------------------------------------------------------ #}
@@ -66,27 +58,26 @@ The below requirements are needed on the host that executes this role.
6658
{# Control the order of options: true: ordered by name; false: keep source order #}
6759
{% set sorted = false %}
6860
{% for name, spec in (opts | dictsort if sorted else opts.items()) if not name.startswith('_') %}
69-
{% set req = "required" if spec.required else "optional" %}
70-
71-
{# if its a boolean we need to convert to a string for html #}
72-
{% if spec.type == 'bool' %}
73-
{% set default_str = (spec.default | string | lower ) %}
74-
{% elif spec.type == 'int' %}
75-
{% set default_str = (spec.default | string ) %}
76-
{% else %}
77-
{% set default = ", default: " + spec.default if spec.default else "" %}
78-
{% endif %}
61+
62+
{# Need to convert defalut value from bool or int to string for html display #}
63+
{% if spec.type == 'bool' or spec.type == 'int' %}
64+
{% set default_str = (spec.default | string ) %}
65+
{% else %}
66+
{% set default_str = spec.default if spec.default else "" %}
67+
{% endif %}
7968

8069
{{ " " * level }}{{ name }}
8170
{% for para in spec.description %}
8271
{{ " " * level }}{{ para | rst_ify }}
8372

8473
{% endfor %}
85-
86-
{{ " " * level }}| **required**: {{ spec.required | default("False") }}
74+
{{ " " * level }}| **required**: {{ spec.required | string | default("False") }}
8775
{{ " " * level }}| **type**: {{ spec.type | default("str") }}
88-
{% if spec.default %}
89-
{{ " " * level }}| **default**: {{ spec.default }}
76+
{% if spec.elements %}
77+
{{ " " * level }}| **elements**: {{ spec.elements }}
78+
{% endif %}
79+
{% if default_str != "" and default_str != "None" %}
80+
{{ " " * level }}| **default**: {{ default_str }}
9081
{% endif %}
9182
{% if spec.choices %}
9283
{{ " " * level }}| **choices**: {{ ", ".join(spec.choices) }}
@@ -102,9 +93,9 @@ The below requirements are needed on the host that executes this role.
10293
{# Generate the options doc #}
10394
{# ------------------------------------------------------------- #}
10495

105-
{% if options -%}
106-
Parameters
107-
----------
96+
{% if options %}
97+
Variables
98+
---------
10899

109100
{{ option_generation(options, 0) }}
110101
{% endif %}
@@ -120,92 +111,109 @@ Examples
120111

121112
{{ examples | indent(3, True) }}
122113

123-
124114
{# ------------------------------------------------------------- #}
125115
{# Generate the notes doc #}
126116
{# ------------------------------------------------------------- #}
127117

128-
{% if notes -%}
118+
{% if notes %}
129119
Notes
130120
-----
131121

132122
.. note::
133123
{% for note in notes %}
134-
{{ note | rst_ify }}
124+
- {{ note | rst_ify }}
135125

136126
{% endfor %}
127+
137128
{% endif %}
138129

139130
{# ------------------------------------------------------------- #}
140-
{# Generate the see also doc #}
131+
{# Generate the set also doc #}
141132
{# ------------------------------------------------------------- #}
142133

143-
{% if seealso -%}
134+
{% if seealso %}
144135
See Also
145136
--------
146137

147138
.. seealso::
148-
149-
{% for item in seealso %}
139+
{% for item in seealso %}
150140
- :ref:`{{ item.module }}_module`
151-
{% endfor %}
141+
142+
{% endfor %}
143+
152144
{% endif %}
153145

154146
{# ------------------------------------------------------------- #}
155147
{# Return doc macro #}
156148
{# ------------------------------------------------------------- #}
157149

158150
{% macro result_generation(results, level) %}
151+
{% for entry in results %}
152+
{% set _description = results[entry].description %}
153+
{% set _returned = results[entry].returned %}
154+
{% set _type = results[entry].type %}
155+
{% set _elements = results[entry].elements %}
156+
{% set _contains = results[entry].contains %}
157+
{% set _sample = results[entry].sample %}
158+
159+
{{ " " * level }}{{ entry }}
160+
{% if _description is iterable and _description is not string %}
161+
{% for _para in _description %}
162+
{{ " " * level }}{{ _para | rst_ify }}
163+
164+
{% endfor %}
165+
{% else %}
166+
{{ " " * level }}{{ _description | rst_ify }}
159167

160-
{% for entry in results %}
168+
{% endif %}
169+
{% if _returned %}
170+
{{ " " * level }}| **returned**: {{ _returned }}
171+
{% endif %}
172+
{% if _type %}
173+
{{ " " * level }}| **type**: {{ _type | default("str") }}
174+
{% endif %}
175+
{% if _elements %}
176+
{{ " " * level }}| **elements**: {{ _elements }}
177+
{% endif %}
178+
{% if _sample %}
179+
{% if _sample.sample1 %}
180+
{% if _type != 'str' and _type != 'int' %}
181+
{{ " " * level }}| **sample**:
161182

162-
{% set _description = results[entry].description %}
163-
{% set _returned = results[entry].returned %}
164-
{% set _type = results[entry].type %}
165-
{% set _contains = results[entry].contains %}
166-
{% set _sample = results[entry].sample %}
183+
{% for _samplex in _sample %}
184+
{{ " " * level }} .. code-block:: json
167185

168-
{{ entry | indent(level, True) }}
169-
{% if _description is iterable and _description is not string %}
170-
{{ " " * (level) }}| {{ _description[0] }}
171-
{% else %}
172-
{{ " " * (level) }}| {{ _description }}
173-
{% endif %}
186+
{{ " " * level }} {{ _sample[_samplex] | tojson(4) | indent(2*level+8) }}
174187

175-
{% if _returned %}
176-
{{ " " * level }}| **returned**: {{ _returned }}
177-
{% endif %}
178-
{{ " " * level }}| **type**: {{ _type }}
188+
{% endfor %}
189+
{% else %}
190+
{{ " " * level }}| **sample**:
179191

180-
{%- if _sample -%}
181-
{% if _type != 'str' and _type != 'int' %}
182-
183-
{{ " " * level }}| **sample**:
192+
{% for _samplex in _sample %}
193+
{{ " " * level }} {{ _sample[_samplex] }}
184194

185-
.. code-block::
195+
{% endfor %}
196+
{% endif %}
197+
{% else %}
198+
{% if _type != 'str' and _type != 'int' %}
199+
{{ " " * level }}| **sample**:
186200

187-
{{ _sample | tojson }}
188-
{% else %}
201+
{{ " " * level }} .. code-block:: json
189202

190-
{{ " " * level }}| **sample**: {{ _sample }}
203+
{{ " " * level }} {{ _sample | tojson(4) | indent(2*level+8) }}
191204

192-
{% endif %}
193-
{% endif %}
205+
{% else %}
206+
{{ " " * level }}| **sample**: {{ _sample }}
194207

195-
{% if _contains %}
196-
{{ result_generation(_contains, level + 1) }}
197-
{% endif %}
208+
{% endif %}
209+
{% endif %}
210+
{% endif %}
211+
{% if _contains %}
212+
{{ result_generation(_contains, level + 1) }}
213+
{% endif %}
214+
{% endfor %}
215+
{% endmacro %}
198216

199-
{% endfor %}
200-
{% endmacro %}
201217
{# ------------------------------------------------------------- #}
202218
{# Generate the return values doc #}
203219
{# ------------------------------------------------------------- #}
204-
205-
{% if returndocs -%}
206-
Return Values
207-
-------------
208-
209-
{{ result_generation(returndocs,1) }}
210-
{% endif %}
211-

0 commit comments

Comments
 (0)