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. In their
  78 simplest form they just link activities from one to the others (as in the
  79 example above), and activities are processed as soon as the activities
  80 preceding them are completed.
  81
  82 But instead of running all activities in one fell swoop, it is also possible to
  83 block on transitions, going through them only when some criteria are met. Such
  84 criteria are the conditions, the signals, and the triggers. They are detailed
  85 in the next sections.
  86
  87 Conditions
  88 ''''''''''
  89
  90 When an activity has been completed, its outgoing transitions will be inspected
  91 to see if it is possible for the workflow instance to proceed through them and
  92 reach the next activities. When only a condition is defined (i.e. no signal or
  93 trigger is defined), the condition is evaluated by OpenERP, and if it evaluates
  94 to ``True``, the worklfow instance will go through.
  95
  96 By default, the ``condition`` attribute (i.e. the expression to be evaluated)
  97 is just "True", which will trivially evaluate to ``True``.
  98
  99 Actually, the condition can be several lines long, and the value of the last
 100 one will be used to test if the transition can be taken.
 101
 102 In the condition evaluation environment, several symbols are conveniently
 103 defined:
 104
 105 - The  database cursor (``cr``),
 106 - the user ID (``uid``), the record ID tied to the workflow instance (``id``),
 107 - the user ID wrapped in a list (``ids``),
 108 - the model name (``model``),
 109 - the model instance (``obj``),
 110 - all the model column names,
 111 - and all the record (the one obtained by browsing the provided ID) attributes.
 112
 113 Signals
 114 '''''''
 115
 116 Triggers
 117 ''''''''
 118
 119 When an activity is completed, the workflow engine will try to get across
 120 transitions departing from the completed activity, towards the next activities.
 121 To get across a transition, its associated condition should evaluate to True.
 122 If the condition evaluates to False, the transition is not taken (and thus the
 123 activity it leads to will not be processed). Still, the workflow instance can
 124 get new chances to progress across that transition by providing so-called
 125 triggers. The idea is that when the condition fails, triggers (actually just
 126 model name/record IDs pairs) are recorded in database. Later, it is possible to
 127 wake-up specifically the workflow instances that installed those triggers,
 128 offering them a new chance to evaluation their transition conditions. This
 129 mechnism makes it cheaper to wake-up workflow instances by targetting just a
 130 few of them (those that have installed the triggers) instead of all of them.
 131
 132 On each transition, in addition to a condition, records can be defined as a
 133 trigger. The records will be defined as triggers as the transition is tried
 134 withing a workflow, after the condition has failed. The actual records are
 135 stored as model name and record ids. The model name is defined by the
 136 trigger_model attribute of the transition while the record IDs are retrived by
 137 evaluating the trigger_expression (also defined on the transition).
 138
 139 - I think the triggers are never deleted from the database. They are: they are
 140   'on delete cascade' on both the workflow instance and the workitem.
 141
 142 - Are those triggers re-installed whenever the transition is tried ? Nope.
 143