.. _workflows: Workflows ========= In OpenERP, a workflow is a technical artefact to manage a set of "things to do" associated to the records of some data model. The workflow provides a higher- level way to organize the things to do on a record. More specifically, a workflow is a directed graph where the nodes are called "activities" and the arcs are called "transitions". - Activities define work that should be done within the OpenERP server, such as changing the state of some records, or sending emails. - Transitions control how the workflow progresses from activity to activity. In the definition of a workflow, one can attach conditions, signals, and triggers to transitions, so that the behavior of the workflow depends on user actions (such as clicking on a button), changes to records, or arbitrary Python code. Basics ------ Defining a workflow with data files is straightforward: a record "workflow" is given together with records for the activities and the transitions. For instance, here is a simple sequence of two activities defined in XML:: test.workflow test.workflow.model True True a function print_a() True b function print_b() A worfklow is always defined with respect to a particular model (the model is given by the attribute ``osv`` on the model ``workflow``). Methods specified in the activities or transitions will be called on that model. In the example code above, a workflow called "test_workflow" is created. It is made up of two activies, named "a" and "b", and one transition, going from "a" to "b". The first activity has its attribute ``flow_start`` set to ``True`` so that OpenERP knows where to start the workflow traversal after it is instanciated. Because ``on_create`` is set to True on the workflow record, the workflow is instanciated for each newly created record. (Otherwise, the workflow should be instanciated by other means, such as from some module Python code.) When the workflow is instanciated, it begins with activity "a". That activity is of kind ``function``, which means that the action ``print_a()`` is a method call on the model ``test.workflow`` (the usual ``cr, uid, ids, context`` arguments are passed for you). The transition between "a" and "b" does not specify any condition. This means that the workflow instance immediately goes from "a" to "b" after "a" has been processed, and thus also processes activity "b". Transitions ----------- Transitions provide the control structures to orchestrate a workflow. When an activity is completed, the workflow engine tries to get across transitions departing from the completed activity, towards the next activities. In their simplest form (as in the example above), they link activities sequentially: activities are processed as soon as the activities preceding them are completed. Instead of running all activities in one fell swoop, it is also possible to wait on transitions, going through them only when some criteria are met. The criteria are the conditions, the signals, and the triggers. They are detailed in the following sections. Conditions '''''''''' When an activity has been completed, its outgoing transitions are inspected to determine whether it is possible for the workflow instance to proceed through them and reach the next activities. When only a condition is defined (i.e., no signal or trigger is defined), the condition is evaluated by OpenERP, and if it evaluates to ``True``, the worklfow instance progresses through the transition. If the condition is not met, it will be reevaluated every time the associated record is modified, or by an explicit method call to do it. By default, the attribute ``condition`` (i.e., the expression to be evaluated) is just "True", which trivially evaluates to ``True``. Note that the condition may be several lines long; in that case, the value of the last one determines whether the transition can be taken. In the condition evaluation environment, several symbols are conveniently defined (in addition to the OpenERP ``safe_eval`` environment): - all the model column names, and - all the browse record's attributes. Signals ''''''' In addition to a condition, a transition can specify a signal name. When such a signal name is present, the transition is not taken directly, even if the condition evaluates to ``True``. Instead the transition blocks, waiting to be woken up. In order to wake up a transition with a defined signal name, the signal must be sent to the workflow instance. A common way to send a signal is to use a button in the user interface, using the element ``