Version: v1.0.0

Workflow Jobs and Steps

A Workflow Job is a set of actions for a specific task within a set of several other Jobs to execute a larger workflow or process. Each Job generates a process that is composed of a series of steps or 'Steps', and the processes are executed on the same machine/runner. Jobs are executed in parallel unless there is a dependency between them. Each Job can contain one or more Steps.

Each Step that makes up the Job can be of a different type. The Step type determines whether it executes an Action, another Workflow, or applies a Plugin.

In the Workflow file (workflow.yaml), the 'spec:' field receives all the Workflow-specific parameters such as the 'jobs' and 'steps' objects, respectively:

Workflow file 'workflow.yaml'
schema-version: v1
kind: workflow
metadata:
  name: my-first-workflow
  display-name: my-first-workflow
  description: First creation of a Workflow
  version: 0.0.1
spec:
  type: reusable
  label: Workflow Title
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which runs an action and applies a plugin
      steps:
        - id: step_id_1
          label: Step which runs action
          name: stackspot/hello-world@1.0.0
          type: action
          inputs:
            const_input: "This is an example of fixed input"
        - id: step_id_2
          label: Step which applies plugin
          name: stackspot/plugin-basic@1.0.0
          type: plugin
          inputs:
            const_input: "This is an example of fixed input"

    - id: job_id_2
      label: Job which runs another workflow
      depends-on:
        - job_id_1
      steps:
        - id: step_id_1
          name: stackspot/workflow@1.0.0
          type: workflow
          inputs:
            const_input: "This is an example of fixed input"

Workflow Field	Description
`spec.jobs`	Groupings of tasks that need to be executed in the Workflow.
`spec.jobs[i].id`	Job identifier for reference in the Workflow, must follow snake_case format.
`spec.jobs[i].label`	Text displayed to the user when the Job is running.
`spec.jobs[i].depends-on`	List of other Jobs that the current Job depends on. Jobs with resolved dependencies run in parallel.
`spec.jobs[i].when`	Condition for the Job to run, defined by a Jinja expression that must return “true” (case insensitive).
`spec.jobs[i].steps`	List of steps to be executed in the Jobs.
`spec.jobs[i].steps[i].type`	Step type: “action”, “plugin”, “workflow”, "run" and “suspend”.
`spec.jobs[i].steps[i].workdir`	Directory where the Step will be executed. Optional attribute.
`spec.jobs[i].steps[i].id`	Step id for reference within the Workflow, must follow snake_case format.
`spec.jobs[i].steps[i].label`	Text displayed in the Portal when the Step is shown.
`spec.jobs[i].steps[i].when`	Condition for Step execution, defined by a Jinja expression.
`spec.jobs[i].steps[i].inputs`	Mapping of input values to be passed to the Action/Plugin/Workflow.
`spec.jobs[i].steps[i].name`	Indicates which Action/Plugin/Workflow will be executed/applied.
`spec.jobs[i].steps[i].generated-connections`	Map of connections generated by the Plugin. The key is the connection alias and the value is the name provided by the user.

Creating Dependency Between Workflow Jobs

Workflow Jobs are executed in parallel unless they have dependencies. If there are dependencies, they must be resolved before execution.

To create a dependency between Workflow Jobs, use the depends-on parameter. In it, you define as a list the other Jobs that the current Job depends on.

depends-on: List of other Jobs that the current Job depends on. Available only for Jobs.

Workflow Job with dependency on another Job.
schema-version: v1
kind: workflow
metadata:
  name: my-first-workflow
  display-name: my-first-workflow
  description: First creation of a Workflow
  version: 0.0.1
spec:
  type: reusable
  label: Workflow Title
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  Jobs:
    - id: optional
      label: Optional job
      depends-on:
        - some_job_id
      when: "{{ boolean_input }}"

Workflow Dependencies Using the `targets` Parameter

The use of the targets option follows these rules:

Workflow with the infra target must have at least one Plugin of type infra or another Workflow with the infra target. If it does not have a target, check the Plugins and Workflows in the Stack of the dependent Workflow.
Workflow with the app target must have at least one Plugin of type app or a Workflow with the app target. If it does not have a target, check the Plugins and Workflows in the Stack of the dependent Workflow.
Workflows of type reusable can only depend on other Workflows of type reusable.
Whenever a Workflow or Workflows within it have the targets parameter with type app or infra defined, the Workflow's Plugins must depend on a Plugin of the target type.

