Merge "Update docs for tasks function"

doc/source/dsl/dsl_v2.rst

@@ -1082,8 +1082,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='<class 'mistral.actions.action_factory.FailAction'>', attributes='{}', params='{}']\n Fail action expected exception.",
+        "result": "Failed to run action [action_ex_id=bcb04b28-6d50-458e-9b7e-a45a5ff1ca01, action_cls='<class 'mistral.actions.action_factory.FailAction'>', 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(<task_name>).result**. It contains task result
 and directly depends on action output structure. Note that the *task(<task_name>)*