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.