schema-version: v1
kind: workflow
metadata:
  name: my-create-app-workflow
  display-name: my-create-app-workflow
  description: Creation of an Application
  version: 2.0.0
spec:
  type: reusable
  label: Workflow Title
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which runs an action and applies a plugin
      steps:
        - id: step_id_1
          label: Step which runs action
          name: stackspot/hello-world@1.0.0
          type: action
          inputs:
            const_input: "This is an example of fixed input"
        - id: step_id_2
          label: Step which applies plugin
          name: stackspot/plugin-basic@1.0.0
          type: plugin
          inputs:
            const_input: "This is an example of fixed input"  

Workflow Steps

`plugin` Step

A Step of type plugin executes the application of Plugins by the Job in your Workflow. This Step allows you to define all the values that should be obtained by the Workflow and used during the application of the Plugins.

Example:

schema-version: v1
kind: workflow
metadata:
  name: my-create-app-workflow
  display-name: my-create-app-workflow
  description: Creation of an Application
  version: 2.0.0
spec:
  type: reusable
  label: Workflow Title
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which applies plugin
      steps:
        - type: plugin
          name: studio-name/optional_plugin@1
          id: apply_optional_plugin
          label: Apply optional plugin
          when: "{{ boolean_input }}"
          inputs:
            some_plugin_input: "fixed_value"
            other_plugin_input: "{{ text_input | lower }}"
            input_from_other_job: "{{ outputs.some_job.some_action_execution.some_action_output }}"

type: Step type.
name: Name of the Plugin to be applied by the Step. Use the format: studio-name/plugin-name@1.0.0(semantic version).

Warning!

The name field always uses the Plugin Studio Qualifier. This allows it to be applied inside or outside a Workspace. Learn more about the Plugin Studio Qualifier.

id: Step identifier.
label: Name displayed on the Activities screen in the Workflow log.
when: (Optional) Parameter to use a boolean value as a condition for executing the Job or Step.
inputs: Filling in the inputs for the Plugins defined in the Workflow. The syntax to define them is:
- input_name: "input_value"

Example:

inputs:
  some_plugin_input: "fixed_value"
  other_plugin_input: "{{ text_input | lower }}"
  input_from_other_job: "{{ outputs.some_job.some_action_execution.some_action_output }}"

`action` Step

A Step of type action executes an Action in a Job of your Workflow. This Step allows you to define all the values that must be obtained by the Workflow and used during the Action execution.

Example:

schema-version: v1
kind: workflow
metadata:
  name: my-create-app-workflow
  display-name: my-create-app-workflow
  description: Creation of an Application
  version: 2.0.0
spec:
  type: reusable
  label: Workflow Title
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which runs an action and applies a plugin
      steps:
        - id: action_example
          label: Example of step run action
          name: studio-name/action-name@1.0.0
          type: action
          inputs:
            input_1: "This is an example of fixed input"

id: Step identifier.
label: Name displayed on the Activities screen in the Workflow log.
name: Name of the Action that the Step will execute. Use the format: studio-name/action-name@1.0.0(semantic version).
type: Step type.
inputs: Filling in the inputs for the Action defined in the Workflow. The syntax to define them is:
- input_name: "input_value".

`suspend` Step

A Step of type suspend pauses the execution of the Workflow until someone approves its continuation. Whenever the execution of a Workflow is paused by a suspend Step, the person responsible for the Account or Workspace in your Organization must approve the continuation of the Workflow execution.

Another way to resume the execution of a suspended Workflow is by running the stk resume workflow command in local executions or in pre-configured pipeline steps.

steps:
  - id: example_suspend
    label: Example of step suspend
    type: suspend

id: Step identifier.
label: Name displayed on the Activities screen in the Workflow log.
type: Step type.

`run` Step

A Step of type run executes arbitrary Shell commands.

The command in the script parameter compresses the files into a tar.gz archive
steps:
  - id: step_id_1
    label: Step which says hello
    type: run
    script: |
      tar -czvf archive.tar.gz file1 file2

id: Step identifier.
label: Name displayed on the Activities screen in the Workflow log.
type: Step type.
script: Shell script that will be executed by the Step.

tip

Check how to generate outputs in the run type step

`workflow` Step

