Merge "Mistral docs terminology: workbooks and workflows"

doc/source/terminology/workbooks.rst

@@ -1,4 +1,68 @@
 Workbooks
 =========
 
-TBD
+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 </dsl/index>`

doc/source/terminology/workflows.rst

@@ -1,4 +1,139 @@
 Mistral Workflows
 =================
 
-TBD
+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 </dsl/index>`