Workflow namespaces

General

Mistral allows creating workflows within a namespace. So it is possible to create many workflows with the same name as long as they are in different namespaces. This is useful when a user already has many workflows that are connected to each other (some are sub workflows of others) and one of the workflow names is already in use and the user does not want to edit that workflow and all the ones referencing it or combine them into a workbook. This is possible because the namespace is not a part of the Mistral workflow language.

If one wants to use a namespace she needs to provide an additional parameter to a corresponding operation run via REST API or CLI. If it’s not provided, Mistral will be operating within the default namespace.

REST API parameters

In order to use namespaces Mistral a number of REST API methods have the optional namespace parameter:

• create workflow definition within a namespace:

  POST /v2/workflows?namespace=<namespace>
  
  <Workflow YAML text>
  

• delete workflow definition within a namespace:

  DELETE /v2/workflows/<workflow id>?namespace=<namespace>
  

• get a workflow definition within a namespace:

  GET /v2/workflows/<workflow id>?namespace=<namespace>
  

• get all workflow definitions within a given namespace:

  GET /v2/workflows?namespace=<namespace>
  

• update a workflow definition within a given namespace:

  PUT /v2/workflows?namespace=<namespace>
  
  <Workflow YAML text>
  

• create an execution of a workflow that belongs to a non-default namespace:

  POST /v2/executions
  
  {
    "workflow_name": "<workflow id or name>",
    "workflow_namespace": "<namespace>",
    ...
  }
  

Resolving a workflow definition

It’s important to understand how Mistral resolves a workflow definition taking namespaces into account when running workflows and how namespaces work in case of workflow hierarchies.

The rules are the following:

• If a user launches a workflow via API (or CLI) then the workflow name and the corresponding namespace are provided explicitly so Mistral will look for a workflow definition with the given name under the provided namespace. If a namespace is not specified then the default namespace (empty namespace value) will be used. If Mistral doesn’t find a workflow definition with the given name and namespace it will return an error response.

• If a workflow is launched as a sub workflow, i.e. it has a parent task in a different workflow, then Mistral uses the namespace of the parent workflow to resolve a workflow definition. In other words, Mistral propagates namespace to its child workflows. However, if a workflow definition does not exist in the namespace of the parent workflow then Mistral will try to find it in the default namespace. This is different from the previous case when a workflow is launched via API, Mistral would return an error instead of trying to find a workflow definition in the default namespace.

• Workflows declared as part of workbooks are always located in the default namespace.

To illustrate how this all works let’s look at the following workflow definitions:

---
version: '2.0'

wf1:
  tasks:
    t1:
      workflow: wf2

---
version: '2.0'

wf2:
  tasks:
    t2:
      workflow: wf3

---
version: '2.0'

wf3:
  tasks:
    t3:
      action: std.noop

---
version: '2.0'

wf3:
  tasks:
    should_not_run:
      action: std.fail

So the call chain looks like this:

wf1 -> wf2 -> wf3

However, notice that we have two workflows with the name “wf3”.

Let’s assume that these workflow definitions are uploaded to Mistral under these namespaces:

ID	name	namespace
1	wf1	abc
2	wf2
3	wf3	abc
4	wf3

And we create a workflow execution like this via API:

POST /v2/executions

{
  "workflow_name": "wf1",
  "workflow_namespace": "abc"
}

In this case, Mistral will:

• Find “wf1” in the namespace “abc” (it doesn’t exist in the default namespace anyway)

• Try to find “wf2” in the namespace “abc” and since it doesn’t exist there Mistral will find it in the default namespace

• Find “wf3” in the namespace “abc” because it is propagated from “wf1”

However, if we launch a workflow like this:

POST /v2/executions

{
  "workflow_name": "wf2"
}

We’ll get the call chain

wf2 -> wf3

And both workflow definitions will be taken from the default namespace because a non-default namespace wasn’t provided to the endpoint.