[odoo/odoo.git] / doc / reference / workflows.rst

.. _reference/workflows:

Workflows
=========

In Odoo, a workflow is a technical artefact to manage a set of "things to
do" associated to the records of a model. The workflow provides a higher-level
way to organize tasks to perform with or on a record.

More specifically, a workflow is a directed graph where the nodes are called
"activities" and the arcs are called "transitions".

- Activities define work that should be done within the Odoo server, such
  as changing the state of some records, or sending emails.
- Transitions control how the workflow progresses from activity to activity.

In the definition of a workflow, one can attach conditions, signals, and
triggers to transitions, so that the behavior of the workflow depends on user
actions (such as clicking on a button), changes to records, or arbitrary
Python code.

All in all, Odoo's workflow system provides:

* a description of the evolution of a record (document) over time
* automatic actions based on various and flexible conditions
* management of company roles and validation steps
* management of interactions between objects
* a visual representation of document flows through their lifecycle

For instance, a basic order could have the following flow:

.. sphinx.ext.graphviz would be nice, but it requires ``dot`` on any machine
.. where the doc is compiled... otoh this is a pain in the ass because you
.. need 2 compilation steps (dot -> image and rst -> html) every time

.. image:: workflow/order_0.*
    :align: center

Orders start in the *Draft* state, can be *Confirmed* by a user, and then
either shipped (*Closed*) or *Canceled*.

A company using Odoo may want to add discount support to orders, where sales
staff has discretionary discounting powers up to 15%, but manager validation
is required for discounts beyond 15%. The workflow can be altered online to
add the relevant steps without editing Python or XML files:

.. image:: workflow/order_1.*
    :align: center

Because Activities can perform arbitrary actions, the *Validation* can
automatically send a validation request to the relevant employee.

.. note:: the order view needs to be modified to add an *Accept Discount*
          button for managers

Basics
------

Defining a workflow with data files is straightforward: a record "workflow" is
given together with records for the activities and the transitions. For
instance, here is a simple sequence of two activities defined in XML

.. code-block:: xml

    <record id="test_workflow" model="workflow">
        <field name="name">test.workflow</field>
        <field name="osv">test.workflow.model</field>
        <field name="on_create">True</field>
    </record>

    <record id="activity_a" model="workflow.activity">
        <field name="wkf_id" ref="test_workflow"/>
        <field name="flow_start">True</field>
        <field name="name">a</field>
        <field name="kind">function</field>
        <field name="action">print_a()</field>
    </record>
    <record id="activity_b" model="workflow.activity">
        <field name="wkf_id" ref="test_workflow"/>
        <field name="flow_stop">True</field>
        <field name="name">b</field>
        <field name="kind">function</field>
        <field name="action">print_b()</field>
    </record>

    <record id="trans_a_b" model="workflow.transition">
        <field name="act_from" ref="activity_a"/>
        <field name="act_to" ref="activity_b"/>
    </record>

A worfklow is always defined with respect to a particular model (the model is
given by the attribute ``osv`` on the model ``workflow``). Methods specified
in the activities or transitions will be called on that model.

In the example code above, a workflow called "test_workflow" is created. It is
made up of two activies, named "a" and "b", and one transition, going from "a"
to "b".

The first activity has its attribute ``flow_start`` set to ``True`` so that
Odoo knows where to start the workflow traversal after it is instanciated.
Because ``on_create`` is set to True on the workflow record, the workflow is
instanciated for each newly created record. (Otherwise, the workflow should be
instanciated by other means, such as from some module Python code.)

When the workflow is instanciated, it begins with activity "a". That activity
is of kind ``function``, which means that the action ``print_a()`` is a method
call on the model ``test.workflow`` (the usual ``cr, uid, ids, context``
arguments are passed for you).

The transition between "a" and "b" does not specify any condition. This means
that the workflow instance immediately goes from "a" to "b" after "a" has been
processed, and thus also processes activity "b".

Activities
----------

While the transitions can be seen as the control structures of the workflows,
activities are the places where everything happens, from changing record
states to sending email.

Different kinds of activities exist: ``Dummy``, ``Function``, ``Subflow``, and
``Stop all``, each doing different things when the activity is processed. In
addition to their kind, activies have other properties, detailed in the next
sections.

Flow start and flow stop
''''''''''''''''''''''''

The attribute ``flow_start`` is a boolean value specifying whether the activity
is processed when the workflow is instanciated. Multiple activities can have
their attribute ``flow_start`` set to ``True``. When instanciating a workflow
for a record, Odoo simply processes all of them, and evaluate all their
outgoing transitions afterwards.

The attribute ``flow_stop`` is a boolean value specifying whether the activity
stops the workflow instance. A workflow instance is considered completed when
all its activities with the attribute ``flow_stop`` set to ``True`` are
completed.

It is important for Odoo to know when a workflow instance is completed. A
workflow can have an activity that is actually another workflow (called a
subflow); that activity is completed when the subflow is completed.

Subflow
'''''''

An activity can embed a complete workflow, called a subflow (the embedding
workflow is called the parent workflow). The workflow to instanciate is
specified by attribute ``subflow_id``.

.. note:: In the GUI, that attribute can not be set unless the kind of the
          activity is ``Subflow``.

The activity is considered completed (and its outgoing transitions ready to be
evaluated) when the subflow is completed (see attribute ``flow_stop`` above).

Sending a signal from a subflow
'''''''''''''''''''''''''''''''

