External-Mirrors/awx
2
0
Fork 0
mirror of https://github.com/ansible/awx.git synced 2026-01-11 01:57:35 -03:30
Code Issues Packages Projects Releases Wiki Activity

Fix: #14523 Add alt-text codeblock to Images for workflow_template.rst (#14604)

Browse Source 
* add alt to images in workflow_templates.rst

Signed-off-by: Ratan Gulati <ratangulati.dev@gmail.com>

* add alt to images in workflow_templates.rst

Signed-off-by: Ratan Gulati <ratangulati.dev@gmail.com>

* Update workflow_templates.rst

* Revised proposed alt text for workflow_templates.rst

---------

Signed-off-by: Ratan Gulati <ratangulati.dev@gmail.com>
Co-authored-by: TVo <thavo@redhat.com>
This commit is contained in:
Ratan Gulati 2023-11-07 23:21:11 +05:30 committed by GitHub
parent 71d548f9e5
commit 40c2b700fe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 69 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/docsite/rst/userguide/workflow_templates.rst
View File

@ -15,18 +15,16 @@ A :term:`workflow job template` links together a sequence of disparate resources
The **Templates** menu opens a list of the workflow and job templates that are currently available. The default view is collapsed (Compact), showing the template name, template type, and the statuses of the jobs that ran using that template, but you can click **Expanded** to view more information. This list is sorted alphabetically by name, but you can sort by other criteria, or search by various fields and attributes of a template. From this screen, you can launch (|launch|), edit (|edit|), and copy (|copy|) a workflow job template.
.. |delete| image:: ../common/images/delete-button.png
Only workflow templates have the Workflow Visualizer icon (|wf-viz-icon|) as a shortcut for accessing the workflow editor.
.. |wf-viz-icon| image:: ../common/images/wf-viz-icon.png
:alt: Workflow vizualizer icon
|Wf templates - home with example wf template|
.. |Wf templates - home with example wf template| image:: ../common/images/wf-templates-home-with-example-wf-template.png
:alt: Job templates list view with example of workflow template and arrow pointing to the Workflow vizualizer icon.
.. note::
@ -41,10 +39,12 @@ To create a new workflow job template:
1. Click the |add options template| button then select **Workflow Template** from the menu list.
.. |add options template| image:: ../common/images/add-options-template.png
:alt: Create new template Add drop-down options.
|Wf templates - create new wf template|
.. |Wf templates - create new wf template| image:: ../common/images/wf-templates-create-new-wf-template.png
:alt: Create new workflow template form.
2. Enter the appropriate details into the following fields:
@ -53,6 +53,9 @@ To create a new workflow job template:
If a field has the **Prompt on launch** checkbox selected, launching the workflow template, or when the workflow template is used within another workflow template, it will prompt for the value for that field upon launch. Most prompted values will override any values set in the workflow job template; exceptions are noted below.
.. |delete| image:: ../common/images/delete-button.png
:alt: Delete button.
.. list-table::
:widths: 10 35 30
:header-rows: 1
@ -106,9 +109,11 @@ To create a new workflow job template:
For more information about **Job Tags** and **Skip Tags**, refer to `Tags <https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html>`_ in the Ansible documentation.
.. |x-circle| image:: ../common/images/x-delete-button.png
:alt: x delete button
.. |x| image:: ../common/images/x-button.png
:alt: x button
3. **Options**: Specify options for launching this workflow job template, if necessary.
@ -136,6 +141,7 @@ For more information about **Job Tags** and **Skip Tags**, refer to `Tags <https
Saving the template exits the workflow template page and the Workflow Visualizer opens to allow you to build a workflow. See the :ref:`ug_wf_editor` section for further instructions. Otherwise, you may close the Workflow Visualizer to return to the Details tab of the newly saved template in order to review, edit, add permissions, notifications, schedules, and surveys, or view completed jobs and build a workflow template at a later time. Alternatively, you can click **Launch** to launch the workflow, but you must first save the template prior to launching, otherwise, the **Launch** button remains grayed-out. Also, note the **Notifications** tab is present only after the template has been saved.
.. image:: ../common/images/wf-templates-wf-template-saved.png
:alt: Details tab of the newly created workflow template.
@ -146,6 +152,8 @@ Work with Permissions
Clicking on **Access** allows you to review, grant, edit, and remove associated permissions for users as well as team members.
.. image:: ../common/images/wf-template-completed-permissions-view.png
:alt: Access tab of the newly created workflow template showing two user roles and their permissions.
Click the **Add** button to create new permissions for this workflow template by following the prompts to assign them accordingly.
@ -156,13 +164,15 @@ Work with Notifications
Clicking on **Notifications** allows you to review any notification integrations you have setup. The **Notifications** tab is present only after the template has been saved.
.. .. image:: ../common/images/wf-template-completed-notifications-view.png
.. image:: ../common/images/wf-template-completed-notifications-view.png
:alt: Notifications tab of the newly created workflow template showing four notification configurations with one notification set for Approval.
Use the toggles to enable or disable the notifications to use with your particular template. For more detail, see :ref:`ug_notifications_on_off`.
If no notifications have been set up, see :ref:`ug_notifications_create` for detail.
.. image:: ../common/images/wf-template-no-notifications-blank.png
:alt: Notifications tab of the newly created workflow template showing no notifications set up.
Refer to :ref:`ug_notifications_types` for additional details on configuring various notification types.
@ -174,20 +184,14 @@ View Completed Jobs
The **Completed Jobs** tab provides the list of workflow templates that have ran. Click **Expanded** to view the various details of each job.
.. .. image:: ../common/images/wf-template-completed-jobs-list.png
.. image:: ../common/images/wf-template-completed-jobs-list.png
:alt: Jobs tab of the example workflow template showing completed jobs.
From this view, you can click the job ID - name of the workflow job and see its graphical representation. The example below shows the job details of a workflow job.
.. image:: ../common/images/wf-template-jobID-detail-example.png
.. If a workflow template is used in another workflow, the jobs details indicate a parent workflow.
.. .. image:: ../common/images/wf-template-job-detail-with-parent.png
.. In the above example, click the parent workflow template, **Overall**, to view its Job Details page and the graphical details of the nodes and statuses of each as they were launched.
.. .. image:: ../common/images/wf-template-jobs-detail-example.png
:alt: Details of the job output for the selected workflow template by job ID
The nodes are marked with labels that help you identify them at a glance. See the legend_ in the :ref:`ug_wf_editor` section for more information.
@ -201,6 +205,7 @@ Work with Schedules
Clicking on **Schedules** allows you to review any schedules set up for this template.
.. .. image:: ../common/images/templates-schedules-example-list.png
:alt: workflow template - schedule list example
@ -246,8 +251,8 @@ To create a survey:
1. Click the **Survey** tab to bring up the **Add Survey** window.
.. figure:: ../common/images/wf-template-create-survey.png
:alt: Workflow Job Template - create survey
.. image:: ../common/images/wf-template-create-survey.png
:alt: Workflow Job Template showing the Create survey form.
Use the **ON/OFF** toggle button at the top of the screen to quickly activate or deactivate this survey prompt.
@ -283,6 +288,7 @@ A stylized version of the survey is presented in the Preview pane. For any quest
|Workflow-template-completed-survey|
.. |Workflow-template-completed-survey| image:: ../common/images/wf-template-completed-survey.png
:alt: Workflow Job Template showing completed survey and arrows pointing to the re-ordering icons.
Optional Survey Questions
@ -324,16 +330,20 @@ You can set up any combination of two or more of the following node types to bui
1. In the details/edit view of a workflow template, click the **Visualizer** tab or from the Templates list view, click the (|wf-viz-icon|) icon to launch the Workflow Visualizer.
.. image:: ../common/images/wf-editor-create-new.png
:alt: Workflow Visualizer start page.
2. Click the |start| button to display a list of nodes to add to your workflow.
.. |start| image:: ../common/images/wf-start-button.png
:alt: Workflow Visualizer Start button.
.. image:: ../common/images/wf-editor-create-new-add-template-list.png
:alt: Workflow Visualizer wizard, step 1 specifying the node type.
3. On the right pane, select the type of node you want to add from the drop-down menu:
.. image:: ../common/images/wf-add-node-selections.png
:alt: Node type showing the drop-down menu of node type options.
If selecting an **Approval** node, see :ref:`ug_wf_approval_nodes` for further detail.
@ -360,7 +370,7 @@ For subsequent nodes, you can select one of the following scenarios (edge type)
- Choose **All** to ensure that *all* nodes complete as specified, before converging and triggering the next node. The purpose of ALL nodes is to make sure that every parent met it's expected outcome in order to run the child node. The workflow checks to make sure every parent behaved as expected in order to run the child node. Otherwise, it will not run the child node.
If selected, the graphical view will label the node as **ALL**.
If selected, the graphical view will indicate the node type with a representative color. Refer to the legend (|compass|) to see the corresponding run scenario and their job types.
.. note::
@ -370,43 +380,51 @@ For subsequent nodes, you can select one of the following scenarios (edge type)
7. If a job template used in the workflow has **Prompt on Launch** selected for any of its parameters, a **Prompt** button appears, allowing you to change those values at the node level. Use the wizard to change the value(s) in each of the tabs and click **Confirm** in the Preview tab.
.. image:: ../common/images/wf-editor-prompt-button-wizard.png
:alt: Workflow Visualizer wizard with Prompt on Launch options.
Likewise, if a workflow template used in the workflow has **Prompt on Launch** selected for the inventory option, use the wizard to supply the inventory at the prompt. If the parent workflow has its own inventory, it will override any inventory that is supplied here.
.. image:: ../common/images/wf-editor-prompt-button-inventory-wizard.png
:alt: Workflow Visualizer wizard with Prompt on Launch for Inventory.
.. note::
For workflow job templates with promptable fields that are required, but do not have a default, you must provide those values when creating a node before the **Select** button becomes enabled. The two cases that disable the **Select** button until a value is provided via the **Prompt** button: 1) when you select the **Prompt on Launch** checkbox in a workflow job template, but do not provide a default, or 2) when you create a survey question that is required but do not provide a default answer. However, this is **NOT** the case with credentials. Credentials that require a password on launch are **not permitted** when creating a workflow node, since everything needed to launch the node must be provided when the node is created. So, if a workflow job template prompts for credentials, AWX prevents you from being able to select a credential that requires a password.
You must also click **Select** when the prompt wizard closes in order to apply the changes at that node. Otherwise, any changes you make will revert back to the values set in the actual job template.
Once the node is created, it is labeled with its job type. A template that is associated with each workflow node will run based on the selected run scenario as it proceeds. Click the compass (|compass|) icon to display the legend for each run scenario and their job types.
.. _legend:
.. |compass| image:: ../common/images/wf-editor-compass-button.png
:alt: Workflow Visualizer legend button.
.. image:: ../common/images/wf-editor-key-dropdown-list.png
:alt: Workflow Visualizer legend expanded.
8. Hovering over a node allows you to add |add node| another node, view info |info node| about the node, edit |edit| the node details, edit an existing link |edit link|, or delete |delete node| the selected node.
.. |add node| image:: ../common/images/wf-editor-add-button.png
:alt: Add node icon.
.. |edit link| image:: ../common/images/wf-editor-edit-link.png
:alt: Edit link icon.
.. |delete node| image:: ../common/images/wf-editor-delete-button.png
:alt: Delete node icon.
.. |info node| image:: ../common/images/wf-editor-info-button.png
:alt: View node details icon.
.. |edit| image:: ../common/images/edit-button.png
:alt: Edit node details icon.
.. image:: ../common/images/wf-editor-create-new-add-template.png
:alt: Building a new example workflow job template in the Workflow Visualizer
9. When done adding/editing a node, click **Select** to save any modifications and render it on the graphical view. For possible ways to build your workflow, see :ref:`ug_wf_building_scenarios`.
9. When done adding/editing a node, click **Save** to save any modifications and render it on the graphical view. For possible ways to build your workflow, see :ref:`ug_wf_building_scenarios`.
10. When done with building your workflow template, click **Save** to save your entire workflow template and return to the new workflow template details page.
.. important::
Clicking **Close** on this pane will not save your work, but instead, closes the entire Workflow Visualizer and you will have to start over.
Closing the wizard without saving will not save your work, but instead, closes the entire Workflow Visualizer and you will have to start where you last saved.
.. _ug_wf_approval_nodes:
@ -417,22 +435,27 @@ Approval nodes
Choosing an **Approval** node requires user intervention in order to advance the workflow. This functions as a means to pause the workflow in between playbooks so that a user can give approval to continue on to the next playbook in the workflow, giving the user a specified amount of time to intervene, but also allows the user to continue as quickly as possible without having to wait on some other trigger.
.. image:: ../common/images/wf-node-approval-form.png
:alt: Workflow Visualizer Approval node form.
The default for the timeout is none, but you can specify the length of time before the request expires and automatically gets denied. After selecting and supplying the information for the approval node, it displays on the graphical view with a pause (|pause|) icon next to it.
.. |pause| image:: ../common/images/wf-node-approval-icon.png
:alt: Workflow node - approval icon.
.. image:: ../common/images/wf-node-approval-node.png
:alt: Workflow Visualizer showing approval node with pause icon.
The approver is anyone who can execute the workflow job template containing the approval nodes, has org admin or above privileges (for the org associated with that workflow job template), or any user who has the *Approve* permission explicitly assigned to them within that specific workflow job template.
.. image:: ../common/images/wf-node-approval-notifications.png
:alt: Workflows requesting approval from notifications
If pending approval nodes are not approved within the specified time limit (if an expiration was assigned) or they are denied, then they are marked as "timed out" or "failed", respectively, and move on to the next "on fail node" or "always node". If approved, the "on success" path is taken. If you try to POST in the API to a node that has already been approved, denied or timed out, an error message notifies you that this action is redundant, and no further steps will be taken.
Below shows the various levels of permissions allowed on approval workflows:
.. image:: ../common/images/wf-node-approval-rbac.png
:alt: Workflow nodes approval RBAC table.
.. source file located on google spreadsheet "Workflow approvals chart"
@ -444,18 +467,22 @@ Node building scenarios
You can add a sibling node by clicking the |add node| on the parent node:
.. image:: ../common/images/wf-editor-create-sibling-node.png
:alt: Workflow Visualizer showing how to create a sibling node.
You can insert another node in between nodes by hovering over the line that connects the two until the |add node| appears. Clicking on the |add node| automatically inserts the node between the two nodes.
.. image:: ../common/images/wf-editor-insert-node-template.png
:alt: Workflow Visualizer showing how to insert a node.
To add a root node to depict a split scenario, click the |start| button again:
.. image:: ../common/images/wf-editor-create-new-add-template-split.png
:alt: Workflow Visualizer showing how depict a split scnario.
At any node where you want to create a split scenario, hover over the node from which the split scenario begins and click the |add node|. This essentially adds multiple nodes from the same parent node, creating sibling nodes:
.. image:: ../common/images/wf-editor-create-siblings.png
:alt: Workflow Visualizer showing how to create sibling nodes.
.. note::
@ -467,8 +494,9 @@ If you want to undo the last inserted node, click on another node without making
Below is an example of a workflow that contains all three types of jobs that is initiated by a job template that if it fails to run, proceed to the project sync job, and regardless of whether that fails or succeeds, proceed to the inventory sync job.
.. image:: ../common/images/wf-editor-create-new-add-template-example.png
:alt: Workflow Visualizer showing a workflow job that contains a job template, a project, and an inventory source.
Remember to refer to the Key at the top of the window to identify the meaning of the symbols and colors associated with the graphical depiction.
Remember to refer to the Legend at the top of the window to identify the meaning of the symbols and colors associated with the graphical depiction.
.. note::
@ -477,6 +505,7 @@ Remember to refer to the Key at the top of the window to identify the meaning of
.. image:: ../common/images/wf-node-delete-scenario.png
:alt: Workflow Visualizer showing a workflow job with a deleted node.
The following ways you can modify your nodes:
@ -486,14 +515,22 @@ The following ways you can modify your nodes:
- To edit the edge type for an existing link (success/failure/always), click on the link. The right pane displays the current selection. Make your changes and click **Save** to apply them to the graphical view.
.. image:: ../common/images/wf-editor-wizard-edit-link.png
:alt: Workflow Visualizer showing the wizard to edit the link.
- To add a new link from one node to another, click the link |edit link| icon that appears on each node. Doing this highlights the nodes that are possible to link to. These feasible options are indicated by the dotted lines. Invalid options are indicated by grayed out boxes (nodes) that would otherwise produce an invalid link. The example below shows the **Demo Project** as a possible option for the **e2e-ec20de52-project** to link to, as indicated by the arrows:
.. image:: ../common/images/wf-node-link-scenario.png
:alt: Workflow showing linking scenerio between two nodes.
- To remove a link, click the link and click the **Unlink** button.
When linked, specify the type of run scenario you would like the link to have in the Add Link prompt.
.. image:: ../common/images/wf-editor-wizard-add-link-prompt.png
:alt: Workflow Visualizer prompt specifying the run type when adding a new link.
- To remove a link, click the link and click the **Unlink** (|delete node|) icon and click **Remove** at the prompt to confirm.
.. image:: ../common/images/wf-editor-wizard-unlink.png
:alt: Workflow Visualizer showing the wizard to remove the link.
This button only appears in the right hand panel if the target or child node has more than one parent. All nodes must be linked to at least one other node at all times so you must create a new link before removing an old one.
@ -501,6 +538,7 @@ This button only appears in the right hand panel if the target or child node has
Click the Tools icon (|tools|) to zoom, pan, or reposition the view. Alternatively, you can drag the workflow diagram to reposition it on the screen or use the scroll on your mouse to zoom.
.. |tools| image:: ../common/images/tools.png
:alt: Workflow Visualizer tools icon.
@ -515,19 +553,19 @@ Launch a workflow template by any of the following ways:
- Access the workflow templates list from the **Templates** menu on the left navigation bar or while in the workflow template Details view, scroll to the bottom to access the |launch| button from the list of templates.
.. image:: ../common/images/wf-templates-wf-template-launch.png
:alt: Templates list view with arrow pointing to the launch button of the workflow job template.
- While in the Workflow Job Template Details view of the job you want to launch, click **Launch**.
.. |launch| image:: ../common/images/launch-button.png
:alt: Workflow template launch button.
Along with any extra variables set in the workflow job template and survey, AWX automatically adds the same variables as those added for a workflow job template upon launch. Additionally, AWX automatically redirects the web browser to the Jobs Details page for this job, displaying the progress and the results.
Events related to approvals on workflows display in the Activity Stream (|activity-stream|) with detailed information about the approval requests, if any.
Events related to approvals on workflows display at the top in the Activity Stream (|activity-stream|) with detailed information about the approval requests, if any.
.. |activity-stream| image:: ../common/images/activitystream.png
.. .. image:: ../common/images/wf-activity-stream-events.png
:alt: Activity Stream icon.
Copy a Workflow Template
-------------------------------
@ -539,10 +577,12 @@ AWX allows you the ability to copy a workflow template. If you choose to copy a
2. Click the |copy| button.
.. |copy| image:: ../common/images/copy-button.png
:alt: Copy button.
A new template opens with the name of the template from which you copied and a timestamp.
.. image:: ../common/images/wf-list-view-copy-example.png
:alt: Templates list view with example copied workflow.
Select the copied template and replace the contents of the **Name** field with a new name, and provide or modify the entries in the other fields to complete this template.
@ -588,3 +628,4 @@ The following table notes the behavior (hierarchy) of variable precedence in AWX
**Variable Precedence Hierarchy (last listed wins)**
.. image:: ../common/images/Architecture-AWX_Variable_Precedence_Hierarchy-Workflows.png
:alt: AWX Variable Precedence Hierarchy for Workflows