[TODO :  All this is too obscure and often not very understandable...]

[XXX define what a "Workflow" is: states, transitions, transition graph ]

Please see the tutorial to view an example of a simple workflow.

entry to be published. This implies specifying a dedicated group of blog

moderator as well as hiding the view of a blog entry to the user until

its state should be `submitted`. To be visible to all, it has to

be in the state `published`. To move it from `submitted` to `published`,

we need a transition that we can call `approve_blogentry`.

A BlogEntry state should not be modifiable by every user.

So we have to define a group of users, `moderators`, and 

this group will have appropriate permissions to publish a BlogEntry.

There are two ways to create a workflow: from the user interface,

or by defining it in ``migration/postcreate.py``. 

We strongly recommand to create the workflow in ``migration/postcreate.py``

and we will now show you how. Read `Under the hood`_ to understand why.

If we want a State for our BlogEntry, we have to define a relation

``in_state`` in the schema of BlogEntry. So we add

As you updated the schema, you have to re-execute ``cubicweb-ctl db-init``

The ``postcreate.py`` script is executed in a special environment, adding

several `CubicWeb` primitives that can be used.

They are all defined in the ``class ServerMigrationHelper``.

We will only discuss the methods we use to create a workflow in this example.

  moderators = add_entity('EGroup', name=u"moderators")

This adds the `moderators` user group.

::

``add_state`` expects as first argument the name of the state you want

to create, then the entity type on which the state can be applied,

and an optional argument to say if it is supposed to be the initial state

of the entity type.

::

``add_transition`` expects 

  * as the first argument the name of the

    transition, then the entity type on which the transition can be applied,

  * then the list of states on which the transition can be trigged,

  * the target state of the transition, 

  * and the permissions

    (e.g. a list of user groups who can apply the transition; the user

    has to belong to at least one of the listed group to perform the action).

::

In addition to the user group condition, we could have added a RQL condition. 

In this case, the user can only perform the action if 

the two conditions are satisfied. 

You can notice that in the action box of a BlogEntry, the state

is now listed as well as the possible transitions defined by the workflow.

The transitions will only be displayed for users having the right permissions.

In our example, the transition `approve_blogentry` will only be displayed 

for the users belonging to the group `moderators` or `managers`.

Under the hood

~~~~~~~~~~~~~~

A workflow is a collection of entities of type ``State`` and of type ``Transition``

which are standard `CubicWeb` entity types.

For instance, the following lines::

  submitted = add_state(_('submitted'), 'BlogEntry', initial=True)

  published = add_state(_('published'), 'BlogEntry')

will create two entities of type ``State``, one with name 'submitted', and the other

with name 'published'. Whereas::

  add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)

will create an entity of type ``Transition`` with name 'approve_blogentry' which will

be linked to the ``State`` entities created before.

As a consequence, we could use the administration interface to do these operations.

But it is not recommanded because it will be uselessly complicated

and will be only local to your instance.

Indeed, if you create the states and transitions through the user interface,

next time you initialize the database

you will have to re-create all the entities. 

The user interface should only be a reference for you to view the states 

and transitions, but is not the appropriate interface to define your

application workflow.