diff --git a/doc/source/img/Mistral_workbook_namespacing.png b/doc/source/img/Mistral_workbook_namespacing.png index 4fbf32f08..21942e006 100644 Binary files a/doc/source/img/Mistral_workbook_namespacing.png and b/doc/source/img/Mistral_workbook_namespacing.png differ diff --git a/doc/source/terminology/workbooks.rst b/doc/source/terminology/workbooks.rst index cc5cee0c3..4b98ff5d2 100644 --- a/doc/source/terminology/workbooks.rst +++ b/doc/source/terminology/workbooks.rst @@ -1,4 +1,68 @@ Workbooks ========= -TBD \ No newline at end of file +Using workbooks users can combine multiple entities of any type (workflows and actions) into one document and upload to Mistral service. When uploading a workbook Mistral will parse it and save its workflows and actions as independent objects which will be accessible via their own API endpoints (/workflows and /actions). Once it's done the workbook comes out of the game. User can just start workflows and use references to workflows/actions as if they were uploaded without workbook in the first place. However, if need to modify these individual objects user can modify the same workbook definition and re-upload it to Mistral (or, of course, user can do it independently). + +**Namespacing** + +One thing that's worth noting is that when using a workbook Mistral uses its name as a prefix for generating final names of workflows and actions included into the workbook. To illustrate this principle let's take a look at the figure below. + +.. image:: /img/Mistral_workbook_namespacing.png + :align: center + +So after a workbook has been uploaded its workflows and actions become independent objects but with slightly different names. + +YAML example +^^^^^^^^^^^^ +:: + + --- + version: '2.0' + + name: my_workbook + description: My set of workflows and ad-hoc actions + + workflows: + local_workflow1: + type: direct + + tasks: + task1: + action: local_action str1='Hi' str2=' Mistral!' + on-complete: + - task2 + + task2: + action: global_action + ... + + local_workflow2: + type: reverse + + tasks: + task1: + workflow: local_workflow1 + + task2: + workflow: global_workflow param1='val1' param2='val2' + requires: [task1] + ... + + actions: + local_action: + input: + - str1 + - str2 + base: std.echo output="<% $.str1 %><% $.str2 %>" + +**NOTE:** Even though names of objects inside workbooks change upon uploading Mistral allows referencing between those objects using local names declared in the original workbook. + +**Attributes** + +* **name** - Workbook name. **Required.** +* **description** - Workbook description. *Optional*. +* **tags** - String with arbitrary comma-separated values. *Optional*. +* **workflows** - Dictionary containing workflow definitions. *Optional*. +* **actions** - Dictionary containing ad-hoc action definitions. *Optional*. + +For more details about DSL itself, please see :doc:`Mistral DSL specification ` diff --git a/doc/source/terminology/workflows.rst b/doc/source/terminology/workflows.rst index 4b0aedbe5..ed25b719a 100644 --- a/doc/source/terminology/workflows.rst +++ b/doc/source/terminology/workflows.rst @@ -1,4 +1,139 @@ Mistral Workflows ================= -TBD \ No newline at end of file +Workflow is the main building block of Mistral DSL, the reason why the +project exists. Workflow represents a process that can be described in a +various number of ways and that can do some job interesting to the end +user. Each workflow consists of tasks (at least one) describing what +exact steps should be made during workflow execution. + +YAML example +^^^^^^^^^^^^ +:: + + --- + version: '2.0' + create_vm: +   description: Simple workflow sample +   type: direct +   input: # Input parameter declarations +     - vm_name +     - image_ref +     - flavor_ref +   output: # Output definition +     vm_id: <% $.vm_id %> +   tasks: +     create_server: +       action: nova.servers_create name=<% $.vm_name %> image=<% $.image_ref %> flavor=<% $.flavor_ref %> +       publish: +         vm_id: <% $.id %> +       on-success: +         - wait_for_instance +     wait_for_instance: +       action: nova.servers_find id=<% $.vm_id %> status='ACTIVE' +       retry: +         delay: 5 +         count: 15 + +Workflow Types +-------------- + +Mistral DSL v2 introduces different workflow types and the structure of +each workflow type varies according to its semantics. Currently, Mistral +provides two workflow types: + +- `Direct workflow <#direct-workflow>`__ +- `Reverse workflow <#reverse-workflow>`__ + +See corresponding sections for details. + +Direct Workflow +--------------- + +Direct workflow consists of tasks combined in a graph where every next +task starts after another one depending on produced result. So direct +workflow has a notion of transition. Direct workflow is considered to be +completed if there aren't any transitions left that could be used to +jump to next tasks. + +.. image:: /img/Mistral_direct_workflow.png + +YAML example +^^^^^^^^^^^^ +:: + + --- + version: '2.0' + create_vm_and_send_email: +   type: direct +   input: +     - vm_name +     - image_id +     - flavor_id +   output: +     result: <% $.vm_id %> +   tasks: +     create_vm: +       action: nova.servers_create name=<% $.vm_name %> image=<% $.image_id %> flavor=<% $.flavor_id %> +       publish: +         vm_id: <% $.id %> +       on-error: +         - send_error_email +       on-success: +         - send_success_email +     send_error_email: +       action: send_email to='admin@mysite.org' body='Failed to create a VM' +       on_complete: +         - fail +     send_success_email: +       action: send_email to='admin@mysite.org' body='Vm is successfully created and its id: <% $.vm_id %>' + +Reverse Workflow +---------------- + +In reverse workflow all relationships in workflow task graph are +dependencies. In order to run this type of workflow we need to specify a +task that needs to be completed, it can be conventionally called 'target +task'. When Mistral Engine starts a workflow it recursively identifies +all the dependencies that need to be completed first. + +.. image:: /img/Mistral_reverse_workflow.png + +The figure explains how reverse workflow works. In the example, task +**T1** is chosen a target task. So when the workflow starts Mistral will +run only tasks **T7**, **T8**, **T5**, **T6**, **T2** and **T1** in the +specified order (starting from tasks that have no dependencies). Tasks +**T3** and **T4** won't be a part of this workflow because there's no +route in the directed graph from **T1** to **T3** or **T4**. + +YAML example +^^^^^^^^^^^^ +:: + + --- + version: '2.0' + create_vm_and_send_email: +   type: reverse +   input: +     - vm_name +     - image_id +     - flavor_id +   output: +     result: <% $.vm_id %> +   tasks: +     create_vm: +       action: nova.servers_create name=<% $.vm_name %> image=<% $.image_id %> flavor=<% $.flavor_id %> +       publish: +         vm_id: <% $.id %> +     search_for_ip: +       action: nova.floating_ips_findall instance_id=null +       publish: +         vm_ip: <% $[0].ip %> +     associate_ip: +       action: nova.servers_add_floating_ip server=<% $.vm_id %> address=<% $.vm_ip %> +       requires: [search_for_ip] +     send_email: +       action: send_email to='admin@mysite.org' body='Vm is created and id <% $.vm_id %> and ip address <% $.vm_ip %>' +       requires: [create_vm, associate_ip] + +For more details about DSL itself, please see :doc:`Mistral DSL specification ` \ No newline at end of file