From 26f5658c441ae7c6a09cfae03ae5112c640aca23 Mon Sep 17 00:00:00 2001 From: Sharat Sharma Date: Thu, 17 Nov 2016 19:41:23 +0530 Subject: [PATCH] Small changes to docs to comply with openstack document style Change-Id: I65608499eb5793f7bdbaaf529def7bb934fc4d05 --- doc/source/terminology/actions.rst | 41 ++++++++++++++---------- doc/source/terminology/cron_triggers.rst | 4 ++- doc/source/terminology/executions.rst | 40 ++++++++++++++++------- doc/source/terminology/workbooks.rst | 22 ++++++++++--- doc/source/terminology/workflows.rst | 8 ++--- 5 files changed, 77 insertions(+), 38 deletions(-) diff --git a/doc/source/terminology/actions.rst b/doc/source/terminology/actions.rst index 7d701d69..4c080cba 100644 --- a/doc/source/terminology/actions.rst +++ b/doc/source/terminology/actions.rst @@ -1,38 +1,45 @@ Actions ======= -A particular instruction associated with a task that needs to be performed once the task runs. It can be anything like -running a shell script, HTTP request or sending a signal to some system external to Mistral. Actions can be synchronous -or asynchronous. +A particular instruction associated with a task that needs to be performed +once the task runs. It can be anything like: running a shell script, HTTP +request or sending a signal to some system external to Mistral. Actions can be +synchronous or asynchronous. -In case of synchronous action, Mistral will send a signal to Mistral Executor and will be waiting for the result from -Executor. Once Executor completes action, it sends the result to Mistral Engine. +In case of synchronous action, Mistral will send a signal to the Mistral +Executor and will be waiting for the result from the Executor. Once the +Executor completes the action, it sends the result to the Mistral Engine. -In case of asynchronous action Mistral will send a signal to third party service and will be waiting for a corresponding -action result to be delivered back to Mistral API. Once the signal is sent, Mistral won't care more about action state -and result. Third party service should do a request to Mistral API and provide info about corresponding -*action execution* and its state and result. +In case of asynchronous action, Mistral will send a signal to third party +service and will be waiting for a corresponding action result to be delivered +back to the Mistral API. Once the signal is sent, Mistral won't care more +about action state and result. Third party service should send a request to +the Mistral API and provide info about corresponding *action execution* and +its state and result. .. image:: /img/Mistral_actions.png :doc:`How to work with asynchronous actions ` -System Actions +System actions -------------- -System actions are provided by Mistral out of the box and can be used by anyone. It is also possible to add system -actions for specific Mistral installation via a special plugin mechanism. +System actions are provided by Mistral out of the box and can be used by +anyone. It is also possible to add system actions for specific Mistral +installation via a special plugin mechanism. :doc:`How to write an Action Plugin ` -Ad-hoc Actions +Ad-hoc actions -------------- -Ad-hoc actions are a special types of actions that can be created by user. Ad-hoc actions are always created as a -wrapper around any other existing system actions and their main goal is to simplify using same actions many times with -similar pattern. +Ad-hoc actions are a special types of actions that can be created by user. +Ad-hoc actions are always created as a wrapper around any other existing +system actions and their main goal is to simplify using same actions +many times with similar pattern. -.. note:: Nested ad-hoc actions currently are not supported (i.e. ad-hoc action around another ad-hoc action). +.. note:: Nested ad-hoc actions currently are not supported (i.e. ad-hoc +action around another ad-hoc action). .. note:: More about actions - :ref:`actions-dsl`. diff --git a/doc/source/terminology/cron_triggers.rst b/doc/source/terminology/cron_triggers.rst index 29f0a1cd..eb245e38 100644 --- a/doc/source/terminology/cron_triggers.rst +++ b/doc/source/terminology/cron_triggers.rst @@ -1,7 +1,9 @@ Cron-triggers ============= -Cron trigger is an object allowing to run workflow on a schedule. User specifies what workflow with what input needs to be run and also specifies how often it should be run. +Cron trigger is an object allowing to run workflow on a schedule. User +specifies what workflow with what input needs to be run and also specifies +how often it should be run. .. image:: /img/Mistral_cron_trigger.png :align: center diff --git a/doc/source/terminology/executions.rst b/doc/source/terminology/executions.rst index 5a0b8fe3..1b4bac63 100644 --- a/doc/source/terminology/executions.rst +++ b/doc/source/terminology/executions.rst @@ -1,45 +1,61 @@ Executions ========== -Executions are runtime objects and they reflect the information about the progress and state of concrete execution type. All executions are persisted in DB. +Executions are runtime objects and they reflect the information about the +progress and state of concrete execution type. -Workflow Execution +Workflow execution ------------------ -A particular execution of specific workflow. When user submits a workflow to run, Mistral creates an object in database for execution of this workflow. It contains all information about workflow itself, about execution progress, state, input and output data. Workflow execution contains at least one *task execution*. +A particular execution of specific workflow. When user submits a workflow to +run, Mistral creates an object in database for execution of this workflow. It +contains all information about workflow itself, about execution progress, +state, input and output data. Workflow execution contains at least one +*task execution*. -A workflow execution can be in one of a number of predefined states reflecting its current status: +A workflow execution can be in one of a number of predefined states reflecting +its current status: * **RUNNING** - workflow is currently being executed. * **PAUSED** - workflow is paused. * **SUCCESS** - workflow has finished successfully. * **ERROR** - workflow has finished with an error. -Task Execution +Task execution -------------- Defines a workflow execution step. It has a state and result. **Task state** -A task can be in one of a number of predefined states reflecting its current status: +A task can be in one of a number of predefined states reflecting its current +status: -* **IDLE** - task is not started yet; probably not all requirements are satisfied. -* **WAITING** - task execution object has been created but it is not ready to start because some preconditions are not met. **NOTE:** The task may never run just because some of the preconditions may never be met. -* **RUNNING_DELAYED** - task was in the running state before and the task execution has been delayed on precise amount of time. +* **IDLE** - task is not started yet; probably not all requirements are + satisfied. +* **WAITING** - task execution object has been created but it is not ready to + start because some preconditions are not met. **NOTE:** The task may never + run just because some of the preconditions may never be met. +* **RUNNING_DELAYED** - task was in the running state before and the task + execution has been delayed on precise amount of time. * **RUNNING** - task is currently being executed. * **SUCCESS** - task has finished successfully. * **ERROR** - task has finished with an error. All the actual task states belonging to current execution are persisted in DB. -Task result is an aggregation of all *action executions* belonging to current *task execution*. Usually one *task execution* has at least one *action execution*. But in case of task is executing nested workflow, this *task execution* won't have *action executions*. Instead, there will be at least one *workflow execution*. +Task result is an aggregation of all *action executions* belonging to current +*task execution*. Usually one *task execution* has at least one +*action execution*. But in case of task is executing nested workflow, this +*task execution* won't have *action executions*. Instead, there will be at +least one *workflow execution*. -Action Execution +Action execution ---------------- Execution of specific action. To see details about actions, please refer to :ref:`actions-dsl` Action execution has a state, input and output data. -Usually action execution belongs to task execution but Mistral also is able to run separate action executions. +Usually action execution belongs to task execution but Mistral also is able to run +separate action executions. diff --git a/doc/source/terminology/workbooks.rst b/doc/source/terminology/workbooks.rst index 4b98ff5d..71754bcc 100644 --- a/doc/source/terminology/workbooks.rst +++ b/doc/source/terminology/workbooks.rst @@ -1,16 +1,28 @@ Workbooks ========= -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). +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. +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. +So after a workbook has been uploaded its workflows and actions become +independent objects but with slightly different names. YAML example ^^^^^^^^^^^^ @@ -55,7 +67,9 @@ YAML example - 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. +**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** diff --git a/doc/source/terminology/workflows.rst b/doc/source/terminology/workflows.rst index ed25b719..d4f6ac77 100644 --- a/doc/source/terminology/workflows.rst +++ b/doc/source/terminology/workflows.rst @@ -35,7 +35,7 @@ YAML example         delay: 5         count: 15 -Workflow Types +Workflow types -------------- Mistral DSL v2 introduces different workflow types and the structure of @@ -47,7 +47,7 @@ provides two workflow types: See corresponding sections for details. -Direct Workflow +Direct workflow --------------- Direct workflow consists of tasks combined in a graph where every next @@ -88,7 +88,7 @@ YAML example     send_success_email:       action: send_email to='admin@mysite.org' body='Vm is successfully created and its id: <% $.vm_id %>' -Reverse Workflow +Reverse workflow ---------------- In reverse workflow all relationships in workflow task graph are @@ -136,4 +136,4 @@ YAML example       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 +For more details about DSL itself, please see :doc:`Mistral DSL specification `