tower-cli/docs/source/cli_ref/usage/WORKFLOWS.rst

.. _cli_ref:

Workflow Management
===================

These docs show how to populate an example workflow in Tower and how to
automate the creation or copying of workflows.

Normal CRUD
-----------

Workflows and workflow nodes can be managed as normal tower-cli
resources.

Workflow Creation
~~~~~~~~~~~~~~~~~

Create an empty workflow:

::

    tower-cli workflow create --name="workflow1" --organization="Default" --description="example description"

Check the existing workflows with the standard list or get commands.

::

    tower-cli workflow list --description-on

Node Creation
~~~~~~~~~~~~~

Create nodes inside the workflow These all become "root" nodes and will
spawn jobs on workflow launch without any dependencies on other nodes.
These commands create 2 root nodes.

::

    tower-cli node create -W workflow1 --job-template="Hello World"
    tower-cli node create -W workflow1 --job-template="Hello World"

List the nodes inside of the workflow

::

    tower-cli node list -W workflow1

Node Association
~~~~~~~~~~~~~~~~

From the list command, you can find the ids of nodes you want to link
``associate_success_node`` will cause the 2nd node to run on success of
the first node. The following command causes node 2 to run on the event
of successful completion of node 1.

::

    tower-cli node associate_success_node 1 2

This operation is only possible when node 2 is a root node. See the
Tower documentation for the limitations on the types of node connections
allowed.

Auto-creation of the success node, only knowing the parent node id:

::

    tower-cli node associate_success_node 8 --job-template="Hello world"

Corresponding disassociate commands are also available. Disassociating a
node from another node will make it a root node.

Node Network Bulk Management
----------------------------

To print out a YAML representation of the nodes of a workflow, you can
use the following command. JSON format is also allowed.

::

    tower-cli workflow schema workflow1

Here, "workflow1" is the name of the workflow.

Creating/updating a Schema Definition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To bulk-create or buld-update a workflow node network, use the workflow
schema command. The schema is JSON or YAML content, and can be passed in
the CLI argument, or pointed to a file. The schema is passed as a second
positional argument, where the first argument references the workflow.

::

    tower-cli workflow schema workflow2 @schema.yml

The schema can be provided without using a file:

::

    tower-cli workflow schema workflow2 '[{"job_template": "Hello world"}]'

The Schema definition defines the hierarchy structure that connects the
nodes. Names, as well as other valid parameters for node creation, are
acceptable inside of the node's entry inside the schema definition.

Links must be declared as a list under a key that starts with "success",
"failure", or "always". The following is an example of a valid schema
definition.

Example ``schema.yml`` file:

.. code:: yaml

    - job_template: Hello world
      failure:
      - inventory_source: AWS servers (AWS servers - 42)
      success:
      - project: Ansible Examples
        always:
        - job_template: Echo variable
          success:
          - job_template: Scan localhost

This style may be useful to apply in a script to create a workflow
network with a tower-cli command after the constituent resources like
the job templates and projects were created by preceding tower-cli
commands.

Workflows Inside Workflows
~~~~~~~~~~~~~~~~~~~~~~~~~~

It is possible to have a workflow embedded inside of the schema of another
workflow. To do this, use the key "workflow".

.. code:: yaml

    - workflow: Another workflow

Differences with Machine Formatted Schemas
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After writing a workflow schema, you may notice differences in how
tower-cli subsequently echos the schema definition back to you. The
following is what tower-cli might return after writing the above
example.

.. code:: yaml

    - failure_nodes:
      - inventory_source: 42
      job_template: 45
      success_nodes:
      - always_nodes:
        - job_template: 55
          success_nodes:
          - job_template: 44
        project: 40

Note that the root node data starts with "failure\_nodes", instead of
the name of the job template. This will not impact functionality, and
manually changing the order will not impact functionality either.

Although this format is harder to read, it does the same thing as the
previous schema. The ability to both echo and create schemas can be used
to copy the contents of one workflow to another.

As an example, consider 2 workflows. The first has a name "workflow1",
and has its node network populated. The second is named "workflow2" and
is empty. The following commands will copy the structure from the first
to the second.

.. code:: bash

    tower-cli workflow schema workflow1 > schema.yml
    tower-cli workflow schema workflow2 @schema.yml

Idempotence
~~~~~~~~~~~

The workflow schema feature populates the workflow node network based on
the hierarchy structure. Before creating each node, it attempts to find
an existing node with the specified properties in that location in the
tree, and will not create a new node if it exists. Also, if an existing
node has no correspondence in the schema, the entire sub-tree based on
that node will be deleted.

Thus, after running the schema command, the resulting workflow topology
will always be exactly the same as what is specified in the given schema
file. To continue with the previous example, subsequent invocations of:

.. code:: bash

    tower-cli workflow schema workflow2 @schema.yml
    tower-cli workflow schema workflow2 @schema.yml

should not change the network of workflow2, since ``schema.yml`` file
itself remains unchanged. However

.. code:: bash

    tower-cli workflow schema workflow2 @new_schema.yml

will modify topology of workflow2 to exactly the same as what is
specified in ``new_schema.yml``.

Launching Workflow Jobs
-----------------------

Use the workflow\_job resource to launch workflow jobs. This supports
the use of extra\_vars, which can contain answers to survey questions.
The ``--monitor`` and ``--wait`` flag are available to poll the server
until workflow job reaches a completed status. The ``--monitor`` option
will print rolling updates of the jobs that ran as part of the workflow.
Here is an example of using those features:

::

    tower-cli workflow_job launch -W "echo Hello World" -e a=1 --monitor