From 0568f5c65384cdc70bae5d03f8932a5db6b97cbb Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Mon, 22 Jul 2013 17:17:40 +0200
Subject: [PATCH 01/17] [ADD] test_workflow: added some tests for the
 workflows.

bzr revid: vmt@openerp.com-20130722151740-mucw6i5vn38blh66
---
 .../tests/addons/test_workflow/__init__.py    |  3 +
 .../tests/addons/test_workflow/__openerp__.py | 15 ++++
 openerp/tests/addons/test_workflow/data.xml   | 86 +++++++++++++++++++
 openerp/tests/addons/test_workflow/models.py  | 37 ++++++++
 openerp/tests/addons/test_workflow/run.py     | 44 ++++++++++
 .../addons/test_workflow/tests/__init__.py    | 12 +++
 .../test_workflow/tests/test_workflow.py      | 62 +++++++++++++
 7 files changed, 259 insertions(+)
 create mode 100644 openerp/tests/addons/test_workflow/__init__.py
 create mode 100644 openerp/tests/addons/test_workflow/__openerp__.py
 create mode 100644 openerp/tests/addons/test_workflow/data.xml
 create mode 100644 openerp/tests/addons/test_workflow/models.py
 create mode 100755 openerp/tests/addons/test_workflow/run.py
 create mode 100644 openerp/tests/addons/test_workflow/tests/__init__.py
 create mode 100644 openerp/tests/addons/test_workflow/tests/test_workflow.py

diff --git a/openerp/tests/addons/test_workflow/__init__.py b/openerp/tests/addons/test_workflow/__init__.py
new file mode 100644
index 00000000000..fe4487156b1
--- /dev/null
+++ b/openerp/tests/addons/test_workflow/__init__.py
@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+import models
+# vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
diff --git a/openerp/tests/addons/test_workflow/__openerp__.py b/openerp/tests/addons/test_workflow/__openerp__.py
new file mode 100644
index 00000000000..1b846f9f227
--- /dev/null
+++ b/openerp/tests/addons/test_workflow/__openerp__.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+{
+    'name': 'test-workflow',
+    'version': '0.1',
+    'category': 'Tests',
+    'description': """A module to play with workflows.""",
+    'author': 'OpenERP SA',
+    'maintainer': 'OpenERP SA',
+    'website': 'http://www.openerp.com',
+    'depends': ['base'],
+    'data': ['data.xml'],
+    'installable': True,
+    'auto_install': False,
+}
+# vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
diff --git a/openerp/tests/addons/test_workflow/data.xml b/openerp/tests/addons/test_workflow/data.xml
new file mode 100644
index 00000000000..c50dfc03bf6
--- /dev/null
+++ b/openerp/tests/addons/test_workflow/data.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="utf-8"?>
+<openerp>
+    <data>
+
+        <record id="view_test_workflow_model" model="ir.ui.view">
+            <field name="name">Test workflow</field>
+            <field name="model">test.workflow.model</field>
+            <field name="arch" type="xml">
+                <form string="Test workflow">
+                          <button name="a-b" string="a-b" type="workflow" icon="gtk-ok" colspan="1"/>
+                          <label string="a-b"/>
+                          <button name="trigger" string="trigger" type="object" icon="gtk-ok" colspan="1"/>
+                          <label string="trigger"/>
+                </form>
+           </field>
+        </record>
+
+        <record id="action_test_workflow" model="ir.actions.act_window">
+            <field name="name">Test workflow</field>
+            <field name="type">ir.actions.act_window</field>
+            <field name="res_model">test.workflow.model</field>
+            <field name="view_type">form</field>
+            <field name="view_mode">tree,form</field>
+        </record>
+
+        <menuitem icon="STOCK_PREFERENCES" id="base.menu_tests" name="Tests" sequence="1000000"/>
+
+        <menuitem id="menu_test_workflow" parent="base.menu_tests" name="Test workflow"/>
+
+        <menuitem id="menu_test_workflow_leaf"
+            name="Test workflow"
+            action="action_test_workflow"
+            parent="menu_test_workflow"/>
+
+
+        <record id="test_workflow_trigger_1" model="test.workflow.trigger">
+        <!-- A single trigger record, with known ID 1 -->
+        </record>
+
+
+        <!-- A simple workflow:
+
+            a -signal-> b -trigger-> c
+
+        -->
+        <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="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">print_b()</field>
+        </record>
+        <record id="activity_c" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow"/>
+            <field name="flow_stop">True</field>
+            <field name="name">c</field>
+            <field name="kind">function</field>
+            <field name="action">print_c()</field>
+        </record>
+
+        <record id="trans_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_a"/>
+            <field name="act_to" ref="activity_b"/>
+            <field name="signal">a-b</field>
+        </record>
+        <record id="trans_b_c" model="workflow.transition">
+            <field name="act_from" ref="activity_b"/>
+            <field name="act_to" ref="activity_c"/>
+            <field name="condition">condition()</field>
+            <field name="trigger_model">test.workflow.trigger</field>
+            <field name="trigger_expr_id">[1]</field>
+        </record>
+    </data>
+</openerp>
diff --git a/openerp/tests/addons/test_workflow/models.py b/openerp/tests/addons/test_workflow/models.py
new file mode 100644
index 00000000000..7f79aeb1484
--- /dev/null
+++ b/openerp/tests/addons/test_workflow/models.py
@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+import openerp
+
+class m(openerp.osv.orm.Model):
+    """ A model for which we will define a worflow (see data.xml). """
+    _name = 'test.workflow.model'
+
+    def print_(self, cr, uid, ids, s, context=None):
+        print '  Running activity `%s` for record %s' % (s, ids)
+        return True
+
+    def print_a(self, cr, uid, ids, context=None):
+        return self.print_(cr, uid, ids, 'a', context)
+
+    def print_b(self, cr, uid, ids, context=None):
+        return self.print_(cr, uid, ids, 'b', context)
+
+    def print_c(self, cr, uid, ids, context=None):
+        return self.print_(cr, uid, ids, 'c', context)
+
+    def condition(self, cr, uid, ids, context=None):
+        m = self.pool['test.workflow.trigger']
+        for r in m.browse(cr, uid, [1], context=context):
+            if not r.value:
+                return False
+        return True
+
+    def trigger(self, cr, uid, context=None):
+        return openerp.workflow.trg_trigger(uid, 'test.workflow.trigger', 1, cr)
+
+class n(openerp.osv.orm.Model):
+    """ A model used for the trigger feature. """
+    _name = 'test.workflow.trigger'
+    _columns = { 'value': openerp.osv.fields.boolean('Value') }
+    _defaults = { 'value': False }
+
+# vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
diff --git a/openerp/tests/addons/test_workflow/run.py b/openerp/tests/addons/test_workflow/run.py
new file mode 100755
index 00000000000..dda955f9ce9
--- /dev/null
+++ b/openerp/tests/addons/test_workflow/run.py
@@ -0,0 +1,44 @@
+#! /usr/bin/env python2
+import os
+
+import openerp
+from openerp import SUPERUSER_ID
+
+DATABASE='t'
+
+def configure():
+    conf = openerp.tools.config
+    conf['addons_path'] = os.path.join(os.path.dirname(os.path.dirname(__file__))) + ",/home/thu/repos/web/trunk/addons"
+    conf['log_handler'] = [':CRITICAL']
+    openerp.modules.module.initialize_sys_path()
+    openerp.netsvc.init_logger()
+
+if __name__ == '__main__':
+    configure()
+
+    print '> Loading registry `%s`...' % DATABASE
+    registry = registry = openerp.registry(DATABASE)
+    cr = registry.db.cursor()
+    print '< Registry `%s` loaded.' % DATABASE
+
+    model = registry['test.workflow.model']
+    trigger = registry['test.workflow.trigger']
+
+    print '> Creating new record...'
+    i = model.create(cr, SUPERUSER_ID, {})
+    print '< Record created with ID %s' % i
+
+    print '> Calling signal `a-b`...'
+    model.signal_workflow(cr, SUPERUSER_ID, [i], 'a-b')
+    print '< Signal `a-b` called.'
+
+    print '> Triggering associated record...'
+    model.trigger(cr, SUPERUSER_ID, [i])
+    print '< Associated record triggered.'
+
+    print '> Triggering associated record (this time with the condition evaluating to True)...'
+    trigger.write(cr, SUPERUSER_ID, [1], {'value': True})
+    model.trigger(cr, SUPERUSER_ID)
+    print '< Associated record triggered.'
+
+    cr.close()
diff --git a/openerp/tests/addons/test_workflow/tests/__init__.py b/openerp/tests/addons/test_workflow/tests/__init__.py
new file mode 100644
index 00000000000..a09d09fe74a
--- /dev/null
+++ b/openerp/tests/addons/test_workflow/tests/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+from . import test_workflow
+
+fast_suite = [
+]
+
+checks = [
+    test_workflow,
+]
+
+# vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
diff --git a/openerp/tests/addons/test_workflow/tests/test_workflow.py b/openerp/tests/addons/test_workflow/tests/test_workflow.py
new file mode 100644
index 00000000000..60ace7ee269
--- /dev/null
+++ b/openerp/tests/addons/test_workflow/tests/test_workflow.py
@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+import openerp
+from openerp import SUPERUSER_ID
+from openerp.tests import common
+
+
+class test_workflows(common.TransactionCase):
+
+    def check_activities(self, model_name, i, names):
+        """ Check that the record i has workitems in the given activity names.
+        """
+        instance = self.registry('workflow.instance')
+        workitem = self.registry('workflow.workitem')
+
+        # Given the workflow instance associated to the record ...
+        instance_id = instance.search(
+            self.cr, SUPERUSER_ID,
+            [('res_type', '=', model_name), ('res_id', '=', i)])
+        self.assertTrue( instance_id, 'A workflow instance is expected.')
+
+        # ... get all its workitems ...
+        workitem_ids = workitem.search(
+            self.cr, SUPERUSER_ID,
+            [('inst_id', '=', instance_id[0])])
+        self.assertTrue(
+            workitem_ids,
+            'The workflow instance should have workitems.')
+
+        # ... and check the activity the are in against the provided names.
+        workitem_records = workitem.browse(
+            self.cr, SUPERUSER_ID, workitem_ids)
+        self.assertEqual(
+            sorted([item.act_id.name for item in workitem_records]),
+            sorted(names))
+
+    def test_workflow(self):
+        model = self.registry('test.workflow.model')
+        trigger = self.registry('test.workflow.trigger')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+
+        # a -> b is just a signal.
+        model.signal_workflow(self.cr, SUPERUSER_ID, [i], 'a-b')
+        self.check_activities(model._name, i, ['b'])
+
+        # b -> c is a trigger (which is False),
+        # so we remain in the b activity.
+        model.trigger(self.cr, SUPERUSER_ID, [i])
+        self.check_activities(model._name, i, ['b'])
+
+        # b -> c is a trigger (which is set to True).
+        # so we go in c when the trigger is called.
+        trigger.write(self.cr, SUPERUSER_ID, [1], {'value': True})
+        model.trigger(self.cr, SUPERUSER_ID)
+        self.check_activities(model._name, i, ['c'])
+
+        self.assertEqual(
+            True,
+            True)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])

