Chapter 23. Workflow job templates

download PDF

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 next 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 Launch , edit Edit , and copy Copy a workflow job template.

Only workflow templates have the workflow visualizer Workflow visualizer icon as a shortcut for accessing the workflow editor.

Workflow templates home

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:


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.


  1. On the Templates list view, select Add workflow template from the Add list.

    Create workflow template
  2. Enter the appropriate details in the following fields:


    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.

    FieldOptionsPrompt on Launch


    Enter a name for the job.



    Enter an arbitrary description as appropriate (optional).



    Choose the organization to use with this template from the organizations available to the logged in user.



    Optionally, select the inventory to use with this template from the inventories available to the logged in user.



    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.


    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.



    • 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 Disassociate 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.


    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 Disassociate only removes the newly added labels, not existing default labels.


    • 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


    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.


    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.


  3. 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.

  4. 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.


    Save the template before launching, or Launch remains disabled. The Notifications tab is only present after you save the template.

Template saved

23.2. Work with permissions

Click the Access tab to review, grand, edit, and remove associated permissions for users as well as team members.

Completed permissions

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 Expand icon next 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:

Workflow template job ID

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 next 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.


  1. To launch the workflow visualizer, use one of these methods:

    1. From the navigation panel, select Resources Templates.

      1. Select a workflow template, in the Details tab click Edit.
      2. Select the Visualizer tab.
    2. From the Templates list view, click the Visualizer icon.

      Launch visualizer
  2. Click Start to display a list of nodes to add to your workflow.

    Add Node workflow job template
  3. From the Node Type list, select the type of node that you want to add:

    Node type
    • If you select an Approval node, see Approval nodes for more information.

      Selecting a node provides the available valid options associated with it.


      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.

  4. 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.
  5. 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 next template.
    • On Failure: After failure, execute a different template.
  6. 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 next 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 next 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:

      Convergent node all


      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.

  7. 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.

    Prompt option

    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.

    Prompt button inventory

    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:

    1. When you select the Prompt on Launch checkbox in a workflow job template, but do not provide a default.
    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, 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 ( Compass ) icon to display the legend for each run scenario and their job types.

    Worfklow dropdown list
  8. 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:

    Node options
  9. 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.
  10. 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.

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 next 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.

Approval node

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.
Node approval 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", 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 are taken.

The following table shows the various levels of permissions allowed on approval workflows:

Node approval rbac

23.7.3. Building nodes scenarios

Learn how to manage nodes in the following scenarios.


  • Click the ( Plus icon ) icon on the parent node to add a sibling node:
Create sibling node
  • Hover over the line that connects two nodes and click the plus ( Plus icon ), to insert another node in between nodes. Clicking the plus ( Plus icon ) icon automatically inserts the node between the two nodes:
Insert node template
  • Click START again, to add a root node to depict a split scenario:
Node 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 ( Plus icon ) icon. This adds multiple nodes from the same parent node, creating sibling nodes:
Node create siblings

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:

Workflow template example

Refer to the key by clicking the compass ( Compass ) icon to identify the meaning of the symbols and colors associated with the graphical depiction.


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:

Node delete scenario

23.7.4. Editing a node


  • 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 ( Link icon ) 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:

      Node link scenario
    • 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


  • Launch a workflow job template by using one of these methods:

    • From the navigation panel, select Resources Templates and click Launch next to the job template:

      Launch workflow 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 ( 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.


  1. 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 ( Copy icon ) icon.

        A new template opens with the name of the template from which you copied and a timestamp:

        Workflow template copy list view
  2. 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.
  3. Click Save.

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.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.