From 77084f7de173dab3545cf742aa950cd85980844b Mon Sep 17 00:00:00 2001 From: Michal Gershenzon Date: Mon, 13 Feb 2017 14:50:53 +0000 Subject: [PATCH] Update docs for tasks function tasks function can be used to get all tasks in state error of a given workflow execution and more. Change-Id: I64e101bf36e0d865342e848723b610bfe23423d9 --- doc/source/dsl/dsl_v2.rst | 141 +++++++++++++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 1 deletion(-) diff --git a/doc/source/dsl/dsl_v2.rst b/doc/source/dsl/dsl_v2.rst index 70a826bc..791c3cde 100644 --- a/doc/source/dsl/dsl_v2.rst +++ b/doc/source/dsl/dsl_v2.rst @@ -1069,8 +1069,147 @@ OpenStack context is available by **$.openstack**. It contains **auth_token,** **project_id**, **user_id**, **service_catalog**, **user_name**, **project_name**, **roles**, **is_admin** properties. + +Builtin functions in expressions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In addition to the current context (i.e. $ in YAQL and _ in Jinja2) expressions +have access to a set of predefined functions. + + +The expression languages come with their own individual included functions and +operations. Mistral adds the following functions that are available in all the +supported languages. + +This section will describe builtin functions added by Mistral. + +Tasks function +'''''''''''''' + +Signature: + **tasks(workflow_execution_id=null, recursive=false, state=null, flat=false)** + +Description: + + This function allows users to filter all tasks by workflow execution id + and/or state. In addition, it is possible to get task executions recursively + and flatten the task executions list. + +Parameters: + + #. **workflow_execution_id** - If provided the tasks function will return + task executions for a specific workflow execution (either the current + execution or a different one). Otherwise it will return all task + executions that match the other parameters. *Optional.* + #. **recursive** - This parameter is a boolean value, if it is true then all + task executions within nested workflow executions will be returned. This + is usually used in combination with a specific workflow_execution_id + where you still want to see nested workflow's task executions. *Optional.* + False by default. + #. **state** - If provided, the task executions will be filtered by their + current state. If state isn't provided, all task executions that match the + other parameters will be returned . *Optional.* + #. **flat** - if true, only list the task executions that match at least one + of the next conditions: + + * task executions of type action + * task executions of type workflow that have a different state from the + workflow execution they triggered. For example, if used with a + specific workflow_execution_id and the state ERROR it will return + tasks that erred despite the workflow succeeding. This can mean that + there was an error in the task itself, like an invalid expression in + publish. + + *Optional.* False by default. + +Example: + +Workflow definition: + +.. code-block:: yaml + + --- + version: "v2.0" + wf: + tasks: + task: + action: std.noop + publish: + all_tasks_in_this_wf_yaql: <% tasks(execution().id) %> + all_tasks_in_this_wf_jinja: "{{ tasks(execution().id) }}" + + all_tasks_in_error_yaql: <% tasks(null, false, ERROR) %> + all_tasks_in_error_jinja: "{{ tasks(None, false, 'ERROR') }}" + all_tasks_in_error_yaql_with_kw: <% tasks(state => ERROR) %> + all_tasks_in_error_jinja_with_kw: "{{ tasks(state='ERROR') }}" + + all_tasks_yaql_option1: <% tasks() %> + all_tasks_yaql_option2: <% tasks(null, false, null, false) %> + all_tasks_jinja_option1: "{{ tasks() }}" + all_tasks_jinja_option2: "{{ tasks(None, false, None, false) }}" + +Task publish result (partial to keep the documentation short): + +.. warning:: + The return value for each task execution hasn't been finalized and isn't + considered stable. It may change in a future Mistral release. + +.. code-block:: json + + { + "all_tasks_in_error_yaql": [ + { + "id": "3d363d4b-8c19-48fa-a9a0-8721dc5469f2", + "name": "fail_task", + "type": "ACTION", + "workflow_execution_id": "c0a4d2ff-0127-4826-8370-0570ef8cad80", + "state": "ERROR", + "state_info": "Failed to run action [action_ex_id=bcb04b28-6d50-458e-9b7e-a45a5ff1ca01, action_cls='', attributes='{}', params='{}']\n Fail action expected exception.", + "result": "Failed to run action [action_ex_id=bcb04b28-6d50-458e-9b7e-a45a5ff1ca01, action_cls='', attributes='{}', params='{}']\n Fail action expected exception.", + "published": {}, + "spec": { + "action": "std.fail", + "version": "2.0", + "type": "direct", + "name": "fail_task" + } + } + ], + "all_tasks_in_this_wf_jinja": [ + { + "id": "83a34bfe-268c-46f5-9e5c-c16900540084", + "name": "task", + "type": "ACTION", + "workflow_execution_id": "899a3318-b5c0-4860-82b4-a5bd147a4643", + "state": "SUCCESS", + "state_info": null, + "result": null, + "published": {}, + "spec": { + "action": "std.noop", + "version": "2.0", + "type": "direct", + "name": "task", + "publish": { + "all_tasks_in_error_yaql": "<% tasks(null, false, ERROR) %>", + "all_tasks_in_error_jinja": "{{ tasks(None, false, 'ERROR') }}", + "all_tasks_yaql_option2": "<% tasks(null, false, false, false) %>", + "all_tasks_yaql_option1": "<% tasks() %>", + "all_tasks_jinja_option1": "{{ tasks() }}", + "all_tasks_in_error_jinja_with_kw": "{{ tasks(state='ERROR') }}", + "all_tasks_jinja_option2": "{{ tasks(None, false, None, false) }}", + "all_tasks_in_this_wf_jinja": "{{ tasks(execution().id) }}", + "all_tasks_in_this_wf_yaql": "<% tasks(execution().id) %>" + } + } + } + ], + "_comment": "other fields were dropped to keep docs short" + } + + Task result -^^^^^^^^^^^ +''''''''''' Task result is available by **task().result**. It contains task result and directly depends on action output structure. Note that the *task()*