Workflow

The workflow portlet allows a user to define any number of simple to complex business processes/workflows, deploy them, and manage them through a portal interface. The power of this portlet is that it allows users to create forms-based data entry applications that are fully integrated with Liferay's permissions system. They have knowledge of users, groups, and roles without writing a single line of code—it only requires the creation of a single XML document.

The portlet relies on Apache ServiceMix or Mule to function as an Enterprise Service Bus (ESB) that acts as a broker between the portal and a workflow engine. Essentially, the portal provides a generic interface through which workflow services are requested via normal HTTP calls. The requests are routed through the ESB which in turn calls a workflow engine implementation that the user has defined in the ESB configuration. By default, Liferay provides an implementation of JBoss' jBPM workflow engine.

Installation and Test

Though the workflow portlet is installed in Liferay by default, it is nonfunctional without the jBPM and one of the ESB plugins. These are conveniently located on the web tab of the Plugin Installer portlet. You will need to have jBPM and one of the ESB plugins installed. At the time of this writing, we recommend the Mule ESB plugin, as the ServiceMix plugin is currently being reworked.

Once you install the plugins, follow these steps to get everything configured properly:

• Make sure the following property in portal-ext.properties is set to the following:

  jbi.workflow.url=http://localhost:8080/mule-web/workflow

• Restart your application server if you needed to change the above property.

• Login to the portal as the portal administrator. The default credentials are test@liferay.com/test.

• Add the Workflow portlet to a page.

• Click on the Definitions tab.

• Click on the Add button.

• Copy and paste the contents of jbpm-web.war/WEB-INF/definitions/datatypes_definition.xml into the text area and click the Save New Version button.

• Click on the Add Instance icon.

• From the Instances tab, click on the Manage icon next to Enter data.

• Fill out the form and click the Save button; alternatively, you can test the various error checking capabilities by inputting incorrect values and clicking the Save button.

• Eventually, enter correct values and click the Save button.

• From the Instances tab, click on the Manage icon next to View Data.

• Confirm that all the data was entered correctly and click the Finished button.

• Confirm that the instance is now in the End state.

Using Different Databases

The default implementation of jBPM uses an HSQL database found in jbpm-web.war/WEB-INF/sql/jbpm.*. To change the location of the HSQL database, change the value of the hibernate.connection.url property in jbpm-web.war/WEB-INF/classes/hibernate.cfg.xml. The location is relatively addressed from wherever the startup script for your server is located.

To use a database other than HSQL, first create the database schema using one of the SQL create scripts supplied in the jbpm-web.war/WEB-INF/sql directory. Then uncomment the corresponding hibernate connection properties block in jbpm-web.war/WEB-INF/classes/hibernate.cfg.xml.

Technical Explanations