From 9357ed959a8b9228264f60377a877ae5a70629d6 Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Tue, 23 Jul 2013 13:21:47 +0200
Subject: [PATCH 02/17] [DOC] workflows: started to write some workflow
 documentation.

bzr revid: vmt@openerp.com-20130723112147-wje0mt5e1a59zj68
---
 doc/index.rst     |   1 +
 doc/workflows.rst | 104 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 doc/workflows.rst

diff --git a/doc/index.rst b/doc/index.rst
index e641de1da67..b5ac49f6a8f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -14,6 +14,7 @@ OpenERP Server
    02_architecture
    03_module_dev
    04_security
+   workflows
    05_test_framework
    06_misc
    deployment-gunicorn
diff --git a/doc/workflows.rst b/doc/workflows.rst
new file mode 100644
index 00000000000..6e7308d485d
--- /dev/null
+++ b/doc/workflows.rst
@@ -0,0 +1,104 @@
+.. _workflows:
+
+Workflows
+=========
+
+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 OpenERP server, such as
+  changing the state of some records, or sending mails.
+
+- Transitions control how the workflow will go from activities to activities.
+
+When defining a workflow, one can attach conditions, signals, and triggers to
+transitions, so that the behavior of the workflow can depend on user actions
+(such as clicking on a button), changes to records, or arbitrary Python code.
+
+XML definition
+--------------
+
+Defining a workflow with data files is straightforward: a record "workflow" is
+needed together with records for the activities and the transitions. For
+instance here is a simple sequence of two activities defined in 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 through the ``osv`` attribute on the ``workflow`` model). 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 ``flow_start`` attribute set to True so that OpenERP
+knows where to start the workflow when 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
+created by other means, such as from some module Python code.)
+
+When the workflow is instanciated, it will start by the "a" activity. That
+activity is of kind ``function`` which means the action ``print_a()`` is a
+method to be called on the ``test.workflow`` model (the usual ``cr, uid, ids,
+context`` arguments are passed for you).
+
+The transition between "a" and "b" does not specify any conditions. This means
+the workflow instance will immediately progress from "a" to "b" (after "a" has
+been processed), and thus elso process the "b" activity.
+
+Conditions
+----------
+
+Triggers
+--------
+
+When an activity is completed, the workflow engine will try to get across
+transitions departing from the completed activity, towards the next activities.
+To get across a transition, its associated condition should evaluate to True.
+If the condition evaluates to False, the transition is not taken (and thus the
+activity it leads to will not be processed). 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 fails, triggers (actually just
+model name/record IDs pairs) are recorded in database. Later, it is possible to
+wake-up specifically the workflow instances that installed those triggers,
+offering them a new chance to evaluation their transition conditions. This
+mechnism 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.
+
+On each transition, in addition to a condition, records can be defined as a
+trigger. The records will be defined as triggers as the transition is tried
+withing a workflow, after the condition has failed. The actual records are
+stored as model name and record ids. The model name is defined by the
+trigger_model attribute of the transition while the record IDs are retrived by
+evaluating the trigger_expression (also defined on the transition).
+
+- I think the triggers are never deleted from the database. They are: they are
+  'on delete cascade' on both the workflow instance and the workitem.
+
+- Are those triggers re-installed whenever the transition is tried ? Nope.
+

From b5068764adb294f3d914d46751a3cbe0bfc55dd2 Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Tue, 23 Jul 2013 14:51:43 +0200
Subject: [PATCH 03/17] [DOC] workflows: added Conditions section.

bzr revid: vmt@openerp.com-20130723125143-20n8ukewixxbkbt4
---
 doc/workflows.rst | 49 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 44 insertions(+), 5 deletions(-)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index 6e7308d485d..939433440a2 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -15,8 +15,8 @@ When defining a workflow, one can attach conditions, signals, and triggers to
 transitions, so that the behavior of the workflow can depend on user actions
 (such as clicking on a button), changes to records, or arbitrary Python code.
 
-XML definition
---------------
+Basics
+------
 
 Defining a workflow with data files is straightforward: a record "workflow" is
 needed together with records for the activities and the transitions. For
@@ -69,13 +69,52 @@ context`` arguments are passed for you).
 
 The transition between "a" and "b" does not specify any conditions. This means
 the workflow instance will immediately progress from "a" to "b" (after "a" has
-been processed), and thus elso process the "b" activity.
+been processed), and thus also process the "b" activity.
+
+Transitions
+-----------
+
+Transitions provide the control structures to orchestrate a workflow. In their
+simplest form they just link activities from one to the others (as in the
+example above), and activities are processed as soon as the activities
+preceding them are completed.
+
+But instead of running all activities in one fell swoop, it is also possible to
+block on transitions, going through them only when some criteria are met. Such
+criteria are the conditions, the signals, and the triggers. They are detailed
+in the next sections.
 
 Conditions
