workflow2/readme.txt transcript

BearingPoint OpenCms Workflow2 Module
—————————————————————-
This module extends OpenCms by adding basic workflow related
features as:

- Definition of worklow states (defined as common
OpenCms projects)
- Assignment of VFS resources to specific workflow states
- Integrated user/role management
- Additional Interfaces for attaching a workflow engine

The Workflow2 module works by overlapping several OpenCms projects.
Each of these projects represents one workflow state:

project “Offline”, assigned to root folder
project “REVIEW”, assigned to root folder
project “APPROVAL”, assigned to root folder

As you see the Workflow2 module you can simply create n-eye workflow
mechanisms.

When creating a new resource in e.g. project one it’s also visible
from project two. Indeed OpenCms is showing an icon that the resource
belongs to project1, but the main functionalities (context menu) are
also available from the other projects.

This packages is solving that issue by adding certain behaviours and
rules. The transformation to other workflow states is done by moving
resources between the projects.

When attaching a workflow engine like JBPM following additional
features are available:

- Assignment of Tasks to VFS resources
- Dedicated task view

For details see chapter “Workflow Engine Interface”.

System Requirements
—————————————————————-

- OpenCms 7.0.2 or later
- bearingpoint commons modules:
opencmsmodule-com.bearingpoint.opencms.commons
opencmsmodule-com.bearingpoint.opencms.commons.springmanager

Installation
—————————————————————-

1. Build the workflow2 module
2. Deploy to OpenCms via module import mechanism
3. Create a database where to store the workflow states.
4. Declare your new database inside the workflow2 spring configuration:
a) Inside the OpenCms workbench switch to the root (“/”) view
b) Edit /system/modules/com.bearingpoint.opencms.workflow2/config/spring/DataSource.xml
c) Configure the database connection section (URL, user, password):

<bean id="workflow.dataSource">
<property name="driverClassName"><value>com.mysql.jdbc.Driver</value></property>
<property name="url"><value>jdbc:mysql://localhost:3306/workflow2?useServerPrepStmts=false&amp;jdbcCompliantTruncation=false</value></property>
<property name="username"><value>root</value></property>
<property name="password"><value>rootx</value></property>
</bean>

d) In some cases you also have to change the Hibernate settings within
this file (Especially when you are using an database other than MySQL)
e) Save and quit the editor. Publish the VFS resource.

5. Configure the opencms-workplace.xml for new context menu entries to approve/reject resources
respectively to create tasks if an workflow engine is attached. Inside the folder <patches>
you can find an example opencms-workplace.xml. There is also a patch to modify your OpenCms
sources within Eclipse. If you have a zipped OpenCms distrubution and/or a customized
workplace configuration it is recommended to do it manually:

a) To approve/reject resources/task this packages offers a new context menu entry.
To add the context menu action you have to add following definiton to your
workplace-config.xml:

<!-- WORKFLOW2 ITEM -->
<entry key="GUI_EXPLORER_CONTEXT_COPYTOPROJECT_0" uri="commons/movetoproject.jsp" rule="movetoproject"/>

Note: Unfortunately workflow for folder doesn’t work at the moment. For that
reason bypass the entry at the folder-section.

b) The workflow2 packages introduces a new menu item rule (MIR) which is called

com.bearingpoint.opencms.workflow2.cms.CmsMirPrBelongsToOtherInvisible

This rule deactives the regarding context menu items if the refering resource
doesn’t belong to the current project.

For example this type of rule would be
applied to the “Publish” functionality if the current user is just an author
and no publisher.

Insert the new rule at the menu rules section:

<menurule name="movetoproject">
<menuitemrule />
</menurule>

c) Furthermore all other context menu actions should not be available if the
resource belongs to another project. For that reason we have to insert the
“CmsMirPrBelongsToOtherInvisible” rule to all menu rule definitions
(note: it has to be at the first position if there are other MIRs).

6. Restart your OpenCms Server

Configuration
—————————————————————-

As an example workflow we create three workflow stages:
* Authoring (Default offline project)
* Review
* Approval

Each workflow stage needs a related OpenCms project.
This means you have to move to the OpenCms Administration View
and create those projects. Afterwards the Workflow has to be
defined:

1. Inside the CMS administration select workflow2 –> Show Project Flow
2. Here you click “New Workflow Stage”
3. Select Project “Authoring” and stage 0. Confirm by clicking Ok.
4. Go on the same way with the other projects. The stage number represents
the position of the project within flow.
5. When you are finished you should have following configuration:

Offline  —->  Review   —->  Approval
Stage 0           Stage 1         Stage 2

6. Now you can start pushing resources between the projects.
Just right-click on a resource within the explorer view and
select “Approve/Reject”.

Workflow Engine Interface
—————————————————————-

Task functionalities are just available if an 3rd party
workflow engine or an self implmented engine is attached.

To attach a third party workflow engine (e.g. JBoss JBPM)
the workflow2 module provides an interface to be implemented:

com.bearingpoint.opencms.workflow2.engine.I_WorkflowEngine.java

The implementation of that interface should contain simple delegation
methods to the engine.

2. Add the Workflow Engine Beans declaration to your spring-config.xml
a) Inside the OpenCms workbench switch to the root (“/”) view
b) Edit /system/modules/com.bearingpoint.opencms.workflow2/config/spring/spring-config.xml
c) Add following line to the other Spring Config Locations:

<SpringConfigFileLocation>opencms:WorkflowEngineBeans.xml</SpringConfigFileLocation>

d) Save & Exit editor + publish VFS resource.
3. Set the correct Workflow Engine Connector Class:
a) Inside the OpenCms workbench switch to the root (“/”) view
b) Edit /system/modules/com.bearingpoint.opencms.workflow2/config/spring/WorkflowEngineBeans.xml.xml
c) Update the class attribute with your desired class file:

<bean id=”workflow.workflowEngine”
>
</bean>
d) Save & Exit editor + publish VFS resource.
4. Restart OpenCms Server

FAQ
—————————————————————-
Q: When importing any of these OpenCms Modules I receive an error
message like “Caused by: com.mysql.jdbc.PacketTooBigException:
Packet for query is too large (1980691 > 1048576).”

A: The packet size of your database is to small! =) For example in
case of an MySQL database you have to change this value inside
the my.ini file. E.g. insert “max_allowed_packet = 16M” at the end
of your MySQL configuration.

Q: When switching to the Workflow2 Administration Panel I get an
error message saying: “java.lang.NullPointerException
at com.bearingpoint.opencms.commons.springmanager.SpringManager
.getBean(SpringManager.java:160)”
or “ERROR initializing SpringManager: Error creating bean..”

A: Possibly the configuration for your Workflow Engine connector is
not valid respectively the configured class file is not available.
If you don’t have any engine implementation you have to avoid the
loading of your engine bean definition (!) inside the spring-config.xml
For details see chapter “Workflow Engine Interface”.

Legal / License
—————————————————————-
This package is distributed under the LGPL and without any
warranty. For details see license.txt

Contact
—————————————————————-
If you have any concerns, questions or contributions contact me
at “david.trattnig (at) gmail (dot) com”

Flickr

Twitter