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

.. _Workflow:

Workflow definition

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

General

-------

A workflow can be defined in a `CubicWeb` application thanks to the system 

entities ``State`` and ``Transition``. Those are defined within all 

`CubicWeb` application and can be set-up through the main administrator interface.

Once your schema is defined, you can start creating the set of states and

the required transitions for your applications entities.

You first need to define the states and then the transitions between those

to complete your workflow.

A ``State`` defines the status of an entity. While creating a new state, 

you will be first given the option to select the entity type the state

can be applied to. By choosing ``Apply``, a new section will be displayed

in the editing screen to enable you to add relation to the state you are

creating.

A ``Transition`` is also based on an entity type it can be applied to.

By choosing ``Apply``, a new section will be displayed in the editing 

screen to enable you to add relation to the transition you are

creating.

At the transition level you will also define the group of user which can

aplly this transition to an object.

Example of a simple workflow

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

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

[Create a simple workflow for BlogDemo, to have a moderator approve new blog 

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

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

it reaches the state published]

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 needs to

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

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

We do not want every user to be allowed to change the state of a 

BlogEntry. We need to define a group of user, `moderators`, and 

this group will have appropriate permissions to approve BlogEntry

to be published and visible to all.

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

and also by defining it in ``migration/postcreate.py``. 

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

If you create the states and transitions through the user interface

this means that next time you will need to initialize the database

you will have to re-create all the entities. 

We strongly recommand you create the workflow in ``migration\postcreate.py``

and we will now show you how.

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

and transitions but is not the appropriate interface to define your

application workflow.

Update the schema

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

To enable a BlogEntry to have a State, we have to define a relation

``in_state`` in the schema of BlogEntry. Please do as follows, 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 will have re-execute ``cubicweb-ctl db-init``

to initialize the database and migrate your existing entities.

[WRITE ABOUT MIGRATION]

Create states, transitions and group permissions

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

At the time the ``postcreate.py`` script is executed, several methods

can be used. They are all defined in the ``class ServerMigrationHelper``.

We will only discuss the method we use to create a wrokflow here.

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

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

  _ = unicode

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

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

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

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

  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.

``add_entity`` is used here to define the new group of users that we

need to define the transitions, `moderators`.

If this group required by the transition is not defined before the

transition is created, it will not create the relation `transition 

require the group moderator`.

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

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

and an optionnal argument to set if the state is the initial state

of the entity type or not.

``add_transition`` expects as the first argument the name of the 

transition, then the entity type on which we can apply the transition,

then the list of possible initial states from which the transition

can be applied, the target state of the transition, and the permissions

(e.g. list of the groups of users who can apply the transition, the user

needs to belong to at least one of the listed group).

We could have also added a RQL condition in addition to a group to 

which the user should belong to. 

If we use both RQL condition and group, the two must be satisfied 

for the user to be allowed to apply the transition.

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 now notice that in the actions box of a BlogEntry, the state

is now listed as well as the possible transitions from this state

defined by the workflow. This transition, as defined in the workflow,

will only being displayed for the users belonging to the group

moderators of managers.