-----------
+''''''''''
+
+When an activity has been completed, its outgoing transitions will be inspected
+to see if 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 OpenERP, and if it evaluates
+to ``True``, the worklfow instance will go through.
+
+By default, the ``condition`` attribute (i.e. the expression to be evaluated)
+is just "True", which will trivially evaluate to ``True``.
+
+Actually, the condition can be several lines long, and the value of the last
+one will be used to test if the transition can be taken.
+
+In the condition evaluation environment, several symbols are conveniently
+defined:
+
+- The  database cursor (``cr``),
+- the user ID (``uid``), the record ID tied to the workflow instance (``id``),
+- the user ID wrapped in a list (``ids``),
+- the model name (``model``),
+- the model instance (``obj``),
+- all the model column names,
+- and all the record (the one obtained by browsing the provided ID) attributes.
+
+Signals
+'''''''
 
 Triggers
---------
+''''''''
 
 When an activity is completed, the workflow engine will try to get across
 transitions departing from the completed activity, towards the next activities.

From 2397c1a98ba6b93dc013d6d338a50ec49bacd47f Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Tue, 23 Jul 2013 14:52:42 +0200
Subject: [PATCH 04/17] [IMP] workflows: added docstring, some variable
 renaming (to wkf_expr).

bzr revid: vmt@openerp.com-20130723125242-mpzpjfbnyrmx3bzt
---
 openerp/workflow/wkf_expr.py | 74 +++++++++++++++++++++++++-----------
 1 file changed, 52 insertions(+), 22 deletions(-)

diff --git a/openerp/workflow/wkf_expr.py b/openerp/workflow/wkf_expr.py
index b43fa83e3de..0b83195aec2 100644
--- a/openerp/workflow/wkf_expr.py
+++ b/openerp/workflow/wkf_expr.py
@@ -19,62 +19,92 @@
 #
 ##############################################################################
 
+"""
+Evaluate workflow code found in activity actions and transition conditions.
+"""
+
 import openerp
 from openerp.tools.safe_eval import safe_eval as eval
 
 class Env(dict):
-    def __init__(self, cr, uid, model, ids):
+    """
+    Dictionary class used as an environment to evaluate workflow code (such as
+    the condition on transitions).
+
+    This environment provides sybmols for cr, uid, id, model name, model
+    instance, column names, and all the record (the one obtained by browsing
+    the provided ID) attributes.
+    """
+    def __init__(self, cr, uid, model, id):
         self.cr = cr
         self.uid = uid
         self.model = model
-        self.ids = ids
+        self.id = id
+        self.ids = [id]
         self.obj = openerp.registry(cr.dbname)[model]
         self.columns = self.obj._columns.keys() + self.obj._inherit_fields.keys()
 
     def __getitem__(self, key):
         if (key in self.columns) or (key in dir(self.obj)):
-            res = self.obj.browse(self.cr, self.uid, self.ids[0])
+            res = self.obj.browse(self.cr, self.uid, self.id)
             return res[key]
         else:
             return super(Env, self).__getitem__(key)
 
-def _eval_expr(cr, ident, workitem, action):
-    ret=False
-    assert action, 'You used a NULL action in a workflow, use dummy node instead.'
-    for line in action.split('\n'):
+def _eval_expr(cr, ident, workitem, lines):
+    """
+    Evaluate each line of ``lines`` with the ``Env`` environment, returning
+    the value of the last line.
+    """
+    assert lines, 'You used a NULL action in a workflow, use dummy node instead.'
+    uid, model, id = ident
+    result = False
+    for line in lines.split('\n'):
         line = line.strip()
         if not line:
             continue
-        uid=ident[0]
-        model=ident[1]
-        ids=[ident[2]]
-        if line =='True':
-            ret=True
-        elif line =='False':
-            ret=False
+        if line == 'True':
+            result = True
+        elif line == 'False':
+            result = False
         else:
-            env = Env(cr, uid, model, ids)
-            ret = eval(line, env, nocopy=True)
-    return ret
+            env = Env(cr, uid, model, id)
+            result = eval(line, env, nocopy=True)
+    return result
 
 def execute_action(cr, ident, workitem, activity):
-    obj = openerp.registry(cr.dbname)['ir.actions.server']
-    ctx = {'active_model':ident[1], 'active_id':ident[2], 'active_ids':[ident[2]]}
-    result = obj.run(cr, ident[0], [activity['action_id']], ctx)
+    """
+    Evaluate the ir.actions.server action specified in the activity.
+    """
+    uid, model, id = ident
+    ir_actions_server = openerp.registry(cr.dbname)['ir.actions.server']
+    context = { 'active_model': model, 'active_id': id, 'active_ids': [id] }
+    result = ir_actions_server.run(cr, uid, [activity['action_id']], context)
     return result
 
 def execute(cr, ident, workitem, activity):
+    """
+    Evaluate the action specified in the activity.
+    """
     return _eval_expr(cr, ident, workitem, activity['action'])
 
 def check(cr, workitem, ident, transition, signal):
+    """
+    Test if a transition can be taken. The transition can be taken if:
+    
+    - the signal name matches,
+    - the uid is SUPERUSER_ID or the user groups contains the transition's
+      group,
+    - the condition evaluates to a truish value.
+    """
     if transition['signal'] and signal != transition['signal']:
         return False
 
     uid = ident[0]
-    if transition['group_id'] and uid != 1:
+    if uid != openerp.SUPERUSER_ID and transition['groups_id']:
         registry = openerp.registry(cr.dbname)
         user_groups = registry['res.users'].read(cr, uid, [uid], ['groups_id'])[0]['groups_id']
-        if not transition['group_id'] in user_groups:
+        if transition['group_id'] not in user_groups:
             return False
 
     return _eval_expr(cr, ident, workitem, transition['condition'])

From 3f9fb6eacc5468c62b9017fd2af6e259e16b7c8f Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Tue, 23 Jul 2013 15:27:51 +0200
Subject: [PATCH 05/17] [DOC] workflows: added Signals section.

bzr revid: vmt@openerp.com-20130723132751-lwn5r6y1m51jhj9o
---
 doc/workflows.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index 939433440a2..19b845f7f98 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -113,6 +113,19 @@ defined:
 Signals
 '''''''
 
+In addition of a condition, a transition can specify a signal name. When such
+signal name is present, the transition will not be taken directly (even if the
+condition evaluates to true). Instead the transition will block, waiting to be
+woken up.
+
+To wake up a transition with a defined signal name, the signal must be sent to
+the workflow. A common way to send a signal is to use a button in the web
+interface, using the ``<button/>`` element with the signal name as the ``name``
+attribute of the button.
+
+.. note:: The condition is still evaluated when the signal is sent to the
+    workflow instance.
+
 Triggers
 ''''''''
 

From 8501e89735f826332d3cd4fbeb543af637405e1b Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Tue, 23 Jul 2013 17:12:49 +0200
Subject: [PATCH 06/17] [DOC] workflows: improved Triggers section.

bzr revid: vmt@openerp.com-20130723151249-oa18owwzg82ea79t
---
 doc/workflows.rst | 39 ++++++++++++++++++---------------------
 1 file changed, 18 insertions(+), 21 deletions(-)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index 19b845f7f98..928cd49fbcc 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -74,7 +74,9 @@ been processed), and thus also process the "b" activity.
 Transitions
 -----------
 
-Transitions provide the control structures to orchestrate a workflow. In their
+Transitions provide the control structures to orchestrate a workflow. When an
+activity is completed, the workflow engine will try to get across transitions
+departing from the completed activity, towards the next activities.  In their
 simplest form they just link activities from one to the others (as in the
 example above), and activities are processed as soon as the activities
 preceding them are completed.
@@ -129,28 +131,23 @@ attribute of the button.
 Triggers
 ''''''''
 
-When an activity is completed, the workflow engine will try to get across
-transitions departing from the completed activity, towards the next activities.
-To get across a transition, its associated condition should evaluate to True.
-If the condition evaluates to False, the transition is not taken (and thus the
+With conditions that evaluate to false, transitions are not taken (and thus the
 activity it leads to will not be processed). 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 fails, triggers (actually just
-model name/record IDs pairs) are recorded in database. Later, it is possible to
-wake-up specifically the workflow instances that installed those triggers,
-offering them a new chance to evaluation their transition conditions. This
-mechnism 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. The idea is that when the condition fails, triggers are recorded in
+database. Later, it is possible to wake-up specifically the workflow instances
+that installed those triggers, offering them a new chance to evaluation their
+transition conditions. This mechnism 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.
 
-On each transition, in addition to a condition, records can be defined as a
-trigger. The records will be defined as triggers as the transition is tried
-withing a workflow, after the condition has failed. The actual records are
-stored as model name and record ids. The model name is defined by the
-trigger_model attribute of the transition while the record IDs are retrived by
-evaluating the trigger_expression (also defined on the transition).
+Triggers are recorded in database as record IDs (together with the model name)
+and refer to the workflow instance waiting for them. The transition definition
+can thus provide a Python expression (using the ``trigger_model`` attribute)
+that when evaluated will return the record IDs. Unlike the other expressions
+defined on the workflow, this one is evaluated with respect to a model that can
+be chosen on a per-transition basis with the ``trigger_expression`` attribute.
 
-- I think the triggers are never deleted from the database. They are: they are
-  'on delete cascade' on both the workflow instance and the workitem.
-
-- Are those triggers re-installed whenever the transition is tried ? Nope.
+.. note:: Note that triggers are not re-installed whenever the transition is
+    re-tried.
 

From 86c544d2024495d6c533a7263245fda7446bdcaf Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Wed, 24 Jul 2013 14:37:41 +0200
Subject: [PATCH 07/17] [DOC] workflows: added Flow start and flow stop
 section.

bzr revid: vmt@openerp.com-20130724123741-jf3l9w3flxf7ty4k
---
 doc/workflows.rst | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index 928cd49fbcc..d631fdfb265 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -151,3 +151,33 @@ be chosen on a per-transition basis with the ``trigger_expression`` attribute.
 .. note:: Note that triggers are not re-installed whenever the transition is
     re-tried.
 
+Activities
+----------
+
+While the transitions can be seen as the control structure of the workflows,
+activities are the place where everything happen, from changing record states
+to sending email.
+
+Different kind of activities exist: ``Dummy``, ``Function``, ``Subflow``, and
+``Stop all``; different kind of activities can do different and they are
+detailed below. 
+
+In addition to the activity kind, activies have some properties, detailed in
+the next sections.
+
+Flow start and flow stop
+''''''''''''''''''''''''
+
+The ``flow_start`` attribute is a boolean value specifying if the activity
+starts the workflow. Multiple activities can have the ``flow_start`` attribute
+set to ``True`` and when instanciating a workflow for a record, OpenERP will
+simply process all of them, and try all their outgoing transitions afterwards.
+
+The ``flow_stop`` attribute is also a boolean value, specifying if the activity
+ends the workflow. A workflow is considered to be completed when all its
+activities with the ``flow_stop`` attribute set to ``True`` are completed.
+
+It is important for OpenERP to know when a workflow instance is completed: a
+workflow can have an activity that is actually another workflow (called a
+subflow) and that activity will be completed only when the subflow is
+completed.

From eff32c650c5c69d64ad21bc4a7a003fce9f8e1ac Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Wed, 24 Jul 2013 15:51:02 +0200
Subject: [PATCH 08/17] [DOC] workflows: added Subflow section.

bzr revid: vmt@openerp.com-20130724135102-2zzaoqpjpebim59k
---
 doc/workflows.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index d631fdfb265..521ca0bb6d3 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -181,3 +181,29 @@ It is important for OpenERP to know when a workflow instance is completed: a
 workflow can have an activity that is actually another workflow (called a
 subflow) and that activity will be completed only 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 the ``subflow_id`` attribute.
+
+.. note:: In the GUI, that attribute can not be set unless the kind of the
+    activity is ``Subflow``.
+
+The activity will be completed (and its outgoing transitions will be tried)
+when the subflow is completed (see the ``flow_stop`` attribute above to read
+about when a workflow is considered completed by OpenERP).
+
+Sending a signal from a subflow
+'''''''''''''''''''''''''''''''
+
+When a workflow is used (as a sublfow) in the activity of a (parent) workflow,
+the sublow can send a signal from its own activities to the parent by specifying a
+signal name in the ``signal_send`` attribute. OpenERP will process those
+activities normally and send to the parent workflow instance a signal with
+``signal_send`` value prefixed with ``subflow.``.
+
+In other words, it is possible to react and take transitions in the parent
+workflow as activities are executed in the sublow.

From 33ab08b8b37aa859eae55b334e2d959c2457d3c4 Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Wed, 24 Jul 2013 17:25:18 +0200
Subject: [PATCH 09/17] [DOC] workflows: added remaining sections for the
 Activities.

bzr revid: vmt@openerp.com-20130724152518-gab0fa44t8a81u30
---
 doc/workflows.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index 521ca0bb6d3..a1165b6f5d2 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -151,6 +151,14 @@ be chosen on a per-transition basis with the ``trigger_expression`` attribute.
 .. note:: Note that triggers are not re-installed whenever the transition is
     re-tried.
 
+Splitting and joining transitions
+'''''''''''''''''''''''''''''''''
+
+When multiple transitions leave the same activity, or lead to the same
+activity, OpenERP provides some control about which transitions will be
+crossed, or how the reached activity will be processed. The ``split_mode`` and
+``join_mode`` attributes on the activity are used for such control.
+
 Activities
 ----------
 
