19 

    20 General

    21 -------

    22 

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

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

    25 LAX application and can be set-up through the main administrator interface.

    26 

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

    28 the required transitions for your applications entities.

    29 

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

    31 to complete your workflow.

    32 

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

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

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

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

    37 creating.

    38 

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

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

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

    42 creating.

    43 

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

    45 aplly this transition to an object.

    46 

    47 

    48 Example of a simple workflow

    49 ----------------------------

    50 

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

    52 

    53 

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

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

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

    57 it reaches the state published]

    58 

    59 Set-up a workflow

    60 -----------------

    61 

    62 Before starting, make sure you refresh your mind by reading [link to

    63 definition_workflow chapter].

    64 

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

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

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

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

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

    70 

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

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

    73 this group will have appropriate permissions to approve BlogEntry

    74 to be published and visible to all.

    75 

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

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

    78 is executed each time a new ``./bin/laxctl db-init`` is done. 

    79 If you create the states and transitions through the user interface

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

    81 you will have to re-create all the entities. 

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

    83 and we will now show you how.

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

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

    86 application workflow.

    87 

    88 Update the schema

    89 ~~~~~~~~~~~~~~~~~

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

    91 ``in_state`` in the schema of BlogEntry. Please do as follows, add

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

    93 

    94   class BlogEntry(EntityType):

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

    96       publish_date = Date(default='TODAY')

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

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

    99       text = String(fulltextindexed=True)

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

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

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

   103 

   104 As you updated the schema, you will have re-execute ``./bin/laxctl db-init``

   105 to initialize the database and migrate your existing entities.

   106 [WRITE ABOUT MIGRATION]

   107 

   108 Create states, transitions and group permissions

   109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   110 

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

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

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

   114 

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

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

   117   

   118   _ = unicode

   119 

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

   121 

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

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

   124 

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

   126 

   127   checkpoint()

   128 

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

   130 need to define the transitions, `moderators`.

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

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

   133 require the group moderator`.

   134 

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

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

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

   138 of the entity type or not.

   139 

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

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

   142 then the list of possible initial states from which the transition

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

   144 (e.g. list of the groups of users who can apply the transition).

   145 

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

   147 

   148 You can now notice that in the actions box of a BlogEntry, the state

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

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

   151 will only being displayed for the users belonging to the group

   152 moderators of managers.

   153 

   154