.. _apps_workflow:

Workflow
********

.. include:: workflow_id.inc
.. include:: workflow_aliases.inc

Description
===========

The Workflow application enables you to automate your pipelines by applying actions defined in rules that are triggered when certain conditions are met. The application works as follows:

* Custom variables are resolved sequentially

  * Variables are given a

    * User-defined name, which can be referenced in the user-defined rules
    * JSON path expression into the :ref:`Document <json_document>` from which the variable gets its data. The result of this expression, if it resolves, is always an array of matches

  * By default, a special variable representing the document is available as ``document``. For example, the document's ID can be referenced as ``document.id``

* Rules are considered sequentially

  * Conditions are evaluated

    * Any explicitly listed variables are looked up

      * If the variables are found to be resolved (see previous step), the rule triggers
      * If any variable is unresolved, the rule is skipped

    * Any implicitly listed variables -- referenced in the action's configuration -- are looked up

      * If the variables are found to be resolved (see previous step), the rule triggers
      * If any variable is unresolved, the rule is skipped

  * Actions are applied: if the rule triggers, the action is applied using the provided configuration

.. note::

  The JSON path expression is standard compliant, including arithmetic and binary comparison operators and conforms toe the original ``JSONPath`` proposal defined in to https://goessner.net/articles/JsonPath/

Configuration
=============

The configuration is an object defined as (**bold = required**, *italic = optional*):

* **variables** (``array[Variable]``) -- The list of variables accessible in the rules
* **rules** (``array[Rule]``) -- The list of rules to be considered

With ``Variable`` defined as:

* ``object`` -- The variable

  * **name** (``string``) -- The name of the variable
  * **expression** (``string``) -- The JSON path expression pointing to the data that will be held by the variable

And ``Rule`` defined as:

* ``object`` -- The rule to be considered

  * **action** (``string``) -- The :ref:`action <apps_workflow_actions>` to be applied if the rule triggers
  * **config** (``object``) -- The configuration for the action. This is an ``object`` with fields determined by the particular action. The configuration can use variables. In case referenced variables are not present, the rule is not triggered
  * *requires* (``array[string]``) -- An optional list of *explicitly* listed variables that must be present in order for the rule to be triggered. This list is in addition to the list of *implicit* variables found in the action's configuration

.. _apps_workflow_actions:

Actions
-------

.. list-table:: 
    :widths: 20 40 40
    :header-rows: 1

    * - Name
      - Description
      - Configuration
    * - ``Run``
      - Insert and run additional steps in the pipeline
      - **pipeline** (``string``) -- The comma-separated list of pipeline steps to be inserted
    * - ``WebHook``
      -  Perform a REST call to a web URL to hook into your pipeline
      - | **url** (``string``) -- The web URL to call
        | **method** (``string``) -- Either ``GET`` or ``POST``. In the latter case, the current :ref:`document <json_document>` is passed as the body of an ``application/json`` content request and the response, if it contains a valid document is used further along the pipeline. This allows you to perform any custom operations on the document, including altering, adding or removing data


Example
=======

.. include:: workflow_example.inc

yields:

.. include:: workflow_results.inc