Getting Started

Authoring

Like any StackStorm action, an Orquesta workflow requires an action metadata file in /opt/stackstorm/packs/<mypack>/actions. The entry point specified in the action metadata file is the path relative to /opt/stackstorm/packs/<mypack>/actions for the workflow definition.

Let’s start with a very basic Orquesta workflow named examples.orquesta-sequential for the examples pack. The workflow definition for this example is provided below. This workflow is a very simple example that runs a few echoes, pieces together the output, and returns a response. A task can reference any registered StackStorm action directly. In this example, the task calls core.echo, an action in StackStorm that just echoes back the message, like the shell echo command. The core.echo action is already installed by default with StackStorm. Let’s save this workflow definition as /opt/stackstorm/packs/examples/actions/workflows/orquesta-sequential.yaml on the StackStorm server.

version: 1.0

description: A basic sequential workflow.

input:
  - name

vars:
  - greeting: null

output:
  - greeting: <% ctx().greeting %>

tasks:
  task1:
    action: core.echo message=<% ctx().name %>
    next:
      - when: <% succeeded() %>
        publish: greeting=<% result().stdout %>
        do: task2
  task2:
    action: core.echo
    input:
      message: "All your base are belong to us!"
    next:
      - when: <% succeeded() %>
        publish:
          - greeting: <% ctx("greeting") %>, <% result().stdout %>
        do:
          - task3
  task3:
    action: core.echo message=<% ctx('greeting') %>
    next:
      - when: <% succeeded() %>
        publish: greeting=<% result().stdout %>

As for the corresponding StackStorm action metadata file for the example above. The StackStorm pack for this workflow action is named examples. The StackStorm action runner is orquesta. The entry point for the StackStorm action is the relative path to the YAML file of the workflow definition. Let’s save this metadata as /opt/stackstorm/packs/examples/actions/orquesta-sequential.yaml:

---
name: orquesta-sequential
pack: examples
description: A basic sequential workflow.
runner_type: orquesta
entry_point: workflows/orquesta-sequential.yaml
enabled: true
parameters:
  name:
    required: true
    type: string
    default: Lakshmi

The files used in this example are also located under /usr/share/doc/st2/examples if StackStorm is already installed (see also deploy examples).

To create this action in StackStorm, run the command st2 action create /opt/stackstorm/packs/examples/actions/orquesta-sequential.yaml. This will register the workflow as examples.orquesta-sequential in StackStorm. The following is what the output should look like.

$ st2 action create /opt/stackstorm/packs/examples/actions/orquesta-sequential.yaml
+---------------+------------------------------------+
| Property      | Value                              |
+---------------+------------------------------------+
| id            | 5d3a08a00a08a41a995221a0           |
| name          | orquesta-sequential                |
| pack          | examples                           |
| description   | A basic sequential workflow.       |
| enabled       | True                               |
| entry_point   | workflows/orquesta-sequential.yaml |
| metadata_file |                                    |
| notify        |                                    |
| output_schema |                                    |
| parameters    | {                                  |
|               |     "name": {                      |
|               |         "default": "Lakshmi",      |
|               |         "required": true,          |
|               |         "type": "string"           |
|               |     }                              |
|               | }                                  |
| ref           | examples.orquesta-sequential       |
| runner_type   | orquesta                           |
| tags          |                                    |
| uid           | action:default:orquesta-sequential |
+---------------+------------------------------------+

Execution

Before we run the example, let’s run the help command st2 run examples.orquesta-sequential -h to see what input parameters are required. The following is what the help command returns. The workflow requires a value for the input parameter named name. There is an optional parameter named notify which we can ignore for now.

$ st2 run examples.orquesta-sequential -h

A basic sequential workflow.

Required Parameters:
    name
        Type: string
        Default: Lakshmi

Optional Parameters:
    notify
        List of tasks to trigger notifications for.
        Type: array
        Default: []

To execute the workflow, run the command st2 run examples.orquesta-sequential name=Earthling -a where the -a option tells the command to return and not wait for the workflow to complete.

$ st2 run examples.orquesta-sequential name=Earthling -a
To get the results, execute:
 st2 execution get 5d3a0a890a08a41a995221a3

To view output in real-time, execute:
 st2 execution tail 5d3a0a890a08a41a995221a3

