.. -*- coding: utf-8 -*-

.. _Workflow:

An Example: Workflow definition

===============================

General

-------

A workflow describes how certain entities have to evolve between 

different states. Hence we have a set of states, and a "transition graph", 

i.e. a list of possible transitions from one state to another state.

We will define a simple workflow for a blog, with only the following 

two states: `submitted` and `published`. So first, we create a simple 

`CubicWeb` in ten minutes (see :ref:`BlogTenMinutes`).

Set-up a workflow

-----------------

We want to create a workflow to control the quality of the BlogEntry 

submitted on your application. When a BlogEntry is created by a user

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``. 

This script is executed each time a new ``cubicweb-ctl db-init`` is done. 

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.

Update the schema

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

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

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

the line ``in_state (...)``::

  class BlogEntry(EntityType):

      title = String(maxsize=100, required=True)

      publish_date = Date(default='TODAY')

      text_format = String(meta=True, internationalizable=True, maxsize=50,

                           default='text/rest', constraints=[format_constraint])

      text = String(fulltextindexed=True)

      category = String(vocabulary=('important','business'))

      entry_of = SubjectRelation('Blog', cardinality='?*')

      in_state = SubjectRelation('State', cardinality='1*')

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

to initialize the database and migrate your existing entities.

[WRITE ABOUT MIGRATION]

Create states, transitions and group permissions

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

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.

To define our workflow for BlogDemo, please add the following lines

to ``migration/postcreate.py``::

  _ = unicode

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

This adds the `moderators` user group.

::

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

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

``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(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)

``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).

::

  checkpoint()

.. note::

  Do not forget to add the `_()` in front of all states and transitions names while creating

  a workflow so that they will be identified by the i18n catalog scripts.

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. 

If we use a RQL condition on a transition, we can use the following 

variables:

* `%(eid)s`, object's eid

* `%(ueid)s`, user executing the query eid

* `%(seid)s`, the object's current state eid

.. image:: images/lax-book.03-transitions-view.en.png

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.