Since the default implementation of the workflow portlet relies heavily on the capabilities of jBPM, this section gives a technical overview of jBPM and explains how it integrates into Liferay using jBPM Process Definition Language (JPDL) formatted XML files. It does not, however, give an in depth view of jBPM. For that, please refer to the jBPM user guide (http://docs.jboss.com/jbpm/v3/userguide).

Process Definitions

Before the workflow portlet can be used, business processes must be defined. Business processes in jBPM are defined by XML documents known as process definitions which are written in jBPM Process Definition Language (JPDL). This XML format specifies entities such as the process roles (known as swimlanes), the various states in the process (known as nodes), the tasks associated with each node, the roles associated with each task, the transitions from one node to the next, the variables associated with each task's form, the external actions executed on entry or exit of a node, and many others. For an in depth understanding of process definitions and JPDL, refer to JBoss' jBPM user guide at the link above.

There are three sample process definition XMLs that are packaged with the portlet. They can be found in jbpm-web.war/WEB-INF/definitions. We used one in the quick start section above to create a sample workflow. An explanation of each is included below.

Integrating with Users, Communities, and Roles

In JPDL, there is the notion of process roles called swimlanes. Swimlanes can be associated with Liferay users, communities, and roles via the IdentityAssignmentHandler class.

<swimlane name="approver">

<assignment class="com.liferay.jbpm.handler.IdentityAssignmentHandler" config-type="field">

<type>user</type>

<companyId>10095</companyId>

<id>10112</id>

</assignment>

</swimlane>

In the XML above, the approver swimlane is associated with the Liferay user that has a User ID of 10112 and belongs to a Company ID of 10095. You can also associate a Liferay user with a swimlane by email address as shown in the following XML snippet.

<swimlane name="shipper">

<assignment class="com.liferay.jbpm.handler.IdentityAssignmentHandler" config-type="field">

<type>user</type>

<companyId>10095</companyId>

<name>test.lax.2@liferay.com</name>

</assignment>

</swimlane>

In the XML above, the shipper swimlane is associated with the Liferay user that has an email address of "test.lax.2@liferay.com" and belongs to a Company ID of 10095.

<swimlane name="salesman">

<assignment class="com.liferay.jbpm.handler.IdentityAssignmentHandler" config-type="field">

<type>community</type>

<companyId>10095</companyId>

<id>3</id>

</assignment>

</swimlane>

In the XML above, the salesman swimlane is associated with any Liferay user that belongs to a Community with the Group ID of 3 (which defaults to the Support community if you are using the embedded HSQL database that comes with the Liferay Portal bundles) and Company ID of 10095. In other words, the salesman swimlane is assigned to the pool of Support users. If one of these users were to manage a salesman task, he/she would automatically be assigned to all other salesman tasks in the workflow.

<swimlane name="accountant">

<assignment class="com.liferay.jbpm.handler.IdentityAssignmentHandler" config-type="field">

<type>community</type>

<companyId>10095</companyId>

<name>Support</name>

</assignment>

</swimlane>

The XML above shows an alternative way to associate the accountant swimlane with the Support community using the actual community's name. Since community names must be unique per Company ID, this format accomplishes the same results as the previous XML.

<swimlane name="user_admin">

<assignment class="com.liferay.jbpm.handler.IdentityAssignmentHandler" config-type="field">

<type>role</type>

<companyId>10095</companyId>

<id>1001</id>

</assignment>

</swimlane>

<swimlane name="user_interviewer">

<assignment class="com.liferay.jbpm.handler.IdentityAssignmentHandler" config-type="field">

<type>role</type>

<companyId>10095</companyId>

<name>User Interviewer</name>

</assignment>

</swimlane>

The two XML snippets above are very similar to the Group XML snippets. Both associate their respective swimlanes with a role, but the first XML does so using the Role ID, and the second XML does so using the role's unique name.

Data Types and Error Checking

Currently, jBPM doesn't have support for variable data types. However, data types have been dealt with in the workflow portlet by incorporating them into the names of the controller variables. The table below shows the data types supported by the portlet as well as the syntax for the variable names:

Data Type

Syntax

Description

Checkbox

checkbox:name:checkedValue

name: the caption next to the checkbox

checkedValue = the value assigned to the variable if the checkbox is checked

Date

date:name

name: the caption next to the date selector object

Email

email:name

name: the caption next to the text input field

Number

number:name

name: the caption next to the text input field

Password

password:name

name: the caption next to the text input field

Phone

phone:name

name: the caption next to the text input field

Radio Button

radio:name:option1,option2,…*

name: the caption next to the radio buttons

option1,option2,…* : a comma-delimited list of options that represent the different radio button options

Select Box

select:name:option1,option2,…*

name: the caption next to the select box

option1,option2,…* : a comma-delimited list of options that represent the different options in the select drop-down

Text

text:name

name: the caption next to the text input field

Textarea

textarea:name

name: the caption next to the textarea input field

Note that for all name and option values, the values should be entered in the XML in lowercase with hyphens used between words:

radio:are-you-hungry:yes,no,a-little-bit

In addition, you should register the corresponding display values in the Language.properties file:

are-you-hungry=Are you hungry?

yes=Yes

no=No

a-little-bit=A little bit

This will ensure that the values are displayed correctly in the portlet to the user.

By default, all variables are readable and writable by the user. Therefore, they can be defined as follows:

<variable name="textarea:comments" />

However, if variables should only be readable or writable, or if variables are required, these must be specified in the variable definition:

<variable name="text:name" access="read,write,required" />

<variable name="date:birthday" access="read" />

Variables of data type Date, Number, Email, and Phone are validated in the service call. Also, required fields are validated to ensure a value of some kind was submitted. If invalid values are submitted, the user is returned to the original form and error messages are displayed next to the invalid input fields.

Refer to the sample definition jbpm-web.war/WEB-INF/definitions/datatypes_definition.xml for examples of all data types in use in a single form.

JBoss also provides a graphical JPDL editor which is implemented as an Eclipse plugin. This editor allows you to design workflows graphically, rather than using an XML editor. You can find this tool at http://www.jboss.org/tools.

Illustration 79: The JPDL editor from JBossSample Process Definitions

The best way to understand JPDL is to look over the 3 sample XML files included with the workflow portlet. They can be found in jbpm-web.war/WEB-INF/definitions/. Below is a quick summary of each:

datatypes_definition.xml – a good guide to follow to understand how to use each of the data types described in the section above

holiday_definition.xml – a simple workflow that allows an employee to make a holiday request with a start and end date, and then a manager can either approve, reject, or send the request back for review

websale_definition.xml – a more complex workflow that emulates an online auction site in which control of the workflow passes through various roles. It is the most complicated of the 3 workflows, but it demonstrates almost all of the BPM features offered by jBPM

Notes:

• The JPDL definition XMLs can be created through a graphical design tool offered by JBoss, but that is beyond the scope of this document (see http://docs.jboss.com/jbpm/v3/gpd for a detailed explanation) and is also beyond the scope of the portal.

• For nodes that have tasks associated with them, each of the variables in the controller will be converted to a form element that the user must update.

• For nodes that have tasks associated with them, each of the transitions out of the node is represented as a button in the task's form. The transition's name attribute should always be in lowercase with hyphens between words and registered in Language.properties. The display value is used as the button's name.

• Many of the action handler classes found in the com.liferay.jbpm.handler package are just place holders that output relevant text to the console. Conceivably, these classes could perform operations such as sending out emails, initiating batch processes, updating legacy systems, etc.

• The websale workflow demonstrates the following jBPM concepts, all of which are discussed in further detail in the jBPM user guide (http://docs.jboss.com/jbpm/v3/userguide):

• • Events

  • Beanshell scripting

  • Swimlanes

  • Tasks

    • Assigment(User/Pool)

    • Controllers

    • Variables

    • Timers

  • Node Types

    • State

    • Task

    • Fork

    • Join

    • Decision

  • Transitions

  • Actions

Warning Messages

If you have warning messages turned on for your server, in your console you may see some variant of the following message output several times when jBPM is called:

WARN [org.hibernate.engine.StatefulPersistenceContext] Narrowing proxy to class org.jbpm.graph.node.TaskNode - this operation breaks ==

According to the following post on the JBoss forums (from Koen Aers, one of the key contributors to the jBPM project), this is not an error and is not of significance. He explains the reason this warning is thrown here: http://www.jboss.com/?module=bb&op=viewtopic&t=73123. Basically, the issue boils down to Hibernate doing lazy loading of the class. After a query, a collection is returned which holds a collection of stubs of the class. When a particular instance is retrieved, Hibernate goes and gets it from the database and replaces the stub with an actual instance, thereby breaking the == operator.

Administration

Once you have defined your business processes by successfully writing process definitions for them, the next step is to deploy your business processes. Once they are deployed, users can manage the life of each process instance as control is passed from one role to the next. This section is meant for end users who will actually be executing predefined process definitions.

Deploying Workflows

Once the user logs in to the portal and adds the workflow portlet to her page, he or she will see something similar to the following:

Illustration 80: Default view of the Workflow PortletIf she clicks on the "Definitions" tab, he or she will see the following:

Illustration 81: Workflow DefinitionsThe Definitions tab displays all of the workflows that have been deployed in the system. To deploy a workflow, click on the Add Definition button. The user will see the following screen:

Illustration 82: Adding a Workflow DefinitionAt this point, the user can paste in the contents of a definition XML (see jbpm-web.war/WEB-INF/definitions for examples) and click the Save New Version button. If the XML is invalid, an error message will be displayed. If the XML is valid, it will be deployed, the user will be returned to the Definitions tab, and a success message will be displayed.

Because business processes may change over time, every version of the workflows is maintained. To edit an existing version, click on the Edit icon next to the definition name. Update the XML in the text area, and click the Save New Version button. The new version number will be incremented by 1 from the previous version. To start a new instance of a workflow definition, click on the Add Instance icon. A new instance will appear on the Instances tab. To view all the instances of a particular definition, click on the View Instances icon. Finally, the user can also search for a definition by name using the Definition Name input box.

Managing Instances

After a definition is deployed and an instance of that definition is started, it is up to the user to manage the life cycle of the instance. Instance management is controlled from the Instances tab. Below is an example of what the user might see:

Illustration 83: Workflow InstancesThe Instances tab displays every instance of every version of every workflow deployed in the system. They are listed alphabetically by Definition Name followed by Start Date in descending order. The search form at the top of the screen allows the user to find specific instances to manage. In particular, the Hide instances that have already ended check box allows the user to display only active, running instances. The date ranges also allow the user to search by Start Date and/or End Date (NOTE: Date ranges are inclusive of the day. For example, if the Start Date range was set to January 23, 2008 – January 23, 2008, then only instances that were started between January 28, 2008, 12:00am to January 28, 2008, 11:59pm would be displayed). The first row for each instance describes the state of the instance. Any subsequent rows in the instance define tasks associated with the current state. Often times, the current state and current task have the same name. In the example screen shot above, notice that web sale version 1.0 is currently in the "Perform shipping and payment" state, and it has two outstanding tasks associated with it – "Wait for shipment to be delivered" and "Wait for money."

The right-most column in the results table displays what actions the current user can perform on the given instance in its current state. The table below shows all of the possible actions and what each means:

Action

Explanation

Blank

3 possibilities:

• The user doesn't have the appropriate role/swimlane to perform an action on the instance in its current state

• The user doesn't have permissions to perform an action

• The instance has already ended

Manage icon ()

The user directly has the appropriate role/swimlane to perform an action or the user belongs to a group which has the appropriate role/swimlane. If the user clicks on the "Manage" icon, she will be taken to a form which must be submitted to complete the task. See section 3.3 for more details

Signal icon ()

The instance is currently in a wait state and must be "signalled" to continue. Typically, signals come from eternal processes (e.g., the arrival of a package, the successful update of a legacy system, etc.) and are not manually entered by a user. However, in the case that user intervention is required, the "Signal" icon is available.

Waiting on sibling tokens to complete

This only occurs when the process has forked into multiple subprocesses. In order for the main process to continue, all of the subprocesses must complete. As each of the subprocesses completes, they will go into this state. Once all subprocesses complete, the main process will continue like normal.

Managing Tasks

Task management is controlled from the "Tasks" tab. Below is an example of what the user might see:

Illustration 84: Workflow TasksThe Tasks tab displays every task that has either been assigned directly to the user or to the group/role pool that the user belongs to. They are listed by Create Date in ascending order, and the tasks assigned directly to the user are listed before the tasks assigned to the user's pool (if the Assigned To column is blank, that means the task is open to the pool). The search form at the top of the screen allows the user to find specific tasks to manage. In particular, the Hide tasks that have already ended check box allows the user to display only active tasks. The date ranges also allow the user to search by task Create Date, Start Date, and/or End Date. The user can also choose to only display tasks assigned directly to her, tasks assigned to her pool, or all tasks assigned to either by using the Assigned To drop-down.

The right-most column in the results table displays what actions the current user can perform on the given task. It will either be blank or the Manage icon. The logic to determine which of these will be displayed is exactly the same logic described in the table in the section above labeled Data Types and Error Checking.

If the user clicks the Manage icon, a form similar to the following will be displayed:

Illustration 85: Workflow FormThese task forms are generated from the control variables associated with the task and defined in the definition XML. Depending on the data type, the corresponding element is created in the form. Required fields are denoted by a red asterisk. If the user submits the form with invalid data, she will be returned to the form with error messages next to each of the invalid fields. If all data is valid and the user submits the form, she will be returned to the Tasks tab with a success message displayed.

Future Enhancements

Logging

Currently, the workflow portlet has no notion of logging other than the ability to review all of the tasks that a user has assigned to them or has completed. However, jBPM provides rather robust logging functionality so administrators/users can monitor every action that has ever been taken in a particular workflow.

The only reason logging functionality has not been built out in the current release is because the Liferay development team is not sure what the most effective logging metrics would be to the end user. If you or your organization has logging requirements, please submit them to the Liferay Forums, and we will review those requirements for possible inclusion in future versions of the Workflow portlet.

Customizable Front-End

Though the workflow portlet's strength is that it can provide a forms-based data entry application virtually on-the-fly, it is obvious that there is not much control over what the forms look like when they are rendered by the portlet. To address this concern, the Liferay development team plans to create style sheets and templates that can be applied to the vanilla forms. The functionality would be very similar to how XSL style sheets are currently applied to Journal Articles in the Liferay Journal Content Management System. This enhancement would give organizations flexibility in layout and UI design of their forms.

File Upload Data Type

There have already been several requests to add a file data type to provide a means for users to upload files that are associated with workflow tasks. This will definitely be a future enhancement.

Frequently Asked Questions

How do you write a new process definition?

The best way to learn how to write a new process definition is to use one of the sample definition XMLs (found in jbpm-web.war/WEB-INF/definitions/) as a starting point. In particular, websale_definition.xml demonstrates most of the BPM features offered by jBPM. For an exhaustive explanation of JPDL, visit JBoss' documentation at http://docs.jboss.com/jbpm/v3/userguide/jpdl.html. There is also a graphical JPDL designer available at http://labs.jboss.com/jbossjbpm/downloads.

Why are there "Duplicate File" exceptions when I change databases for jBPM?

Since we are using ServiceMix as the service broker for our workflow implementation (by default, we are using jBPM), we cannot rely on the workflow engine to maintain versions of our process definitions. Therefore, we maintain the process definition XMLs as system documents in our document library. The XMLs are named based on their definition IDs, and the definition IDs are maintained in the jBPM database. Therefore, if you were to switch databases to a new instance, the definition IDs would also be reset, and when the system tries to store the process definition XML, it will find a duplicate XML already exists. The only way to ensure that this exception does not occur is by clearing out the <User Home>/liferay/jackrabbit folder before switching databases. However, be warned that this will delete ALL the files that are stored in your Document Library. It is recommended that once you decide on a jBPM database that suits your needs, you should only use that database.