@@ -207,3 +215,64 @@ activities normally and send to the parent workflow instance a signal with
 
 In other words, it is possible to react and take 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 ``action_id``
+attribute.
+
+Python action
+'''''''''''''
+
+An activity can run some Python code, provided through the ``action``
+attribute. See the section about transition conditions to read about the
+evaluation environment.
+
+Split mode
+''''''''''
+
+After an activity has been processed, its outgoing transitions will be tried.
+Normally, if a transition can be taken, OpenERP will do it and proceed to the
+activity the transition leads to.
+
+Actually, when more than a single transition is leaving an activity, OpenERP
+can proceed, or not, depending on the other transitions. That is, the condition
+on the transitions can be combined together, and the combined result will
+instruct OpenERP to cross zero, one, or all the transitions. The way they are
+combined is controlled by the ``split_mode`` attribute.
+
+There are indeed three modes to decide how to combine the transition
+conditions, ``XOR``, ``OR``, and ``AND``.
+
+``XOR``
+    When the transitions are combined with a ``XOR`` split mode, as soon as a
+    transition with a condition that evaluates to true is found, the
+    transition is taken and the other will not be tried.
+
+``OR``
+    With an ``OR`` mode, all the transitions with a condition that evaluates to
+    true are taken. The remaining transitions will not be tried later.
+
+``AND``
+   With an ``AND`` mode, OpenERP will wait for all transition conditions to
+   evaluate to true, then cross all the transitions at the same time.
+
+Join mode
+'''''''''
+
+Just as departing transition conditions can be combined together to decide
+whether they can be taken or not, arriving transitions can be combined together
+to decide if an activity must be run. The attribute to control that behavior is
+called ``join_mode``.
+
+The join mode is a bit simpler than the split mode: only two modes are
+provided, ``XOR`` and ``AND``.
+
+``XOR``
+    An activity with a ``XOR`` join mode will be run as soon as a transition is
+    crossed to arrive at the activity.
+
+``AND``
+   With an ``AND`` mode, the activity will wait for all its incoming
+   transitions to be crossed before being run.

From b7f02c329e05343c5e4bfa3a35d9bb81ffcff8cc Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Thu, 25 Jul 2013 11:42:19 +0200
Subject: [PATCH 10/17] [DOC] workflows: added Kinds section.

bzr revid: vmt@openerp.com-20130725094219-tintybvpdl5izdca
---
 doc/workflows.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index a1165b6f5d2..293b2c347c0 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -276,3 +276,32 @@ provided, ``XOR`` and ``AND``.
 ``AND``
    With an ``AND`` mode, the activity will wait for all its incoming
    transitions to be crossed before being run.
