doc/workflows.rst

   1 .. _workflows:
   2
   3 Workflows
   4 =========
   5
   6 A workflow is a directed graph where the nodes are called "activities" and the
   7 arcs are called "transitions".
   8
   9 - Activities define work that should be done within the OpenERP server, such as
  10   changing the state of some records, or sending mails.
  11
  12 - Transitions control how the workflow will go from activities to activities.
  13
  14 When defining a workflow, one can attach conditions, signals, and triggers to
  15 transitions, so that the behavior of the workflow can depend on user actions
  16 (such as clicking on a button), changes to records, or arbitrary Python code.
  17
  18 Basics
  19 ------
  20
  21 Defining a workflow with data files is straightforward: a record "workflow" is
  22 needed together with records for the activities and the transitions. For
  23 instance here is a simple sequence of two activities defined in XML::
  24
  25     <record id="test_workflow" model="workflow">
  26         <field name="name">test.workflow</field>
  27         <field name="osv">test.workflow.model</field>
  28         <field name="on_create">True</field>
  29     </record>
  30
  31     <record id="activity_a" model="workflow.activity">
  32         <field name="wkf_id" ref="test_workflow"/>
  33         <field name="flow_start">True</field>
  34         <field name="name">a</field>
  35         <field name="kind">function</field>
  36         <field name="action">print_a()</field>
  37     </record>
  38     <record id="activity_b" model="workflow.activity">
  39         <field name="wkf_id" ref="test_workflow"/>
  40         <field name="flow_stop">True</field>
  41         <field name="name">b</field>
  42         <field name="kind">function</field>
  43         <field name="action">print_b()</field>
  44     </record>
  45
  46     <record id="trans_a_b" model="workflow.transition">
  47         <field name="act_from" ref="activity_a"/>
  48         <field name="act_to" ref="activity_b"/>
  49     </record>
  50
  51 A worfklow is always defined with respect to a particular model (the model is
  52 given through the ``osv`` attribute on the ``workflow`` model). Methods
  53 specified in the activities or transitions will be called on that model.
  54
  55 In the example code above, a workflow called "test_workflow" is created. It is
  56 made up of two activies, named "a" and "b", and one transition, going from "a"
  57 to "b".
  58
  59 The first activity has its ``flow_start`` attribute set to True so that OpenERP
  60 knows where to start the workflow when it is instanciated. Because
  61 ``on_create`` is set to True on the workflow record, the workflow is
  62 instanciated for each newly created record. (Otherwise, the workflow should be
  63 created by other means, such as from some module Python code.)
  64
  65 When the workflow is instanciated, it will start by the "a" activity. That
  66 activity is of kind ``function`` which means the action ``print_a()`` is a
  67 method to be called on the ``test.workflow`` model (the usual ``cr, uid, ids,
  68 context`` arguments are passed for you).
  69
  70 The transition between "a" and "b" does not specify any conditions. This means
  71 the workflow instance will immediately progress from "a" to "b" (after "a" has
  72 been processed), and thus also process the "b" activity.
  73
  74 Transitions
  75 -----------
  76
  77 Transitions provide the control structures to orchestrate a workflow. When an
  78 activity is completed, the workflow engine will try to get across transitions
  79 departing from the completed activity, towards the next activities.  In their
  80 simplest form they just link activities from one to the others (as in the
  81 example above), and activities are processed as soon as the activities
  82 preceding them are completed.
  83
  84 But instead of running all activities in one fell swoop, it is also possible to
  85 block on transitions, going through them only when some criteria are met. Such
  86 criteria are the conditions, the signals, and the triggers. They are detailed
  87 in the next sections.
  88
  89 Conditions
  90 ''''''''''
  91
  92 When an activity has been completed, its outgoing transitions will be inspected
  93 to see if it is possible for the workflow instance to proceed through them and
  94 reach the next activities. When only a condition is defined (i.e. no signal or
  95 trigger is defined), the condition is evaluated by OpenERP, and if it evaluates
  96 to ``True``, the worklfow instance will go through.
  97
  98 By default, the ``condition`` attribute (i.e. the expression to be evaluated)
  99 is just "True", which will trivially evaluate to ``True``.
 100
 101 Actually, the condition can be several lines long, and the value of the last
 102 one will be used to test if the transition can be taken.
 103
 104 In the condition evaluation environment, several symbols are conveniently
 105 defined:
 106
 107 - The  database cursor (``cr``),
 108 - the user ID (``uid``), the record ID tied to the workflow instance (``id``),
 109 - the user ID wrapped in a list (``ids``),
 110 - the model name (``model``),
 111 - the model instance (``obj``),
 112 - all the model column names,
 113 - and all the record (the one obtained by browsing the provided ID) attributes.
 114
 115 Signals
 116 '''''''
 117
 118 In addition of a condition, a transition can specify a signal name. When such
 119 signal name is present, the transition will not be taken directly (even if the
 120 condition evaluates to true). Instead the transition will block, waiting to be
 121 woken up.
 122
 123 To wake up a transition with a defined signal name, the signal must be sent to
 124 the workflow. A common way to send a signal is to use a button in the web
 125 interface, using the ``<button/>`` element with the signal name as the ``name``
 126 attribute of the button.
 127
 128 .. note:: The condition is still evaluated when the signal is sent to the
 129     workflow instance.
 130
 131 Triggers
 132 ''''''''
 133
 134 With conditions that evaluate to false, transitions are not taken (and thus the
 135 activity it leads to will not be processed). Still, the workflow instance can
 136 get new chances to progress across that transition by providing so-called
 137 triggers. The idea is that when the condition fails, triggers are recorded in
 138 database. Later, it is possible to wake-up specifically the workflow instances
 139 that installed those triggers, offering them a new chance to evaluation their
 140 transition conditions. This mechnism makes it cheaper to wake-up workflow
 141 instances by targetting just a few of them (those that have installed the
 142 triggers) instead of all of them.
 143
 144 Triggers are recorded in database as record IDs (together with the model name)
 145 and refer to the workflow instance waiting for them. The transition definition
 146 can thus provide a Python expression (using the ``trigger_model`` attribute)
 147 that when evaluated will return the record IDs. Unlike the other expressions
 148 defined on the workflow, this one is evaluated with respect to a model that can
 149 be chosen on a per-transition basis with the ``trigger_expression`` attribute.
 150
 151 .. note:: Note that triggers are not re-installed whenever the transition is
 152     re-tried.
 153
 154 Activities
 155 ----------
 156
 157 While the transitions can be seen as the control structure of the workflows,
 158 activities are the place where everything happen, from changing record states
 159 to sending email.
 160
 161 Different kind of activities exist: ``Dummy``, ``Function``, ``Subflow``, and
 162 ``Stop all``; different kind of activities can do different and they are
 163 detailed below.
 164
 165 In addition to the activity kind, activies have some properties, detailed in
 166 the next sections.
 167
 168 Flow start and flow stop
 169 ''''''''''''''''''''''''
 170
 171 The ``flow_start`` attribute is a boolean value specifying if the activity
 172 starts the workflow. Multiple activities can have the ``flow_start`` attribute
 173 set to ``True`` and when instanciating a workflow for a record, OpenERP will
 174 simply process all of them, and try all their outgoing transitions afterwards.
 175
 176 The ``flow_stop`` attribute is also a boolean value, specifying if the activity
 177 ends the workflow. A workflow is considered to be completed when all its
 178 activities with the ``flow_stop`` attribute set to ``True`` are completed.
 179
 180 It is important for OpenERP to know when a workflow instance is completed: a
 181 workflow can have an activity that is actually another workflow (called a
 182 subflow) and that activity will be completed only when the subflow is
 183 completed.
 184
 185 Subflow
 186 '''''''
 187
 188 An activity can embed a complete workflow, called a subflow (the embedding
 189 workflow is called the parent workflow). The workflow to instanciate is
 190 specified by the ``subflow_id`` attribute.
 191
 192 .. note:: In the GUI, that attribute can not be set unless the kind of the
 193     activity is ``Subflow``.
 194
 195 The activity will be completed (and its outgoing transitions will be tried)
 196 when the subflow is completed (see the ``flow_stop`` attribute above to read
 197 about when a workflow is considered completed by OpenERP).
 198
 199 Sending a signal from a subflow
 200 '''''''''''''''''''''''''''''''
 201
 202 When a workflow is used (as a sublfow) in the activity of a (parent) workflow,
 203 the sublow can send a signal from its own activities to the parent by specifying a
 204 signal name in the ``signal_send`` attribute. OpenERP will process those
 205 activities normally and send to the parent workflow instance a signal with
 206 ``signal_send`` value prefixed with ``subflow.``.
 207
 208 In other words, it is possible to react and take transitions in the parent
 209 workflow as activities are executed in the sublow.