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

Définition de workflow
======================

Avant-propos
------------

Un worflow décrit comment les entités vont être utilisés à travers différents états. Nous avons donc pour un workflow donné un ensemble d'états, un "graphe de transition" c'est-à-dire la liste des transitions possibles d'un état à un autre.

Nous allons définir ici un simple workflow pour l'exemple du blog avec seulement deux états: `en attente` et `publié`. Il est nécessaire d'avoir préalablement créé une application simple *CubicWeb* en dix minutes (voir :ref:`BlogFiveMinutes`).

Mise en place du workflow
-------------------------

Nous allons créer un workflow pour contrôler la qualité des BlogEntry soumis à l'instance. Lorsque un BlogEntry est créé par un utilisateur, son état doit être `en attente`. Pour être visible par tous, il doit être ensuite mis à l'état `publié`. Pour le changement d'état d'`en attente` à `publié`, nous avons besoin d'une transition que nous appellerons `approuve_blogentry`.

Un état BlogEntry ne doit pas pouvoir être modifiable par les utilisateurs. Nous allons donc créé un groupe de modération `moderateurs` et ce groupe aura les permissions idoines pour publier un BlogEntry.

Il existe deux manières de créer un workflow: depuis l'interface utilisateur ou en le définissant dans le fichier ``migration/postcreate.py``.
Ce script est exécuté à chaque lancement de la commande ``cubicweb-ctl db-init``.
Nous encourageons vivement la création dans ``migration/postcreate.py`` que nous allons vous montrer ici. Lire `Sous le capot`_ pour en comprendre les raisons.

L'état d'une entité est sauvegardé par l'attribut `in_state` qui peut être ajouté à votre schéma d'entité par deux façons:

* héritage direct en utilisant la classe `cubicweb.schema.WorkflowableEntityType`
* par délégation en utilisant `cubicweb.schema.make_worflowable` (utilisable comme un décorateur également)

Pour notre exemple de BlogEntry, nous devons avoir:

.. sourcecode:: python

  from cubicweb.schema import WorkflowableEntityType

  class BlogEntry(EntityType, WorkflowableEntityType):
      ...


Création des états, transitions et les permissions de groupe
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Le script ``postcreate.py`` est exécuté dans un environnement spécial où plusieurs primitives *CubicWeb* peuvent être utilsées.
Elles sont toutes définies dans ``class ServerMigrationHelper``.
Nous allons maintenant voir dans le prochain example celles utilisées pour créer un workflow.

Pour définir notre workflow pour BlogDemo, veuillez ajouter les lignes suivantes au script ``migration/postcreate.py``:

.. sourcecode:: python

  _ = unicode

  moderators = add_entity('CWGroup', name=u"modérateurs")

Cela va ajouter le groupe utilisateur `moderators`.

.. sourcecode:: python

  wf = add_workflow(u'une description succincte de votre workflow', 'BlogEntry')

Ceci va premièrement instancier un nouvel objet workflow avec une description sommaire mais pertinente et le type d'entité concerné (un tuple pour être utilisé pour des valeurs multiples).

.. sourcecode:: python

  submitted = wf.add_state(_('submitted'), initial=True)
  published = wf.add_state(_('published'))

``add_state`` attend comme premier argument le nom de l'état que vous voulez créer et un argument optionnel pour signifier si c'est l'état initial supposé pour ce type d'entité.

.. sourcecode:: python

  wf.add_transition(_('approuve_blogentry'), (submitted,), published, ('moderators', 'managers'),)

``add_transition`` attend:

  * comme premier argument le nom de la transition
  * ensuite la liste des états pour lesquels les transitions peuvent être tirées,
  * l'état attendu en fin de transition,
  * et les permissions
    (c'est-à-dire la liste des goupes utilisateurs qui peuvnet appliquer la transition; l'utilisateur devant appartenir à l'un des groupes listés pour être autoriser à exécuter l'action).

.. sourcecode:: python


  checkpoint()

.. note::
  Dans le script de création d'un workflow, penser à mettre `_()` autour des noms d'états et de transitions pour que ceux si soient pris en compte par les scripts de gestion des catalogues i18n.

En complément de condition sur des groupes utilisateur dont l'utilisateur doit appartenir à l'in d'entre eux, vous pouvez utiliser une RQL condition.
Dans ce cas, l'utilisateur peut seulement exécuter une action si les deux conditions sont satisfaites.

Pour la condition RQL sur une transition, on peut y mettre les substitutions suivantes :

* `%(eid)s`, eid de l'objet
* `%(ueid)s`, eid de l'utilisateur qui fait la requête
* `%(seid)s`, eid de l'état courant de l'objet

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

Vous pouvez remarqué que dans la boîte d'action d'un BlogEntry, l'état est maintenant listé ainsi que les possibles transitions définis pour l'état en cours dans le workflow. Les transitions ne sont seulement affichées pour les utilisateurs ayant les bonnes permissions.
Dans notre exemple, la transition `approuve_blogentry` sera seulement affichée pour les utilisateurs appartenant au groupe `moderators` or `managers`.


Sous le capot
~~~~~~~~~~~~~

Un workflow est une collection d'entités de type `State`` et ``Transition`` qui sont des types d'entités standards de *CubicWeb*.

Par exemple, les lignes précédentes:

.. sourcecode:: python

  submitted = wf.add_state(_('en attente'), initial=True)
  published = wf.add_state(_('publié'))

vont créé deux entités de type ``State``, l'une avec le nom 'submitted' et l'autre avec le nom 'published'. Tandis que:

.. sourcecode:: python

  wf.add_transition(_('approuve_blogentry'), (submitted,), published, ('moderators', 'managers'),)

va créé une entité de type ``Transition`` avec le nom `approuve_blogentry` qui sera relié aux entités ``State`` créées précédemment.

Dès lors, nous pouvons utiliser l'interface d'administration pour ces opérations. Mais ce n'est pas recommandé à cause de la complexité superflue et du fait que ces changements ne seront locaux qu'à cette instance.

En effet, si vous créez les états et les transitions à travers l'interface utilisateur, la prochaine initialisation de la base de données vous oblige à recréer toutes les entités.
L'interface utilisateur devrait être seulement connu par vous pour la visualisation des états et transitions, mais ce n'est pas celle appropriée pour définir vos workflows applicatifs.