+
+Kinds
+'''''
+
+Activities can be of different kinds: ``dummy``, ``function``, ``subflow``, or
+``stopall``. The kind defines what type of work an activity can do.
+
+Dummy
+    The ``dummy`` kind is for activities that do nothing (i.e. they act as hubs
+    to gather/dispatch transitions), or for activities that only call a Server
+    Action.
+
+Function
+    The ``function`` kind is for activities that only need to run some Python
+    code, and possibly a Server Action.
+
+Stop all
+    The ``stopall`` kind is for activities that will completely halt the
+    workflow instance. In addition they can also run some Python code.
+
+Subflow
+    When the kind of the activity is  ``subflow``, the activity will run
+    another workflow. When the sub-workflow is completed, the activity will also be
+    considered completed.
+
+    Normally the sub-workflow is instanciated for the same record as the parent
+    workflow. It is possible to change that default behavior by providing
+    Python code that has to return a record ID for which a workflow has been
+    instanciated.

From ae01b6ab21c3ab26aab135087cf94d80a660c6c2 Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Thu, 25 Jul 2013 11:42:46 +0200
Subject: [PATCH 11/17] [ADD] workflows: added some tests.

bzr revid: vmt@openerp.com-20130725094246-4v2p0sgzocnt5vwf
---
 openerp/tests/addons/test_workflow/data.xml   | 84 ++++++++++++++++++-
 openerp/tests/addons/test_workflow/models.py  | 19 ++++-
 .../test_workflow/tests/test_workflow.py      | 43 ++++++++++
 3 files changed, 144 insertions(+), 2 deletions(-)

diff --git a/openerp/tests/addons/test_workflow/data.xml b/openerp/tests/addons/test_workflow/data.xml
index c50dfc03bf6..a07451e2f42 100644
--- a/openerp/tests/addons/test_workflow/data.xml
+++ b/openerp/tests/addons/test_workflow/data.xml
@@ -37,7 +37,6 @@
         <!-- A single trigger record, with known ID 1 -->
         </record>
 
-
         <!-- A simple workflow:
 
             a -signal-> b -trigger-> c
@@ -82,5 +81,88 @@
             <field name="trigger_model">test.workflow.trigger</field>
             <field name="trigger_expr_id">[1]</field>
         </record>
+
+        <!-- Workflow A (a single activity):
+
+            a
+
+        -->
+        <record id="test_workflow_a" model="workflow">
+            <field name="name">test.workflow.a</field>
+            <field name="osv">test.workflow.model.a</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_a_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_a"/>
+            <field name="flow_start">True</field>
+            <field name="flow_stop">True</field>
+            <field name="name">a</field>
+            <field name="kind">dummy</field>
+        </record>
+
+        <!-- Workflow B (a single activity):
+
+            a
+
+        The function is run when the record is created.
+
+        -->
+        <record id="test_workflow_b" model="workflow">
+            <field name="name">test.workflow.b</field>
+            <field name="osv">test.workflow.model.b</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_b_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_b"/>
+            <field name="flow_start">True</field>
+            <field name="flow_stop">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+        </record>
+
+        <!-- Workflow C (a single activity):
+
+            a
+
+        The function is not run when the kind is dummy and no action_id is provided.
+        -->
+        <record id="test_workflow_c" model="workflow">
+            <field name="name">test.workflow.c</field>
+            <field name="osv">test.workflow.model.c</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_c_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_c"/>
+            <field name="flow_start">True</field>
+            <field name="flow_stop">True</field>
+            <field name="name">a</field>
+            <field name="kind">dummy</field>
+            <field name="action">write({'value': 1})</field>
+        </record>
+
+        <!-- Workflow D (a single activity):
+
+            a
+
+        The function is run when the kind is stopall and no action_id is provided.
+        -->
+        <record id="test_workflow_d" model="workflow">
+            <field name="name">test.workflow.d</field>
+            <field name="osv">test.workflow.model.d</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_d_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_d"/>
+            <field name="flow_start">True</field>
+            <field name="flow_stop">True</field>
+            <field name="name">a</field>
+            <field name="kind">stopall</field>
+            <field name="action">write({'value': 1})</field>
+        </record>
     </data>
 </openerp>
diff --git a/openerp/tests/addons/test_workflow/models.py b/openerp/tests/addons/test_workflow/models.py
index 7f79aeb1484..b1df8e662d3 100644
--- a/openerp/tests/addons/test_workflow/models.py
+++ b/openerp/tests/addons/test_workflow/models.py
@@ -2,7 +2,7 @@
 import openerp
 
 class m(openerp.osv.orm.Model):
-    """ A model for which we will define a worflow (see data.xml). """
+    """ A model for which we will define a workflow (see data.xml). """
     _name = 'test.workflow.model'
 
     def print_(self, cr, uid, ids, s, context=None):
@@ -34,4 +34,21 @@ class n(openerp.osv.orm.Model):
     _columns = { 'value': openerp.osv.fields.boolean('Value') }
     _defaults = { 'value': False }
 
+class a(openerp.osv.orm.Model):
+    _name = 'test.workflow.model.a'
+    _columns = { 'value': openerp.osv.fields.integer('Value') }
+    _defaults = { 'value': 0 }
+
+class b(openerp.osv.orm.Model):
+    _name = 'test.workflow.model.b'
+    _inherit = 'test.workflow.model.a'
+
+class c(openerp.osv.orm.Model):
+    _name = 'test.workflow.model.c'
+    _inherit = 'test.workflow.model.a'
+
+class d(openerp.osv.orm.Model):
+    _name = 'test.workflow.model.d'
+    _inherit = 'test.workflow.model.a'
+
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
diff --git a/openerp/tests/addons/test_workflow/tests/test_workflow.py b/openerp/tests/addons/test_workflow/tests/test_workflow.py
index 60ace7ee269..c09511dc168 100644
--- a/openerp/tests/addons/test_workflow/tests/test_workflow.py
+++ b/openerp/tests/addons/test_workflow/tests/test_workflow.py
@@ -33,6 +33,13 @@ class test_workflows(common.TransactionCase):
             sorted([item.act_id.name for item in workitem_records]),
             sorted(names))
 
+    def check_value(self, model_name, i, value):
+        """ Check that the record i has the given value.
+        """
+        model = self.registry(model_name)
+        record = model.read(self.cr, SUPERUSER_ID, [i], ['value'])[0]
+        self.assertEqual(record['value'], value)
+
     def test_workflow(self):
         model = self.registry('test.workflow.model')
         trigger = self.registry('test.workflow.trigger')
@@ -60,3 +67,39 @@ class test_workflows(common.TransactionCase):
             True)
 
         model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_a(self):
+        model = self.registry('test.workflow.model.a')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+        self.check_value(model._name, i, 0)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_b(self):
+        model = self.registry('test.workflow.model.b')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+        self.check_value(model._name, i, 1)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_c(self):
+        model = self.registry('test.workflow.model.c')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+        self.check_value(model._name, i, 0)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_d(self):
+        model = self.registry('test.workflow.model.d')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+        self.check_value(model._name, i, 1)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])

From 64ddf5f26422dfef9c545cc74e6db975d4a2eb50 Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Thu, 25 Jul 2013 12:43:27 +0200
Subject: [PATCH 12/17] [ADD] workflows: more tests.

bzr revid: vmt@openerp.com-20130725104327-l7onjhipi6fdnrj6
---
 openerp/tests/addons/test_workflow/data.xml   | 65 +++++++++++++++++++
 openerp/tests/addons/test_workflow/models.py  | 13 ++++
 .../test_workflow/tests/test_workflow.py      | 22 +++++++
 3 files changed, 100 insertions(+)

diff --git a/openerp/tests/addons/test_workflow/data.xml b/openerp/tests/addons/test_workflow/data.xml
index a07451e2f42..c6f542879a0 100644
--- a/openerp/tests/addons/test_workflow/data.xml
+++ b/openerp/tests/addons/test_workflow/data.xml
@@ -164,5 +164,70 @@
             <field name="kind">stopall</field>
             <field name="action">write({'value': 1})</field>
         </record>
+
+        <!-- Workflow E:
+
+            a -True-> b
+
+        Both activities are run when the workflow is instanciated.
+        -->
+        <record id="test_workflow_e" model="workflow">
+            <field name="name">test.workflow.e</field>
+            <field name="osv">test.workflow.model.e</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_e_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_e"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+        </record>
+        <record id="activity_e_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_e"/>
+            <field name="flow_stop">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+
+        <record id="trans_e_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_e_a"/>
+            <field name="act_to" ref="activity_e_b"/>
+        </record>
+
+        <!-- Workflow F:
+
+            a -signal-> b
+
+        Same as E but with a signal on the transition.
+        -->
+        <record id="test_workflow_f" model="workflow">
+            <field name="name">test.workflow.f</field>
+            <field name="osv">test.workflow.model.f</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_f_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_f"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+        </record>
+        <record id="activity_f_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_f"/>
+            <field name="flow_stop">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+
+        <record id="trans_f_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_f_a"/>
+            <field name="act_to" ref="activity_f_b"/>
+            <field name="signal">a-b</field>
+        </record>
     </data>
 </openerp>
diff --git a/openerp/tests/addons/test_workflow/models.py b/openerp/tests/addons/test_workflow/models.py
index b1df8e662d3..84789cc9b69 100644
--- a/openerp/tests/addons/test_workflow/models.py
+++ b/openerp/tests/addons/test_workflow/models.py
@@ -51,4 +51,17 @@ class d(openerp.osv.orm.Model):
     _name = 'test.workflow.model.d'
     _inherit = 'test.workflow.model.a'
 
+class e(openerp.osv.orm.Model):
+    _name = 'test.workflow.model.e'
+    _inherit = 'test.workflow.model.a'
+
+for name in 'bcdef':
+    type(
+        name,
+        (openerp.osv.orm.Model,),
+        {
+            '_name': 'test.workflow.model.%s' % name,
+            '_inherit': 'test.workflow.model.a',
+        })
+
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
diff --git a/openerp/tests/addons/test_workflow/tests/test_workflow.py b/openerp/tests/addons/test_workflow/tests/test_workflow.py
index c09511dc168..d55657f6a6a 100644
--- a/openerp/tests/addons/test_workflow/tests/test_workflow.py
+++ b/openerp/tests/addons/test_workflow/tests/test_workflow.py
@@ -103,3 +103,25 @@ class test_workflows(common.TransactionCase):
         self.check_value(model._name, i, 1)
 
         model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_e(self):
+        model = self.registry('test.workflow.model.e')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['b'])
+        self.check_value(model._name, i, 2)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_f(self):
+        model = self.registry('test.workflow.model.f')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+        self.check_value(model._name, i, 1)
+
+        model.signal_workflow(self.cr, SUPERUSER_ID, [i], 'a-b')
+        self.check_activities(model._name, i, ['b'])
+        self.check_value(model._name, i, 2)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])

From 68ff38763ab40845e15b4a1305d8dc592b7b9b8b Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Thu, 25 Jul 2013 16:30:56 +0200
Subject: [PATCH 13/17] [ADD] workflows: some split_mode tests.

I am not sure if the Workflow K is determinist though
so it could maybe end up in activity c instead of b
(and thus fail the tests).

bzr revid: vmt@openerp.com-20130725143056-p6oic1m9jjke9j8r
---
 openerp/tests/addons/test_workflow/data.xml   | 216 ++++++++++++++++++
 openerp/tests/addons/test_workflow/models.py  |   2 +-
 .../test_workflow/tests/test_workflow.py      |  45 ++++
 3 files changed, 262 insertions(+), 1 deletion(-)

diff --git a/openerp/tests/addons/test_workflow/data.xml b/openerp/tests/addons/test_workflow/data.xml
index c6f542879a0..b9f1e367000 100644
--- a/openerp/tests/addons/test_workflow/data.xml
+++ b/openerp/tests/addons/test_workflow/data.xml
@@ -229,5 +229,221 @@
             <field name="act_to" ref="activity_f_b"/>
             <field name="signal">a-b</field>
         </record>
+
+        <!-- Workflow G:
+
+            a -False-> b
+
+        -->
+        <record id="test_workflow_g" model="workflow">
+            <field name="name">test.workflow.g</field>
+            <field name="osv">test.workflow.model.g</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_g_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_g"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+        </record>
+        <record id="activity_g_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_g"/>
+            <field name="flow_stop">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+
+        <record id="trans_g_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_g_a"/>
+            <field name="act_to" ref="activity_g_b"/>
+            <field name="condition">False</field>
+        </record>
+
+        <!-- Workflow H:
+
+            a or  -> b { value: 2 } 
+                 `-> c { value: 2 }
+
+        Whether the action of b or c is exectued last is non-deterministic.
+
+        -->
+        <record id="test_workflow_h" model="workflow">
+            <field name="name">test.workflow.h</field>
+            <field name="osv">test.workflow.model.h</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_h_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_h"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+            <field name="split_mode">OR</field>
+        </record>
+        <record id="activity_h_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_h"/>
+            <field name="flow_stop">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+        <record id="activity_h_c" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_h"/>
+            <field name="flow_stop">True</field>
+            <field name="name">c</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+
+        <record id="trans_h_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_h_a"/>
+            <field name="act_to" ref="activity_h_b"/>
+        </record>
+        <record id="trans_h_a_c" model="workflow.transition">
+            <field name="act_from" ref="activity_h_a"/>
+            <field name="act_to" ref="activity_h_c"/>
+        </record>
+
+        <!-- Workflow I:
+
+            a or -> b { value: 2 } 
+                 `false> c { value: 3 }
+
+        -->
+        <record id="test_workflow_i" model="workflow">
+            <field name="name">test.workflow.i</field>
+            <field name="osv">test.workflow.model.i</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_i_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_i"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+            <field name="split_mode">OR</field>
+        </record>
+        <record id="activity_i_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_i"/>
+            <field name="flow_stop">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+        <record id="activity_i_c" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_i"/>
+            <field name="flow_stop">True</field>
+            <field name="name">c</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 3})</field>
+        </record>
+
+        <record id="trans_i_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_i_a"/>
+            <field name="act_to" ref="activity_i_b"/>
+        </record>
+        <record id="trans_i_a_c" model="workflow.transition">
+            <field name="act_from" ref="activity_i_a"/>
+            <field name="act_to" ref="activity_i_c"/>
+            <field name="condition">False</field>
+        </record>
+
+        <!-- Workflow J:
+
+            a and -> b { value: 2 } 
+                  `False> c { value: 3 }
+
+        This will stay in a because all transitions should be True at the same time.
+
+        -->
+        <record id="test_workflow_j" model="workflow">
+            <field name="name">test.workflow.j</field>
+            <field name="osv">test.workflow.model.j</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_j_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_j"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+            <field name="split_mode">AND</field>
+        </record>
+        <record id="activity_j_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_j"/>
+            <field name="flow_stop">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+        <record id="activity_j_c" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_j"/>
+            <field name="flow_stop">True</field>
+            <field name="name">c</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 3})</field>
+        </record>
+
+        <record id="trans_j_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_j_a"/>
+            <field name="act_to" ref="activity_j_b"/>
+        </record>
+        <record id="trans_j_a_c" model="workflow.transition">
+            <field name="act_from" ref="activity_j_a"/>
+            <field name="act_to" ref="activity_j_c"/>
+            <field name="condition">False</field>
+        </record>
+
+        <!-- Workflow K:
+
+            a xor -> b { value: 2 } 
+                  `> c { value: 3 }
+
+        Only one (truish) transition is taken with a XOR.
+
+        -->
+        <record id="test_workflow_k" model="workflow">
+            <field name="name">test.workflow.k</field>
+            <field name="osv">test.workflow.model.k</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_k_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_k"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+            <field name="split_mode">XOR</field>
+        </record>
+        <record id="activity_k_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_k"/>
+            <field name="flow_stop">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+        </record>
+        <record id="activity_k_c" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_k"/>
+            <field name="flow_stop">True</field>
+            <field name="name">c</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 3})</field>
+        </record>
+
+        <record id="trans_k_a_b" model="workflow.transition">
+            <field name="act_from" ref="activity_k_a"/>
+            <field name="act_to" ref="activity_k_b"/>
+        </record>
+        <record id="trans_k_a_c" model="workflow.transition">
+            <field name="act_from" ref="activity_k_a"/>
+            <field name="act_to" ref="activity_k_c"/>
+        </record>
     </data>
 </openerp>
diff --git a/openerp/tests/addons/test_workflow/models.py b/openerp/tests/addons/test_workflow/models.py
index 84789cc9b69..8214d6313ff 100644
--- a/openerp/tests/addons/test_workflow/models.py
+++ b/openerp/tests/addons/test_workflow/models.py
@@ -55,7 +55,7 @@ class e(openerp.osv.orm.Model):
     _name = 'test.workflow.model.e'
     _inherit = 'test.workflow.model.a'
 
-for name in 'bcdef':
+for name in 'bcdefghijk':
     type(
         name,
         (openerp.osv.orm.Model,),
diff --git a/openerp/tests/addons/test_workflow/tests/test_workflow.py b/openerp/tests/addons/test_workflow/tests/test_workflow.py
index d55657f6a6a..4d9cee98b35 100644
--- a/openerp/tests/addons/test_workflow/tests/test_workflow.py
+++ b/openerp/tests/addons/test_workflow/tests/test_workflow.py
@@ -125,3 +125,48 @@ class test_workflows(common.TransactionCase):
         self.check_value(model._name, i, 2)
 
         model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_g(self):
+        model = self.registry('test.workflow.model.g')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+        self.check_value(model._name, i, 1)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_h(self):
+        model = self.registry('test.workflow.model.h')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['b', 'c'])
+        self.check_value(model._name, i, 2)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_i(self):
+        model = self.registry('test.workflow.model.i')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['b'])
+        self.check_value(model._name, i, 2)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_j(self):
+        model = self.registry('test.workflow.model.j')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['a'])
+        self.check_value(model._name, i, 1)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_k(self):
+        model = self.registry('test.workflow.model.k')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['b'])
+        self.check_value(model._name, i, 2)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])

From fc435af4284ff4f70c8f1900526d00fc5217307d Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Fri, 26 Jul 2013 12:36:00 +0200
Subject: [PATCH 14/17] [FIX] workflows: fixed the non-deterministic workflow
 K, added workflow L in tests.

bzr revid: vmt@openerp.com-20130726103600-t58rshix01q7vpot
---
 openerp/tests/addons/test_workflow/data.xml   | 72 ++++++++++++++++++-
 openerp/tests/addons/test_workflow/models.py  |  2 +-
 .../test_workflow/tests/test_workflow.py      | 13 +++-
 3 files changed, 83 insertions(+), 4 deletions(-)

diff --git a/openerp/tests/addons/test_workflow/data.xml b/openerp/tests/addons/test_workflow/data.xml
index b9f1e367000..6299baa77ea 100644
--- a/openerp/tests/addons/test_workflow/data.xml
+++ b/openerp/tests/addons/test_workflow/data.xml
@@ -403,7 +403,7 @@
         <!-- Workflow K:
 
             a xor -> b { value: 2 } 
-                  `> c { value: 3 }
+                  `> c { value: 2 }
 
         Only one (truish) transition is taken with a XOR.
 
@@ -434,7 +434,7 @@
             <field name="flow_stop">True</field>
             <field name="name">c</field>
             <field name="kind">function</field>
-            <field name="action">write({'value': 3})</field>
+	    <field name="action">write({'value': 2})</field>
         </record>
 
         <record id="trans_k_a_b" model="workflow.transition">
@@ -445,5 +445,73 @@
             <field name="act_from" ref="activity_k_a"/>
             <field name="act_to" ref="activity_k_c"/>
         </record>
+
+        <!-- Workflow L:
+
+            a -> xor c { value: 3 }
+            b ´
+            a -> and d { value: 3 }
+            b ´
+
+        c is run for each incoming (and taken) transition.
+        d is run once when all its incoming transitions are taken at the same time.
+
+        -->
+        <record id="test_workflow_l" model="workflow">
+            <field name="name">test.workflow.l</field>
+            <field name="osv">test.workflow.model.l</field>
+            <field name="on_create">True</field>
+        </record>
+
+        <record id="activity_l_a" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_l"/>
+            <field name="flow_start">True</field>
+            <field name="name">a</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 1})</field>
+            <field name="split_mode">OR</field>
+        </record>
+        <record id="activity_l_b" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_l"/>
+            <field name="flow_start">True</field>
+            <field name="name">b</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 2})</field>
+            <field name="split_mode">OR</field>
+        </record>
+        <record id="activity_l_c" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_l"/>
+            <field name="flow_stop">True</field>
+            <field name="name">c</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 3})</field>
+            <field name="join_mode">XOR</field>
+        </record>
+        <record id="activity_l_d" model="workflow.activity">
+            <field name="wkf_id" ref="test_workflow_l"/>
+            <field name="flow_stop">True</field>
+            <field name="name">d</field>
+            <field name="kind">function</field>
+            <field name="action">write({'value': 3})</field>
+            <field name="join_mode">AND</field>
+        </record>
+
+        <record id="trans_l_a_c" model="workflow.transition">
+            <field name="act_from" ref="activity_l_a"/>
+            <field name="act_to" ref="activity_l_c"/>
+        </record>
+        <record id="trans_l_b_c" model="workflow.transition">
+            <field name="act_from" ref="activity_l_b"/>
+            <field name="act_to" ref="activity_l_c"/>
+        </record>
+
+        <record id="trans_l_a_d" model="workflow.transition">
+            <field name="act_from" ref="activity_l_a"/>
+            <field name="act_to" ref="activity_l_d"/>
+        </record>
+        <record id="trans_l_b_d" model="workflow.transition">
+            <field name="act_from" ref="activity_l_b"/>
+            <field name="act_to" ref="activity_l_d"/>
+        </record>
     </data>
 </openerp>
diff --git a/openerp/tests/addons/test_workflow/models.py b/openerp/tests/addons/test_workflow/models.py
index 8214d6313ff..f7a5ef23b1a 100644
--- a/openerp/tests/addons/test_workflow/models.py
+++ b/openerp/tests/addons/test_workflow/models.py
@@ -55,7 +55,7 @@ class e(openerp.osv.orm.Model):
     _name = 'test.workflow.model.e'
     _inherit = 'test.workflow.model.a'
 
-for name in 'bcdefghijk':
+for name in 'bcdefghijkl':
     type(
         name,
         (openerp.osv.orm.Model,),
diff --git a/openerp/tests/addons/test_workflow/tests/test_workflow.py b/openerp/tests/addons/test_workflow/tests/test_workflow.py
index 4d9cee98b35..e9ff7b9cd1e 100644
--- a/openerp/tests/addons/test_workflow/tests/test_workflow.py
+++ b/openerp/tests/addons/test_workflow/tests/test_workflow.py
@@ -166,7 +166,18 @@ class test_workflows(common.TransactionCase):
         model = self.registry('test.workflow.model.k')
 
         i = model.create(self.cr, SUPERUSER_ID, {})
-        self.check_activities(model._name, i, ['b'])
+        # Non-determinisitic: can be b or c
+        # self.check_activities(model._name, i, ['b'])
+        # self.check_activities(model._name, i, ['c'])
         self.check_value(model._name, i, 2)
 
         model.unlink(self.cr, SUPERUSER_ID, [i])
+
+    def test_workflow_l(self):
+        model = self.registry('test.workflow.model.l')
+
+        i = model.create(self.cr, SUPERUSER_ID, {})
+        self.check_activities(model._name, i, ['c', 'c', 'd'])
+        self.check_value(model._name, i, 3)
+
+        model.unlink(self.cr, SUPERUSER_ID, [i])

From 3c0d11271eff5896de98f4af91c17d7e04a2c900 Mon Sep 17 00:00:00 2001
From: Raphael Collet <rco@openerp.com>
Date: Wed, 31 Jul 2013 15:58:14 +0200
Subject: [PATCH 15/17] [IMP] doc: improve workflow documentation

bzr revid: rco@openerp.com-20130731135814-386v5w6rkc40kwwv
---
 doc/workflows.rst | 284 +++++++++++++++++++++++-----------------------
 1 file changed, 144 insertions(+), 140 deletions(-)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index 293b2c347c0..86ba78d0275 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -3,24 +3,29 @@
 Workflows
 =========
 
-A workflow is a directed graph where the nodes are called "activities" and the
-arcs are called "transitions".
+In OpenERP, a workflow is a technical artefact to manage a set of "things to do"
+associated to the records of some data model. The workflow provides a higher-
+level way to organize the things to do 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 OpenERP server, such as
-  changing the state of some records, or sending mails.
+  changing the state of some records, or sending emails.
 
-- Transitions control how the workflow will go from activities to activities.
+- Transitions control how the workflow progresses from activity to activity.
 
-When defining a workflow, one can attach conditions, signals, and triggers to
-transitions, so that the behavior of the workflow can depend on user actions
-(such as clicking on a button), changes to records, or arbitrary Python code.
+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.
 
 Basics
 ------
 
 Defining a workflow with data files is straightforward: a record "workflow" is
-needed together with records for the activities and the transitions. For
-instance here is a simple sequence of two activities defined in XML::
+given together with records for the activities and the transitions. For
+instance, here is a simple sequence of two activities defined in XML::
 
     <record id="test_workflow" model="workflow">
         <field name="name">test.workflow</field>
@@ -49,81 +54,82 @@ instance here is a simple sequence of two activities defined in XML::
     </record>
 
 A worfklow is always defined with respect to a particular model (the model is
-given through the ``osv`` attribute on the ``workflow`` model). Methods
-specified in the activities or transitions will be called on that model.
+given by 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 ``flow_start`` attribute set to True so that OpenERP
-knows where to start the workflow when it is instanciated. Because
-``on_create`` is set to True on the workflow record, the workflow is
+The first activity has its attribute ``flow_start`` set to ``True`` so that
+OpenERP 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
-created by other means, such as from some module Python code.)
+instanciated by other means, such as from some module Python code.)
 
-When the workflow is instanciated, it will start by the "a" activity. That
-activity is of kind ``function`` which means the action ``print_a()`` is a
-method to be called on the ``test.workflow`` model (the usual ``cr, uid, ids,
-context`` arguments are passed for you).
+When the workflow is instanciated, it begins with activity "a". That activity is
+of kind ``function``, which means that the action ``print_a()`` is 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 conditions. This means
-the workflow instance will immediately progress from "a" to "b" (after "a" has
-been processed), and thus also process the "b" activity.
+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".
 
 Transitions
 -----------
 
 Transitions provide the control structures to orchestrate a workflow. When an
-activity is completed, the workflow engine will try to get across transitions
-departing from the completed activity, towards the next activities.  In their
-simplest form they just link activities from one to the others (as in the
-example above), and activities are processed as soon as the activities
-preceding them are completed.
+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.
 
-But instead of running all activities in one fell swoop, it is also possible to
-block on transitions, going through them only when some criteria are met. Such
-criteria are the conditions, the signals, and the triggers. They are detailed
-in the next sections.
+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 will be inspected
-to see if 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 OpenERP, and if it evaluates
-to ``True``, the worklfow instance will go through.
+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 OpenERP, 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 ``condition`` attribute (i.e. the expression to be evaluated)
-is just "True", which will trivially evaluate to ``True``.
-
-Actually, the condition can be several lines long, and the value of the last
-one will be used to test if the transition can be taken.
+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:
 
-- The  database cursor (``cr``),
-- the user ID (``uid``), the record ID tied to the workflow instance (``id``),
-- the user ID wrapped in a list (``ids``),
+- the database cursor (``cr``),
+- the user ID (``uid``),
+- the record ID tied to the workflow instance (``id``),
+- the record ID wrapped in a list (``ids``),
 - the model name (``model``),
 - the model instance (``obj``),
-- all the model column names,
-- and all the record (the one obtained by browsing the provided ID) attributes.
+- all the model column names, and
+- all the browse record's attributes.
 
 Signals
 '''''''
 
-In addition of a condition, a transition can specify a signal name. When such
-signal name is present, the transition will not be taken directly (even if the
-condition evaluates to true). Instead the transition will block, waiting to be
+In addition to a condition, a transition can specify a signal name. When such
+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.
 
-To wake up a transition with a defined signal name, the signal must be sent to
-the workflow. A common way to send a signal is to use a button in the web
-interface, using the ``<button/>`` element with the signal name as the ``name``
-attribute of the button.
+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 ``name`` attribute of the button. Once the button is clicked, 
 
 .. note:: The condition is still evaluated when the signal is sent to the
     workflow instance.
@@ -131,22 +137,22 @@ attribute of the button.
 Triggers
 ''''''''
 
-With conditions that evaluate to false, transitions are not taken (and thus the
-activity it leads to will not be processed). 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 fails, triggers are recorded in
-database. Later, it is possible to wake-up specifically the workflow instances
-that installed those triggers, offering them a new chance to evaluation their
-transition conditions. This mechnism makes it cheaper to wake-up workflow
+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 them. The transition definition
-can thus provide a Python expression (using the ``trigger_model`` attribute)
-that when evaluated will return the record IDs. Unlike the other expressions
-defined on the workflow, this one is evaluated with respect to a model that can
-be chosen on a per-transition basis with the ``trigger_expression`` attribute.
+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 to.
 
 .. note:: Note that triggers are not re-installed whenever the transition is
     re-tried.
@@ -154,128 +160,125 @@ be chosen on a per-transition basis with the ``trigger_expression`` attribute.
 Splitting and joining transitions
 '''''''''''''''''''''''''''''''''
 
