Mistral

Docs: fill the gaps

Registered by Sharat Sharma on 2017-04-10

There are a few documents which are missing and have to be documented.
The following documents are the ones to be documented:

1.Using workflow environments. There is info in API spec and CLI spec but there's no explanation what it is and what it is for. It should be either a separate article or an addition to DSL spec (which, like I said above, I suggest we rename to 'Mistral Language spec')

2. There's no information anywhere about action defaults (which we can pass, for example, in a workflow environment)

3. There's no explicit info about how to pause and resume/re-run workflows. It may be worth a separate article. But even a better option would be to have an article called something like "Managing workflows" or "Managing life-cycle of workflows" that would describe typical scenarios of what we can do with workflows. Same about monitoring.

4. Missing the information about error handling chain. For example, if Mistral engine accepted some action result and successfully saved it but then in task definition (e.g. 'on-success' or 'publish' clause) we have an expression syntax mistake then action execution will be saved successfully with SUCCESS state but task execution will be stored with state "ERROR" and state_info containing the description of the error.
5. Missing an article about state transactions for various Mistral objects. For example, we need to know how a typical life-cycle of a workflow execution looks like and what states it goes through. Same for tasks and actions.

5. API v2 article (http://docs.openstack.org/developer/mistral/developer/webapi/v2.html):
    * No proper information about sub endpoints (/executions/<id>/tasks, /tasks/<id>/action_executions, /tasks/<id>/action_executions and /tasks/<id>/workflow_executions)
   * In the section about action executions there are mistakes. For example, for "GET /v2/action_executions" we have "Return all tasks within the execution."
   * For "GET /v2/executions" we have "Return all tasks within the execution."
   * It's confusing that we use same relative urls for collections and single objects. For example, "GET /v2/environments" is used for getting all environments and a single environment by id. In the second case it should be something like "GET /v2/environments/<id>". Applies to all endpoints.
   * Generally, as far as API I think we need to revisit how we format our docs. There may be a better way.

6. DSL v2 article (http://docs.openstack.org/developer/mistral/dsl/dsl_v2.html):
   * We need to add more on expressions. Once https://review.openstack.org/#/c/374813/ is merge we'll have Jinja2 support in Mistral and I think we need to have a separate paragraph on basics of YAQL and Jinja and may be even a paragraph with comparison between these two so that people can choose what to use in their workflows (or combine them). On YAQL I would also add some basic info right in Mistral docs since YAQL's own doc is still far from ideal.
    * We're missing all available YAQL/Jinja functions in the specifications. Section http://docs.openstack.org/developer/mistral/dsl/dsl_v2.html#predefined-values-functions-in-execution-data-context needs to be revisited and updated. For example, it's not clear that using 'task()' we can also access fields other than 'result' (also 'state', 'state_info' etc.). Also need to add a link to the article about writing custom YAQL functions.
    * There's no any information about what action can return. For example, actions can return an error result which is not just an exception string but a structured result accessible in a workflow. In case of std.http we can get HTTP error status code which we can analyze and make decisions upon.

7. Mistral Topologies - all-in-one, many executors, many engines, many apis behind a LB. It would also be helpful to have recommendations on what topology is particularly useful for and how scaling of a certain tier influences the system behavior.

8. Stop using abbreviation DSL and change it to "Workflow language" or "Mistral language" in the documentation. Our experience shows that it confuses people sometimes when the word "DSL" is used. It needs to be fixed throughout the whole documentation. Internally we can keep using the work "DSL" though.