doc/book/en/B0020-define-workflows.en.txt
author Emile Anclin <emile.anclin@logilab.fr>
Thu, 02 Apr 2009 18:13:59 +0200
changeset 1220 9f80ecdb057a
parent 1206 6db7addc2869
child 1398 5fe84a5f7035
permissions -rw-r--r--
finalize Workflow definition
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     2
197
1632e01a58a9 [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 129
diff changeset
     3
.. _Workflow:
1632e01a58a9 [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 129
diff changeset
     4
1220
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
     5
An Example: Workflow definition
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
     6
===============================
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
     7
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     8
General
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     9
-------
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    10
1220
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
    11
A workflow describes how certain entities have to evolve between 
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
    12
different states. Hence we have a set of states, and a "transition graph", 
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
    13
i.e. a list of possible transitions from one state to another state.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    14
1220
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
    15
We will define a simple workflow for a blog, with only the following 
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
    16
two states: `submitted` and `published`. So first, we create a simple 
9f80ecdb057a finalize Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 1206
diff changeset
    17
`CubicWeb` in ten minutes (see :ref:`BlogTenMinutes`).
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    18
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    19
Set-up a workflow
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    20
-----------------
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    21
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    22
We want to create a workflow to control the quality of the BlogEntry 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    23
submitted on your application. When a BlogEntry is created by a user
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    24
its state should be `submitted`. To be visible to all, it has to
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    25
be in the state `published`. To move it from `submitted` to `published`,
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    26
we need a transition that we can call `approve_blogentry`.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    27
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    28
A BlogEntry state should not be modifiable by every user.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    29
So we have to define a group of users, `moderators`, and 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    30
this group will have appropriate permissions to publish a BlogEntry.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    31
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    32
There are two ways to create a workflow: from the user interface,
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    33
or by defining it in ``migration/postcreate.py``. 
306
1ed1da008e50 [doc] Removes references to LAX.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 287
diff changeset
    34
This script is executed each time a new ``cubicweb-ctl db-init`` is done. 
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    35
We strongly recommand to create the workflow in ``migration/postcreate.py``
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    36
and we will now show you how. Read `Under the hood`_ to understand why.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    37
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    38
Update the schema
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    39
~~~~~~~~~~~~~~~~~
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    40
If we want a State for our BlogEntry, we have to define a relation
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    41
``in_state`` in the schema of BlogEntry. So we add
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    42
the line ``in_state (...)``::
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    43
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    44
  class BlogEntry(EntityType):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    45
      title = String(maxsize=100, required=True)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    46
      publish_date = Date(default='TODAY')
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    47
      text_format = String(meta=True, internationalizable=True, maxsize=50,
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    48
                           default='text/rest', constraints=[format_constraint])
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    49
      text = String(fulltextindexed=True)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    50
      category = String(vocabulary=('important','business'))
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    51
      entry_of = SubjectRelation('Blog', cardinality='?*')
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    52
      in_state = SubjectRelation('State', cardinality='1*')
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    53
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    54
As you updated the schema, you have to re-execute ``cubicweb-ctl db-init``
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    55
to initialize the database and migrate your existing entities.
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    56
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    57
[WRITE ABOUT MIGRATION]
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    58
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    59
Create states, transitions and group permissions
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    60
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    61
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    62
The ``postcreate.py`` script is executed in a special environment, adding
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    63
several `CubicWeb` primitives that can be used.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    64
They are all defined in the ``class ServerMigrationHelper``.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    65
We will only discuss the methods we use to create a workflow in this example.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    66
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    67
To define our workflow for BlogDemo, please add the following lines
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    68
to ``migration/postcreate.py``::
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    69
  
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    70
  _ = unicode
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    71
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    72
  moderators = add_entity('EGroup', name=u"moderators")
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    73
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    74
This adds the `moderators` user group.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    75
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    76
::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    77
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    78
  submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    79
  published = add_state(_('published'), 'BlogEntry')
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    80
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    81
``add_state`` expects as first argument the name of the state you want
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    82
to create, then the entity type on which the state can be applied,
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    83
and an optional argument to say if it is supposed to be the initial state
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    84
of the entity type.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    85
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    86
::
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    87
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    88
  add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    89
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    90
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    91
``add_transition`` expects 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    92
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    93
  * as the first argument the name of the
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    94
    transition, then the entity type on which the transition can be applied,
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    95
  * then the list of states on which the transition can be trigged,
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    96
  * the target state of the transition, 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    97
  * and the permissions
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    98
    (e.g. a list of user groups who can apply the transition; the user
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
    99
    has to belong to at least one of the listed group to perform the action).
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   100
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   101
::
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   102
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   103
  checkpoint()
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   104
129
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   105
.. note::
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   106
  Do not forget to add the `_()` in front of all states and transitions names while creating
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   107
  a workflow so that they will be identified by the i18n catalog scripts.
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   108
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   109
In addition to the user group condition, we could have added a RQL condition. 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   110
In this case, the user can only perform the action if 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   111
the two conditions are satisfied. 
129
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   112
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   113
If we use a RQL condition on a transition, we can use the following 
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   114
variables:
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   115
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   116
* `%(eid)s`, object's eid
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   117
* `%(ueid)s`, user executing the query eid
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   118
* `%(seid)s`, the object's current state eid
061fa802e2a3 [doc] Merged translation of paragraph.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   119
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   120
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   121
.. image:: images/lax-book.03-transitions-view.en.png
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   122
1206
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   123
You can notice that in the action box of a BlogEntry, the state
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   124
is now listed as well as the possible transitions defined by the workflow.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   125
The transitions will only be displayed for users having the right permissions.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   126
In our example, the transition `approve_blogentry` will only be displayed 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   127
for the users belonging to the group `moderators` or `managers`.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   128
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   129
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   130
Under the hood
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   131
~~~~~~~~~~~~~~
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   132
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   133
A workflow is a collection of entities of type ``State`` and of type ``Transition``
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   134
which are standard `CubicWeb` entity types.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   135
For instance, the following lines::
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   136
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   137
  submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   138
  published = add_state(_('published'), 'BlogEntry')
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   139
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   140
will create two entities of type ``State``, one with name 'submitted', and the other
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   141
with name 'published'. Whereas::
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   142
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   143
  add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   144
 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   145
will create an entity of type ``Transition`` with name 'approve_blogentry' which will
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   146
be linked to the ``State`` entities created before.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   147
As a consequence, we could use the administration interface to do these operations.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   148
But it is not recommanded because it will be uselessly complicated
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   149
and will be only local to your instance.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   150
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   151
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   152
Indeed, if you create the states and transitions through the user interface,
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   153
next time you initialize the database
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   154
you will have to re-create all the entities. 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   155
The user interface should only be a reference for you to view the states 
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   156
and transitions, but is not the appropriate interface to define your
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   157
application workflow.
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   158
6db7addc2869 [doc] rewrite Workflow definition
Emile Anclin <emile.anclin@logilab.fr>
parents: 858
diff changeset
   159