-When multiple transitions leave the same activity, or lead to the same
-activity, OpenERP provides some control about which transitions will be
-crossed, or how the reached activity will be processed. The ``split_mode`` and
-``join_mode`` attributes on the activity are used for such control.
+When multiple transitions leave the same activity, or lead to the same activity,
+OpenERP provides some control over which transitions are actually taken, or how
+the reached activity will be processed. The attributes ``split_mode`` and
+``join_mode`` on the activity are used for such control. The possible values of
+those attributes are explained below.
 
 Activities
 ----------
 
-While the transitions can be seen as the control structure of the workflows,
-activities are the place where everything happen, from changing record states
+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 kind of activities exist: ``Dummy``, ``Function``, ``Subflow``, and
-``Stop all``; different kind of activities can do different and they are
-detailed below. 
-
-In addition to the activity kind, activies have some properties, detailed in
-the next sections.
+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 ``flow_start`` attribute is a boolean value specifying if the activity
-starts the workflow. Multiple activities can have the ``flow_start`` attribute
-set to ``True`` and when instanciating a workflow for a record, OpenERP will
-simply process all of them, and try all their outgoing transitions afterwards.
+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, OpenERP simply processes all of them, and evaluate all their
+outgoing transitions afterwards.
 
-The ``flow_stop`` attribute is also a boolean value, specifying if the activity
-ends the workflow. A workflow is considered to be completed when all its
-activities with the ``flow_stop`` attribute set to ``True`` are completed.
-
-It is important for OpenERP to know when a workflow instance is completed: a
-workflow can have an activity that is actually another workflow (called a
-subflow) and that activity will be completed only when the subflow is
+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 ``flow_stop`` attribute set to ``True`` are
 completed.
 