A Step of type workflow executes another Workflow published in your Studio.

steps:
  - id: step_id_1
    name: studio-name/workflow-name@1.0.0
    type: workflow
    inputs:
      input_1: "This is an example of fixed input"

id: Step identifier.
name: Name of the Workflow that the Step will execute. Use the format: studio-name/workflow-name@1.0.0(semantic version).

Warning!

The name field always uses the Studio Qualifier of the Workflow. This allows it to be executed inside or outside a Workspace. Learn more about the Studio Qualifier of Plugins to execute other Workflows.

type: Step type.
inputs: Filling in the inputs for the Workflow to be executed. The syntax to define them is:
- input_name: "input_value".

The label parameter is optional for Steps of the workflow type.

Executing Steps with Strategy Loop

The Strategy Loop in StackSpot Workflow allows you to execute a Step repeatedly for each value in a provided list. The Strategy Loop runs the same Step for every value in the list, iterating over each element.

During the execution of the Strategy Loop, two variables are automatically made available for use within the Step:

stk_loop_index: Represents the current position of the element in the list.
stk_loop_value: Represents the current value of the element in the list.

These variables can be used in different parts of the Step, such as in the script field, to customize the execution based on the current iteration value.

Example of a Workflow snippet demonstrating the use of Strategy Loop.
jobs:
  - id: job_id
    label: Job Label
    steps:
      - id: step_id
        type: run # 'run' type Step
        label: step label, prints the variables {{stk_loop_index}} and {{stk_loop_value}}
        strategy:
          loop: input_list # list-type input provided in the 'strategy.loop' field of the Workflow
        script: |
          echo "Example script that prints the position and value of the items in the provided list: {{stk_loop_index}} and {{stk_loop_value}}"

How the Strategy Loop Works

Defining the List: The list received by the Strategy Loop can be provided in two ways:

Via Input: a list-type input defined in the Workflow.

Example of a list-type input that receives a list of IP strings.
inputs:
  - label: Enter the list of IPs
    name: ips
    type: list
    add-question: Do you want to add more IPs to the list?
    input:
      type: text
      label: IP Address

In this example, the list of IPs is provided as a Workflow input.
jobs: # StackSpot Workflow Job
  - id: process_ip_list
    label: Process IPs
    steps: # Step that will use the 'ips' list
      - id: process_ip
        type: run 
        label: Process IP {{stk_loop_index}} - {{stk_loop_value}}
        strategy:
          loop: ips # list-type input defined in the previous example
        script: | # script execution using the 'strategy.loop' variables
          echo "IP processed at index {{stk_loop_index}}: {{stk_loop_value}}"

Tip!

The example uses a list-type input with text-type inputs, but you can use any input type supported by the list input:

text;
int;
object;
required-connection.

For more details about the list input, see the Inputs page.

Hardcoded: The list is defined directly in the strategy.loop field of the Workflow:

Example of a string list.
strategy:
  loop:
    - "192.168.0.1"
    - "10.0.0.1"
    - "172.16.0.1"

strategy:
  loop: ["192.168.0.1", "10.0.0.1", "172.16.0.1"]

Creating Conditional Triggers for Jobs and Steps

To declare a conditional trigger in a Job or Step, use the when parameter:

when: receives a boolean input, defined by a Jinja expression that must return "true" for the Job or Step to be executed. Available for Jobs and Steps.

Steps of type 'plugin' in a Workflow.
steps:
  - type: plugin
    name: studio/optional_plugin@1
    id: apply_optional_plugin
    label: Apply optional plugin
    when: "{{ boolean_input }}"
    inputs:
      some_plugin_input: "fixed_value"
      other_plugin_input: "{{ text_input | lower }}"
      input_from_other_job: "{{ outputs.some_job.some_action_execution.some_action_output }}"

This allows an entire Job or Step to be skipped during Workflow execution if it does not meet a certain condition.

Creating Dependency Between Workflow Jobs

Workflow Dependencies Using the targets Parameter

Workflow Steps

plugin Step

action Step

suspend Step

run Step

workflow Step

Executing Steps with Strategy Loop

How the Strategy Loop Works

Creating Conditional Triggers for Jobs and Steps

Workflow Dependencies Using the `targets` Parameter

`plugin` Step

`action` Step

`suspend` Step

`run` Step

`workflow` Step