If the workflow completed successfully, both the workflow examples.orquesta-sequential and the sequence of core.echo should be succeeded under the StackStorm action execution list. By default, st2 execution list only returns top level executions and tasks are not displayed.

$ st2 execution list
+--------------------------+-----------------+--------------+------------------------+-----------------+---------------+
| id                       | action.ref      | context.user | status                 | start_timestamp | end_timestamp |
+--------------------------+-----------------+--------------+------------------------+-----------------+---------------+
| 5d3a0a890a08a41a995221a3 | examples        | stanley      | succeeded (4s elapsed) | Thu, 25 Jul     | Thu, 25 Jul   |
|                          | .orquesta-      |              |                        | 2019 20:01:13   | 2019 20:01:17 |
|                          | sequential      |              |                        | UTC             | UTC           |
+--------------------------+-----------------+--------------+------------------------+-----------------+---------------+

Running the command st2 execution get <execution-id> returns more details about the workflow execution such as the action executions related to the tasks and the output of the workflow.

$ st2 execution get 5d3a0a890a08a41a995221a3
id: 5d3a0a890a08a41a995221a3
action.ref: examples.orquesta-sequential
parameters:
  name: Earthling
status: succeeded (4s elapsed)
start_timestamp: Thu, 25 Jul 2019 20:01:13 UTC
end_timestamp: Thu, 25 Jul 2019 20:01:17 UTC
result:
  output:
    greeting: Earthling, All your base are belong to us!
+--------------------------+------------------------+-------+-----------+-----------------+
| id                       | status                 | task  | action    | start_timestamp |
+--------------------------+------------------------+-------+-----------+-----------------+
| 5d3a0a890a08a41a426722d5 | succeeded (1s elapsed) | task1 | core.echo | Thu, 25 Jul     |
|                          |                        |       |           | 2019 20:01:13   |
|                          |                        |       |           | UTC             |
| 5d3a0a8a0a08a41a426722d8 | succeeded (1s elapsed) | task2 | core.echo | Thu, 25 Jul     |
|                          |                        |       |           | 2019 20:01:14   |
|                          |                        |       |           | UTC             |
| 5d3a0a8b0a08a41a426722db | succeeded (1s elapsed) | task3 | core.echo | Thu, 25 Jul     |
|                          |                        |       |           | 2019 20:01:15   |
|                          |                        |       |           | UTC             |
+--------------------------+------------------------+-------+-----------+-----------------+

Inspection

The workflow definition is inspected on execution. In a single pass, Orquesta will inspect the workflow definition for errors in syntax, YAQL and Jinja expressions, and variables in the context. The following is an execution with inspection failure. Note that the errors are separated by categories. Each entry returns the error message, the path to where the error is located in the workflow definition, and other information specific to the error type.

$ st2 run examples.orquesta-fail-inspection
.
id: 5b3153d08006e627f71c2d39
action.ref: examples.orquesta-fail-inspection
parameters: None
status: failed
start_timestamp: Mon, 25 Jun 2018 20:42:55 UTC
end_timestamp: Mon, 25 Jun 2018 20:42:56 UTC
result:
  errors:
    context:
    - expression: <% ctx().foobar %>
      message: Variable "foobar" is referenced before assignment.
      schema_path: properties.tasks.patternProperties.^\w+$.properties.input
      spec_path: tasks.task1.input
      type: yaql
    expressions:
    - expression: <% <% succeeded() %>
      message: 'Parse error: unexpected ''<'' at position 0 of expression ''<% succeeded()'''
      schema_path: properties.tasks.patternProperties.^\w+$.properties.next.items.properties.when
      spec_path: tasks.task2.next[0].when
      type: yaql
    syntax:
    - message: '[{''cmd'': ''echo <% ctx().macro %>''}] is not of type ''object'''
      schema_path: properties.tasks.patternProperties.^\w+$.properties.input.type
      spec_path: tasks.task2.input
  output: null

More Examples

There are more workflow examples under /usr/share/doc/st2/examples, including workflows that demonstrate branches, joins, decision tree, error handling, rollback/retry, and others.

Additional Tools and Resources

Note

The following tools and resources are not owned by StackStorm. Please use at your own risk.