+It is important for OpenERP 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 the ``subflow_id`` attribute.
+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 will be completed (and its outgoing transitions will be tried)
-when the subflow is completed (see the ``flow_stop`` attribute above to read
-about when a workflow is considered completed by OpenERP).
+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 used (as a sublfow) in the activity of a (parent) workflow,
-the sublow can send a signal from its own activities to the parent by specifying a
-signal name in the ``signal_send`` attribute. OpenERP will process those
-activities normally and send to the parent workflow instance a signal with
-``signal_send`` value prefixed with ``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 attribute ``signal_send``. OpenERP 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 take transitions in the parent
+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 ``action_id``
-attribute.
+An activity can run a "Server Action" by specifying its ID in the attribute
+``action_id``.
 
 Python action
 '''''''''''''
 
-An activity can run some Python code, provided through the ``action``
-attribute. See the section about transition conditions to read about the
-evaluation environment.
+An activity can execute some Python code, given by attribute ``action``. The
+evaluation environment is the same as the one explained in the section
+`Conditions`_.
 
 Split mode
 ''''''''''
 
-After an activity has been processed, its outgoing transitions will be tried.
-Normally, if a transition can be taken, OpenERP will do it and proceed to the
+After an activity has been processed, its outgoing transitions are evaluated.
+Normally, if a transition can be taken, OpenERP traverses it and proceed to the
 activity the transition leads to.
 
-Actually, when more than a single transition is leaving an activity, OpenERP
-can proceed, or not, depending on the other transitions. That is, the condition
-on the transitions can be combined together, and the combined result will
-instruct OpenERP to cross zero, one, or all the transitions. The way they are
-combined is controlled by the ``split_mode`` attribute.
+Actually, when more than a single transition is leaving an activity, OpenERP may
+proceed or not, depending on the other transitions. That is, the condition on
+the transitions can be combined together, and the combined result instructs
+OpenERP to traverse zero, one, or all the transitions. The way they are combined
+is controlled by the attribute ``split_mode``.
 
-There are indeed three modes to decide how to combine the transition
-conditions, ``XOR``, ``OR``, and ``AND``.
+There are three possible split modes: ``XOR``, ``OR`` and ``AND``.
 
 ``XOR``
     When the transitions are combined with a ``XOR`` split mode, as soon as a
-    transition with a condition that evaluates to true is found, the
-    transition is taken and the other will not be tried.
+    transition has a satisfied condition, the transition is traversed and the
+    others are skipped.
 
 ``OR``
-    With an ``OR`` mode, all the transitions with a condition that evaluates to
-    true are taken. The remaining transitions will not be tried later.
+    With the ``OR`` mode, all the transitions with a satisfied condition are
+    traversed. The remaining transitions will not be evaluated later.
 
 ``AND``
-   With an ``AND`` mode, OpenERP will wait for all transition conditions to
-   evaluate to true, then cross all the transitions at the same time.
+    With the ``AND`` mode, OpenERP will wait for all outgoing transition
+    conditions to be satisfied, then traverse all of them at once.
 
 Join mode
 '''''''''
 