When a workflow is embedded in an activity (as a subflow) of a workflow, the
sublow can send a signal from its own activities to the parent workflow by
giving a signal name in the attribute ``signal_send``. Odoo processes those
activities by sending the value of ``signal_send`` prefixed by "subflow."  to
the parent workflow instance.

In other words, it is possible to react and get transitions in the parent
workflow as activities are executed in the sublow.

Server actions
''''''''''''''

An activity can run a "Server Action" by specifying its ID in the attribute
``action_id``.

Python action
'''''''''''''

An activity can execute some Python code, given by the attribute ``action``.
The evaluation environment is the same as the one explained in the section
`Conditions`_.

Split mode
''''''''''

After an activity has been processed, Odoo evaluates its transition to reach
the next activity in the flow.

However if an activity has more than one transition, Odoo must decide which
activity or activities to follow.

.. image:: workflow/split.*
    :align: center

This choice is controlled by the ``split_mode`` attribute:

``XOR`` (default)
    By default, Odoo will use the first transition (in ``sequence`` order)
    whose condition is satisfied. All other transitions are ignored.
``OR``
    In ``OR`` mode, all transitions with a satisfied condition are traversed
    simultanously. Transitions not yet valid will be ignored, even if they
    become valid later.
``AND``
    In ``AND`` mode, Odoo will wait until *all* transitions are satisfied, and
    will traverse all of them (much like the ``OR`` mode).

Both ``OR`` and ``AND`` mode will lead to activities being active in the same
workflow.

Join mode
'''''''''

Just like outgoing transition conditions can be combined together to decide
whether they can be traversed or not, incoming transitions can be combined
together to decide if and when an activity may be processed.

.. image:: workflow/join.*
    :align: center

The ``join_mode`` attribute controls that behavior:

``XOR`` (default)
    Any incoming transition enables the activity and starts its processing.
``AND``
    The activity is enabled and processed only once *all* incoming transitions
    have been traversed.

Kinds
'''''

An activity's kind defines the type of work an activity can perform.

Dummy (``dummy``, default)
    Do nothing at all, or call a server action. Often used as dispatch or
    gather "hubs" for transitions.
Function (``function``)
    Run some python code, execute a server action.
Stop all (``stopall``)
    Completely stops the workflow instance and marks it as completed.
Subflow (``subflow``)
    Starts executing an other workflow, once that workflow is completed the
    activity is done processing.

    By default, the subflow is instanciated for the same record as the parent
    workflow. It is possible to change that behavior by providing Python code
    that returns a record ID (of the same data model as the subflow). The
    embedded subflow instance is then the one of the given record.


Transitions
-----------

Transitions provide the control structures to orchestrate a workflow. When an
activity is completed, the workflow engine tries to get across transitions
departing from the completed activity, towards the next activities. In their
simplest form (as in the example above), they link activities sequentially:
activities are processed as soon as the activities preceding them are
completed.

Instead of running all activities in one fell swoop, it is also possible to
wait on transitions, going through them only when some criteria are met. The
criteria are the conditions, the signals, and the triggers. They are detailed
in the following sections.

Conditions
''''''''''

When an activity has been completed, its outgoing transitions are inspected to
determine whether it is possible for the workflow instance to proceed through
them and reach the next activities. When only a condition is defined (i.e., no
signal or trigger is defined), the condition is evaluated by Odoo, and if
it evaluates to ``True``, the worklfow instance progresses through the
transition.  If the condition is not met, it will be reevaluated every time
the associated record is modified, or by an explicit method call to do it.

By default, the attribute ``condition`` (i.e., the expression to be evaluated)
is just "True", which trivially evaluates to ``True``. Note that the condition
may be several lines long; in that case, the value of the last one determines
whether the transition can be taken.

In the condition evaluation environment, several symbols are conveniently
defined (in addition to the Odoo ``safe_eval`` environment):

- all the model column names, and
- all the browse record's attributes.

Signals
'''''''

In addition to a condition, a transition can specify a signal name. When such
a signal name is present, the transition is not taken directly, even if the
condition evaluates to ``True``. Instead the transition blocks, waiting to be
woken up.

In order to wake up a transition with a defined signal name, the signal must
be sent to the workflow instance. A common way to send a signal is to use a
button in the user interface, using the element ``<button/>`` with the signal
name as the attribute ``name`` of the button. Once the button is clicked, the
signal is sent to the workflow instance of the current record.

.. note:: The condition is still evaluated when the signal is sent to the
          workflow instance.

Triggers
''''''''

With conditions that evaluate to ``False``, transitions are not taken (and
thus the activity it leads to is not processed immediately). Still, the
workflow instance can get new chances to progress across that transition by
providing so-called triggers. The idea is that when the condition is not
satisfied, triggers are recorded in database. Later, it is possible to wake up
specifically the workflow instances that installed those triggers, offering
them to reevaluate their transition conditions. This mechanism makes it
cheaper to wake up workflow instances by targetting just a few of them (those
that have installed the triggers) instead of all of them.

Triggers are recorded in database as record IDs (together with the model name)
and refer to the workflow instance waiting for those records. The transition
definition provides a model name (attribute ``trigger_model``) and a Python
expression (attribute ``trigger_expression``) that evaluates to a list of
record IDs in the given model. Any of those records can wake up the workflow
instance they are associated with.

.. note:: triggers are not re-installed whenever the transition is re-tried.