Integrating Workflow in OpenCms

General thoughts about Workflow integration

Workflow (WF) in OpenCms should provide support for a publish cycle of one or more resources. This means that a workflow may consist of creation, modification (deletion) and publishing of one or more resources. An OpenCms workflow therefore will always terminate when a resource or a set of resources is published to the Online project.

Important to note is that WF requirements for customers are widely different, so that is should always be possible to adopt WF to customer specific needs.

During the workflow, a resource may shift through several stages, different users being responsible to approve/edit the resource in these stages. Some sort of messaging functionality will be required to inform users about their tasks. Moreover, dialogs and functions and a GUI to start a workflow and to manage the different WF states will be required.

Minimum requirements to a Workflow interface

In this sprint, we evaluate the minimal changes required to the OpenCms core in order to be able to implement Workflow functionality in general. The purpose is to develop a thin layer interface for a 'Workflow Manager' that the OpenCms core and the lock system in particular should be aware of.

This thin Workflow Manager interface should provide the following functionality:

• If a resource is edited in a workflow, it must be only editable by users that are the current 'owners' of the resource according to the workflow. A workflow may traverse several states where different users (or groups) become 'owners' of the resource. In OpenCms the lock system already provides a similar functionality. Therefore the lock system should be extended to be workflow aware - providing special lock states for resources inside a workflow. The benefit of this approach is that all other functionality like publishing, editing etc. will not have to be modified, since it already uses the lock states to decide what permissions a users has with a resource.
• Besides changes to the OpenCms locking mechanism, we need a certain minimum amount of information in the OpenCms GUI - the Workplace Explorer - so that users can see what resource is part of a workflow. For this, the basic idea is to use the Explorer GUI 'flag' column to display special status icons if a resource is part of the workflow. For the workflow, two other icons / states will be needed: a) 'Green WF icon' - this will signal the user that a resource is part of a workflow, and he/she is the current owner of the resource according to the workflow. b) 'Red WF Icon' - this will signal the user that a resource is part of a workflow, and that he/she is NOT allowed to currently edit/modify the resource. Additional to the icon being displayed, there should be a status text that is shown when the user moves the mouse over the WF icon. This status text should be fully provided by the workflow system.

With the above mentioned changes, it should be possible to implement a full WF system in OpenCms without further changes to the OpenCms core. Implementing the WF GUI, Messaging and state information will be the work that has to be done in the next step. Apparently there will be additional dialogs in OpenCms required to start and manage the workflows, we will need an overview of the workflow items owned by a specific user etc.

However, all of this can be developed in an OpenCms module without any further core changes, since it is possible to add entries to the context menus or additional Workplace views by configuration.

General approach for implementing the Workflow interface

The above mentioned minimum requirements can be implemented like this:

• We need modifications to the OpenCms lock mechanism, most notably to the org.opencms.lock package where the classes CmsLock, CmsLockState and CmsLockManager reside.
• Modifications to the OpenCms Explorer HTML generation will be required, which is done in org.opencms.workplace.explorer.CmsExlorer class and the helper classes around that. Here we need to add information which icon and text should be displayed.
• The JavaScript modules/org.opencms.workplace.explorer/resources/system/workplace/resources/commons/explorer.js that is generating the Explorer HTML needs to be modified to include the new Explorer icons and text.
• For all of this a 'Workflow Manager' interface is needed that should contain a very small number of methods to tell the lock mechanism which status a resource has for a certain user in the workflow, and to tell the Explorer which status string should be displayed for a resource in the workflow.
• This Workflow Manager interface implementation should be provided by the org.opencms.main.OpenCms Singelton in the very same way all other manager classes are provided.
• The Workflow Manager instance actually used has to be configured in the opencms-system.xml file similar e.g. to the Event Manager. Required changes in the configuration files and classes will be straightforward.
• If no Workflow Manager is defined in the configuration, OpenCms should work just as before without any workflow functionality.

Key findings during the sprint

• One issue with the approach described above is that so far a lock is always owned by a user. With the WF approach, a must check a user state AND the WF state. A lock may thus be a workflow lock that does not belong to a user yet. This may require additional logic inside the lock, and maybe a method like CmsLock#isOwnedByInWorflow(CmsUser user) must be implemented.
• To set a WF lock, an additional method in the CmsObject may be required e.g. CmsObject#lockResourceInWorkflow(CmsUser user). This will then use the WF lock type with the existing private method in the CmsObject.
• The initial setting of the WF lock would be done by the WF Manager using the above mentioned API. Then a user who is owner according to the WF may lock the resource e.g. to edit it. This means the user would add an exclusive lock to a resource already locked, but only as WF. The OpenCms Lock Manager needs to be modified so that it detects such a sate, and in this case modifies the existing WF lock instead of adding a new lock.
• Lock states in OpenCms are quite complex, even without the additional WF information. Adding more states to the lock for the WF must be done with great care in order not to break the current behaviour.