-Just as departing transition conditions can be combined together to decide
-whether they can be taken or not, arriving transitions can be combined together
-to decide if an activity must be run. The attribute to control that behavior is
-called ``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. The attribute
+``join_mode`` controls that behavior.
 
-The join mode is a bit simpler than the split mode: only two modes are
-provided, ``XOR`` and ``AND``.
+There are two possible join modes: ``XOR`` and ``AND``.
 
 ``XOR``
-    An activity with a ``XOR`` join mode will be run as soon as a transition is
-    crossed to arrive at the activity.
+    With the ``XOR`` mode, an incoming transition with a satisfied condition is
+    traversed immediately, and enables the processing of the activity.
 
 ``AND``
-   With an ``AND`` mode, the activity will wait for all its incoming
-   transitions to be crossed before being run.
+    With the ``AND`` mode, OpenERP will wait until all incoming transitions have
+    been traversed before enabling the processing of the activity.
 
 Kinds
 '''''
@@ -284,24 +287,25 @@ Activities can be of different kinds: ``dummy``, ``function``, ``subflow``, or
 ``stopall``. The kind defines what type of work an activity can do.
 
 Dummy
-    The ``dummy`` kind is for activities that do nothing (i.e. they act as hubs
-    to gather/dispatch transitions), or for activities that only call a Server
-    Action.
+    The ``dummy`` kind is for activities that do nothing, or for activities that
+    only call a server action. Activities that do nothing can be used as hubs to
+    gather/dispatch transitions.
 
 Function
     The ``function`` kind is for activities that only need to run some Python
-    code, and possibly a Server Action.
+    code, and possibly a server action.
 
 Stop all
-    The ``stopall`` kind is for activities that will completely halt the
-    workflow instance. In addition they can also run some Python code.
+    The ``stopall`` kind is for activities that will completely stop the
+    workflow instance and mark it as completed. In addition they can also run
+    some Python code.
 
 Subflow
-    When the kind of the activity is  ``subflow``, the activity will run
-    another workflow. When the sub-workflow is completed, the activity will also be
+    When the kind of the activity is ``subflow``, the activity embeds another
+    workflow instance. When the subflow is completed, the activity is also
     considered completed.
 
-    Normally the sub-workflow is instanciated for the same record as the parent
-    workflow. It is possible to change that default behavior by providing
-    Python code that has to return a record ID for which a workflow has been
-    instanciated.
+    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.

From 3d1d7ee39cd9e82c0499af533ae1e1553c4e3b0a Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Wed, 31 Jul 2013 17:09:43 +0200
Subject: [PATCH 16/17] [DOC] workflows: typos, and removed inaccurate
 environment symbols.

bzr revid: vmt@openerp.com-20130731150943-etfvn08fnkhcecvt
---
 doc/workflows.rst | 55 +++++++++++++++++++++--------------------------
 1 file changed, 25 insertions(+), 30 deletions(-)

diff --git a/doc/workflows.rst b/doc/workflows.rst
index 86ba78d0275..d8ba89bd1ad 100644
--- a/doc/workflows.rst
+++ b/doc/workflows.rst
@@ -54,8 +54,8 @@ instance, here is a simple sequence of two activities defined in XML::
     </record>
 
 A worfklow is always defined with respect to a particular model (the model is
-given by attribute ``osv`` on the model ``workflow``). Methods specified in the
-activities or transitions will be called on that model.
+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"
@@ -67,10 +67,10 @@ 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 method call
-on the model ``test.workflow`` (the usual ``cr, uid, ids, context`` arguments
-are passed for you).
+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
@@ -107,14 +107,8 @@ 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:
+defined (in addition to the OpenERP ``safe_eval`` environment):
 
-- the database cursor (``cr``),
-- the user ID (``uid``),
-- the record ID tied to the workflow instance (``id``),
-- the record ID wrapped in a list (``ids``),
-- the model name (``model``),
-- the model instance (``obj``),
 - all the model column names, and
 - all the browse record's attributes.
 
@@ -122,14 +116,15 @@ Signals
 '''''''
 
 In addition to a condition, a transition can specify a signal name. When such
-signal name is present, the transition is not taken directly, even if the
+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 ``name`` attribute of the button. Once the button is clicked, 
+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.
@@ -139,20 +134,20 @@ 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.
+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 to.
+they are associated with.
 
 .. note:: Note that triggers are not re-installed whenever the transition is
     re-tried.
@@ -189,7 +184,7 @@ 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 ``flow_stop`` attribute set to ``True`` are
+all its activities with the attribute ``flow_stop`` set to ``True`` are
 completed.
 
 It is important for OpenERP to know when a workflow instance is completed. A
@@ -214,9 +209,9 @@ 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 attribute ``signal_send``. OpenERP processes those
-activities by sending the value of ``signal_send`` prefixed by "subflow"  to the
-parent workflow instance.
+giving a signal name in the attribute ``signal_send``. OpenERP 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.
@@ -230,8 +225,8 @@ An activity can run a "Server Action" by specifying its ID in the attribute
 Python action
 '''''''''''''
 
-An activity can execute some Python code, given by attribute ``action``. The
-evaluation environment is the same as the one explained in the section
+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
@@ -242,7 +237,7 @@ Normally, if a transition can be taken, OpenERP traverses it and proceed to the
 activity the transition leads to.
 
 Actually, when more than a single transition is leaving an activity, OpenERP may
-proceed or not, depending on the other transitions. That is, the condition on
+proceed or not, depending on the other transitions. That is, the conditions on
 the transitions can be combined together, and the combined result instructs
 OpenERP to traverse zero, one, or all the transitions. The way they are combined
 is controlled by the attribute ``split_mode``.

From 07f5e9a4d64fcd8ae33303ff6c367c587d3c6e61 Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Wed, 31 Jul 2013 17:11:04 +0200
Subject: [PATCH 17/17] [REM] workflows: removed temporary run.py script from
 the tests.

bzr revid: vmt@openerp.com-20130731151104-mxo8qu5x12krto0h
---
 openerp/tests/addons/test_workflow/run.py | 44 -----------------------
 1 file changed, 44 deletions(-)
 delete mode 100755 openerp/tests/addons/test_workflow/run.py

diff --git a/openerp/tests/addons/test_workflow/run.py b/openerp/tests/addons/test_workflow/run.py
deleted file mode 100755
index dda955f9ce9..00000000000
--- a/openerp/tests/addons/test_workflow/run.py
+++ /dev/null
@@ -1,44 +0,0 @@
-#! /usr/bin/env python2
-import os
-
-import openerp
-from openerp import SUPERUSER_ID
-
-DATABASE='t'
-
-def configure():
-    conf = openerp.tools.config
-    conf['addons_path'] = os.path.join(os.path.dirname(os.path.dirname(__file__))) + ",/home/thu/repos/web/trunk/addons"
-    conf['log_handler'] = [':CRITICAL']
-    openerp.modules.module.initialize_sys_path()
-    openerp.netsvc.init_logger()
-
-if __name__ == '__main__':
-    configure()
-
-    print '> Loading registry `%s`...' % DATABASE
-    registry = registry = openerp.registry(DATABASE)
-    cr = registry.db.cursor()
-    print '< Registry `%s` loaded.' % DATABASE
-
-    model = registry['test.workflow.model']
-    trigger = registry['test.workflow.trigger']
-
-    print '> Creating new record...'
-    i = model.create(cr, SUPERUSER_ID, {})
-    print '< Record created with ID %s' % i
-
-    print '> Calling signal `a-b`...'
-    model.signal_workflow(cr, SUPERUSER_ID, [i], 'a-b')
-    print '< Signal `a-b` called.'
-
-    print '> Triggering associated record...'
-    model.trigger(cr, SUPERUSER_ID, [i])
-    print '< Associated record triggered.'
-
-    print '> Triggering associated record (this time with the condition evaluating to True)...'
-    trigger.write(cr, SUPERUSER_ID, [1], {'value': True})
-    model.trigger(cr, SUPERUSER_ID)
-    print '< Associated record triggered.'
-
-    cr.close()