This document is to describe the concepts of workflow in Magnolia5.
The workflow has been decoupled into two modules: workflow-base with the general API, common UI, common configuration etc., and workflow-jbpm with the jBPM based implementation. This decoupling shall allow to add other implementations in the future (e.g. workflow-activiti).
The module defines the general workflow API in the info.magnolia.module.workflow.base.api package. The most important are following interfaces:
The interface for the main workflow class, responsible for the starting up / stopping the workflow engine, managing the workflow definitions, firing up the processes, etc.
This is the interface for the utility class, provides methods to simplify the code (e.g.
activate(workspace, path)) and to interact with the rest of Magnolia API - this has to be available in the workflow definition (in script tasks), e.g. to send a message to users that some workflow has started, or waits for a user interaction, etc.
Handling user interaction
Generally, there are two possibilities - to handle everything on our own, or to use the Human Tasks infrastructure from the jBPM.
A) Implementing everything on our own
When the process requires user interaction (e.g. approval), it will use the implementation of the WorkflowUtil interface to store needed information (process ID, required action, ...) in the workitems workspace and notify the user(s) about the request.
The UI will then use SignalEvent (containing the user input) to reactivate the process flow, but the process must remove its record in the workitems workspace when handling the event (again using WorkflowUtil's methods).
B) Human Task Service
Since jBPM 5.4 (released in November 2012), the LocalHumanTaskService is available (doesn't require to start an additional service). The HT service takes care for handling the UserTasks - including storing their data as described above, and also e.g. escalation of not-in-time processed tasks.
To use the advantages of the HT service, the process definition must contain an UserTask - when the running process reaches UserTask, it is stored in the HT service (an e-mail notification can be send to the user/group the task is assigned to), and the HT client is used to ask the HT service "are there any tasks for user/group XY?". The client then can retrieve particular process and handle it.
Although using the HT service is more in the jBPM style, I am in favor of using the "everything on our own" approach. Here are my reasons:
- Better control on what is going on.
This also means that if we later use another process engine (that might not have an equivalent of the HT service), we will still use the same pattern.
- Use of JCR API we are used to.
- Possibility to notify users via Magnolia messages.
This means that using just pure UserTask / HT service we won't be able to send a message to a user/group that there is new process waiting for approval; If we wanted to do so, we would have to use the WorkflowUtil prior to the UserTask anyway;
Requests / Wishes
Here is the place to specify the requirements to the workflow implementation.
- In the Pages app, indicate that some content is already in the (activation/deactivation) process, to prevent multiple activations.
- The "Inbox" app should be a bit sophisticated, not just a simple list of waiting processes.
- Define conflict handling: e.g. what shall happen when the content waiting for activation approval (or scheduled activation) is changed - which version should be activated? Or shall be the whole process skipped? Shall we prevent users from changing a content, which is already "in process"?
- Integrate the jBPM's visual workflow editor (should be possible, see http://blog.athico.com/2011/04/using-oryx-designer-and-guvnor-in-your.html).