Chapter 23. Workflow job templates
Chapter 23. Workflow job templates A workflow job template links together a sequence of disparate resources that tracks the full set of jobs that were part of the release process as a single unit. These resources include the following: Job templates Workflow job templates Project syncs Inventory source syncs The Templates list view shows 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 have run by using that template. You can click the arrow to each entry to expand and 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 , edit , and copy a workflow job template. Only workflow templates have the workflow visualizer icon as a shortcut for accessing the workflow editor. Note Workflow templates can be used as building blocks for another workflow template. You can enable Prompt on Launch by setting up several settings in a workflow template, which you can edit at the workflow job template level. These do not affect the values assigned at the individual workflow template level. For further instructions, see the Workflow Visualizer section. 23.1. Creating a workflow template To create a new workflow job template, complete the following steps: Important If you set a limit to a workflow template, it is not passed down to the job template unless you check Prompt on launch for the limit. This can lead to playbook failures if the limit is mandatory for the playbook that you are running. Procedure On the Templates list view, select Add workflow template from the Add list. Enter the appropriate details in the following fields: Note If a field has the Prompt on launch checkbox selected, either launching the workflow template, or using the workflow template within another workflow template, you are prompted for the value for that field. Most prompted values override any values set in the job template. Exceptions are noted in the following table. Field Options Prompt on Launch Name Enter a name for the job. N/A Description Enter an arbitrary description as appropriate (optional). N/A Organization Choose the organization to use with this template from the organizations available to the logged in user. N/A Inventory Optionally, select the inventory to use with this template from the inventories available to the logged in user. Yes Limit A host pattern to further constrain the list of hosts managed or affected by the playbook. You can separate many patterns by colons (:). As with core Ansible: a:b means "in group a or b" a:b:&c means "in a or b but must be in c" a:!b means "in a, and definitely not in b" For more information see, Patterns: targeting hosts and groups in the Ansible documentation. Yes If selected, even if a default value is supplied, you are prompted upon launch to select a limit. Source control branch Select a branch for the workflow. This branch is applied to all workflow job template nodes that prompt for a branch. Yes Labels Optionally, supply labels that describe this workflow job template, such as dev or test . Use labels to group and filter workflow job templates and completed jobs in the display. Labels are created when they are added to the workflow template. Labels are associated to a single Organization using the Project that is provided in the workflow template. Members of the Organization can create labels on a workflow template if they have edit permissions (such as the admin role). Once you save the job template, the labels appear in the workflow job templates Details view. Labels are only applied to the workflow templates not the job template nodes that are used in the workflow. Select beside a label to remove it. When a label is removed, it is no longer associated with that particular Job or Job Template, but it remains associated with any other jobs that reference it. Yes If selected, even if a default value is supplied, you are prompted when launching to supply additional labels, if needed. - You cannot delete existing labels, selecting only removes the newly added labels, not existing default labels. Variables Pass extra command line variables to the playbook. This is the "-e" or "-extra-vars" command line parameter for ansible-playbook that is documented in the Ansible documentation at Controlling how Ansible behaves: precedence rules . - Provide key or value pairs by using either YAML or JSON. These variables have a maximum value of precedence and overrides other variables specified elsewhere. The following is an example value: git_branch: production release_version: 1.5 Yes If you want to be able to specify extra_vars on a schedule, you must select Prompt on launch for Variables on the workflow job template, or enable a survey on the job template. Those answered survey questions become extra_vars . For more information about extra variables, see Extra Variables . Job tags Type and select the Create drop-down to specify which parts of the playbook should run. For more information and examples see Tags in the Ansible documentation. Yes Skip Tags Type and select the Create drop-down to specify certain tasks or parts of the playbook to skip. For more information and examples see Tags in the Ansible documentation. Yes Specify the following Options for launching this template, if necessary: Check Enable Webhooks to turn on the ability to interface with a predefined SCM system web service that is used to launch a workflow job template. GitHub and GitLab are the supported SCM systems. If you enable webhooks, other fields display, prompting for additional information: Webhook Service : Select which service to listen for webhooks from. Webhook Credential : Optionally, provide a GitHub or GitLab personal access token (PAT) as a credential to use to send status updates back to the webhook service. For more information, see Credential Types to create one. When you click Save , additional fields populate and the workflow visualizer automatically opens. Webhook URL : Automatically populated with the URL for the webhook service to POST requests to. Webhook Key : Generated shared secret to be used by the webhook service to sign payloads sent to automation controller. You must configure this in the settings on the webhook service so that webhooks from this service are accepted in automation controller. For additional information about setting up webhooks, see Working with Webhooks . Check Enable Concurrent Jobs to allow simultaneous runs of this workflow. For more information, see Automation controller capacity determination and job impact . When you have completed configuring the workflow template, click Save . Saving the template exits the workflow template page and the workflow visualizer opens to allow you to build a workflow. For more information, see the Workflow visualizer section. Otherwise, select one of these methods: Close the workflow visualizer to return to the Details tab of the newly saved template. There you can complete the following tasks: Review, edit, add permissions, notifications, schedules, and surveys View completed jobs Build a workflow template Click Launch to start the workflow. Note Save the template before launching, or Launch remains disabled. The Notifications tab is only present after you save the template. 23.2. Work with permissions Click the Access tab to review, grand, edit, and remove associated permissions for users as well as team members. Click Add to create new permissions for this workflow template by following the prompts to assign them accordingly. 23.3. Work with notifications For information on working with notifications in workflow job templates, see Work with notifications . 23.4. View completed workflow jobs The Jobs tab provides the list of job templates that have run. Click the expand icon to each job to view the details of each job. From this view, you can click the job ID, name of the workflow job and see its graphical representation. The following example shows the job details of a workflow job: The nodes are marked with labels to help you identify them. For more information, see the legend in the Workflow visualizer section. 23.5. Scheduling a workflow job template Select the Schedules tab to access the schedules for a particular workflow job template.. For more information on scheduling a workflow job template run, see the Scheduling job templates section. If a workflow job template used in a nested workflow has a survey, or the Prompt on Launch is selected for the inventory option, the PROMPT option displays to the SAVE and CANCEL options on the schedule form. Click PROMPT to show an optional INVENTORY step where you can provide or remove an inventory or skip this step without any changes. 23.6. Surveys in workflow job templates Workflows containing job types of Run or Check provide a way to set up surveys in the workflow job template creation or editing screens. For more information on job surveys, including how to create a survey and optional survey questions in workflow job templates, see the Surveys in job templates section. 23.7. Workflow visualizer The Workflow Visualizer provides a graphical way of linking together job templates, workflow templates, project syncs, and inventory syncs to build a workflow template. Before you build a workflow template, see the Workflows section for considerations associated with various scenarios on parent, child, and sibling nodes. 23.7.1. Building a workflow You can set up any combination of two or more of the following node types to build a workflow: Template (Job Template or Workflow Job Template) Project Sync Inventory Sync Approval Each node is represented by a rectangle while the relationships and their associated edge types are represented by a line (or link) that connects them. Procedure To launch the workflow visualizer, use one of these methods: From the navigation panel, select Resources Templates . Select a workflow template, in the Details tab click Edit . Select the Visualizer tab. From the Templates list view, click the icon. Click Start to display a list of nodes to add to your workflow. From the Node Type list, select the type of node that you want to add: If you select an Approval node, see Approval nodes for more information. Selecting a node provides the available valid options associated with it. Note If you select a job template that does not have a default inventory when populating a workflow graph, the inventory of the parent workflow is used. Though a credential is not required in a job template, you cannot choose a job template for your workflow if it has a credential that requires a password, unless the credential is replaced by a prompted credential. When you select a node type, the workflow begins to build, and you must specify the type of action to be taken for the selected node. This action is also referred to as edge type. If the node is a root node, the edge type defaults to Always and is non-editable. For subsequent nodes, you can select one of the following scenarios (edge type) to apply to each: Always : Continue to execute regardless of success or failure. On Success : After successful completion, execute the template. On Failure : After failure, execute a different template. Select the behavior of the node if it is a convergent node from the Convergence field: Any is the default behavior, allowing any of the nodes to complete as specified, before triggering the converging node. As long as the status of one parent meets one of those run conditions, an any child node will run. An any node requires all nodes to complete, but only one node must complete with the expected outcome. Choose All to ensure that all nodes complete as specified, before converging and triggering the node. The purpose of all * nodes is to make sure that every parent meets its expected outcome in order to run the child node. The workflow checks to make sure every parent behaves as expected in order to run the child node. Otherwise, it will not run the child node. If selected, the node is labeled as ALL in the graphical view: Note If a node is a root node, or a node that does not have any nodes converging into it, setting the Convergence rule does not apply, as its behavior is dictated by the action that triggers it. If a job template used in the workflow has Prompt on Launch selected for any of its parameters, a PROMPT option appears, enabling you to change those values at the node level. Use the wizard to change the values in each of the tabs and click Confirm in the Preview tab. 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 overrides any inventory that is supplied here. Note For workflow job templates with required fields that prompt details, but do not have a default, you must provide those values when creating a node before the Select option is enabled. The following two cases disable the SELECT option until a value is provided by the PROMPT option: When you select the Prompt on Launch checkbox in a workflow job template, but do not provide a default. 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, because everything required to launch the node must be provided when the node is created. If you are prompted for credentials in a workflow job template, it is not possible to select a credential that requires a password in automation controller. You must also click SELECT when the prompt wizard closes, to apply the changes at that node. Otherwise, any changes you make revert back to the values set in the job template. When the node is created, it is labeled with its job type. A template that is associated with each workflow node runs based on the selected run scenario as it proceeds. Click the compass ( ) icon to display the legend for each run scenario and their job types. Hover over a node to add another node, view info about the node, edit the node details, edit an existing link, or delete the selected node: When you have added or edited a node, click SELECT to save any modifications and render it on the graphical view. For possible ways to build your workflow, see Building nodes scenarios . When you have built your workflow job template, click Save to save your entire workflow template and return to the new workflow job template details page. Important Clicking Close does not save your work, but instead, it closes the entire Workflow Visualizer so that you have to start again. 23.7.2. Approval nodes Choosing an Approval node requires your intervention in order to advance the workflow. This functions as a means to pause the workflow in between playbooks so that you can give approval to continue on to the playbook in the workflow. This gives the user a specified amount of time to intervene, but also enables you to continue as quickly as possible without having to wait on another trigger. The default for the timeout is none, but you can specify the length of time before the request expires and is automatically denied. After you select and supply the information for the approval node, it displays on the graphical view with a pause icon beside it. The approver is anyone who meets the following criteria: A user that can execute the workflow job template containing the approval nodes. A user who has organization administrator or above privileges (for the organization associated with that workflow job template). A user who has the Approve permission explicitly assigned to them within that specific workflow job template. 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", and move on to the "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 are taken. The following table shows the various levels of permissions allowed on approval workflows: 23.7.3. Building nodes scenarios Learn how to manage nodes in the following scenarios. Procedure Click the ( ) icon on the parent node to add a sibling node: Hover over the line that connects two nodes and click the plus ( ), to insert another node in between nodes. Clicking the plus ( ) icon automatically inserts the node between the two nodes: Click START again, to add a root node to depict a split scenario: At any node where you want to create a split scenario, hover over the node from which the split scenario begins and click the plus ( ) icon. This adds multiple nodes from the same parent node, creating sibling nodes: Note When adding a new node, the PROMPT option also applies to workflow templates. Workflow templates prompt for inventory and surveys. You can undo the last inserted node by using one of these methods: Click on another node without making a selection. Click Cancel . The following example workflow contains all three types of jobs initiated by a job template. If it fails to run, you must protect the sync job. Regardless of whether it fails or succeeds, proceed to the inventory sync job: Refer to the key by clicking the compass ( ) icon to identify the meaning of the symbols and colors associated with the graphical depiction. Note If you remove a node that has a follow-on node attached to it in a workflow with a set of sibling nodes that has varying edge types, the attached node automatically joins the set of sibling nodes and retains its edge type: 23.7.4. Editing a node Procedure Edit a node by using one of these methods: If you want to edit a node, click on the node you want to edit. The pane displays the current selections. Make your changes and click Select to apply them to the graphical view. To edit the edge type for an existing link, ( success , failure , always ), click the link. The pane displays the current selection. Make your changes and click Save to apply them to the graphical view. Click the link ( ) icon that appears on each node, to add a new link from one node to another. Doing this highlights the nodes that are possible to link to. These options are indicated by the dotted lines. Invalid options are indicated by disabled boxes (nodes) that would otherwise produce an invalid link. The following example shows the Demo Project as a possible option for the e2e-ec20de52-project to link to, indicated by the arrows: To remove a link, click the link and click UNLINK . This option only appears in the pane 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. Edit the view of the workflow diagram by using one of these methods: Click the settings icon to zoom, pan, or reposition the view. Drag the workflow diagram to reposition it on the screen or use the scroll on your mouse to zoom. 23.8. Launching a workflow job template Procedure Launch a workflow job template by using one of these methods: From the navigation panel, select Resources Templates and click Launch to the job template: Click Launch in the Details tab of the workflow job template that you want to launch. Variables added for a workflow job template are automatically added in automation controller when launching, along with any extra variables set in the workflow job template and survey. Events related to approvals on workflows are displayed in the activity stream ( ) with detailed information about the approval requests, if any. 23.9. Copying a workflow job template With automation controller you can copy a workflow job template. When you copy a workflow job template, it does not copy any associated schedule, notifications, or permissions. Schedules and notifications must be recreated by the user or system administrator creating the copy of the workflow template. The user copying the workflow template is granted the administrator permission, but no permissions are assigned (copied) to the workflow template. Procedure Open the workflow job template that you want to copy by using one of these methods: From the navigation panel, select Resources Templates . In the workflow job template Details view, scroll down to access it from a list of templates. Click the copy ( ) icon. A new template opens with the name of the template from which you copied and a timestamp: 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. Click Save . Note If a resource has a related resource that you do not have the right level of permission to, you cannot copy the resource. For example, in the case where a project uses a credential that a current user only has Read access. However, for a workflow job template, if any of its nodes use an unauthorized job template, inventory, or credential, the workflow template can still be copied. But in the copied workflow job template, the corresponding fields in the workflow template node are absent. 23.10. Workflow job template extra variables For more information see the Extra variables section.