Worklist

We get a lot of questions from customers about how to build custom worklist interfaces for Oracle BPM Suite 11g (and SOA Suite 11g), so much so that we decided to build a sophisticated sample and make it available as a tutorial and example that can be taken and extended to suit your needs.

Update:  We have now published several updates to this sample, please read details later in this article.

Chapter 31 of the Oracle SOA Suite Developer’s Guide (read it here) gives some starting points.  You should also read Chapter 32 (here) which gives a good idea of the functionality provided by the APIs and web services.  The Workflow Services Java API Reference for Oracle SOA Suite (here) is also a very useful reference when setting out to build a custom worklist.

The first question we had to answer was what functionality to include in the sample.  We decided (for ‘Version 1.0’ at least) to include the following:

• Integrated with WebLogic Server security,
• Show a list of tasks,
• Filter the list of tasks by assignee and by status,
• Show details for a task, including the payload,
• Add a comment to a task,
• Process a task, i.e. take a ‘custom’ action – those defined in the human task definition, or a ‘system’ action like ‘escalate,’ ‘reassign,’ ‘suspend,’ etc.,
• Initiate a task/process using the task form.

The second question was what framework and/or technology to use.  Of course, Oracle BPM Suite provides rich support for Oracle Application Development Framework (ADF).  ADF provides great benefits in terms of developer productivity and a comprehensive set of AJAX-enabled components that support sophisticated UI capabilities like lazy loading and paging data in tables, partial page refresh and charting.  The out-of-the-box BPM Workspace is written in ADF, so for people extending and customizing the workspace, ADF is the toolkit of choice.  There is a great deal of high quality information available on the web about ADF already, including our growing collection of ADF posts.

However, some organizations use a different framework for various reasons and are in need of a sample describing how to build custom worklist applications using the public worklist APIs.  For example, they might use predominantly .Net technology, or they may have an existing application written in another framework such as Struts or Spring that they want to extend to include BPM functionality.  This sample is intended to illustrate the use of the BPM Worklist API from third party UI frameworks and here we have chosen Spring to demonstrate how to build a worklist interface with a toolkit other than ADF.

We felt that the sample would be useful to the most people if we chose a commonly used web framework, so that we can spend more time showing how to use the APIs to deliver the BPM functionality into any web framework that you may choose to use.  Note also that the sample is built in such a way that all of the logic that interfaces with BPM is contained in the com.oracle.ateam.domain package.  You could replace the Spring Controllers and Views with another web framework relatively easily and reuse the ‘business logic’ in this package.

The sample is built with Spring Web MVC 3.0.5 with JSP and JSTL for the view.  We used Maven 2 to manage the dependencies, building and deploying and Subversion for source control.  Java (obviously) for the language and we deployed to WebLogic Server 10.3.4.  The sample is written against the 11.1.1.4 release of Oracle Fusion Middleware.  All development was done on Mac OS X 10.6.  Our test servers ran on Oracle Linux 5.5.  Everything is 64 bit.  Update: From version 1.3 onwards, all development and testing was done on Windows 2008 Server R2, also 64-bit.

The sample is presented in three ways:

• As a ‘walkthrough,’ or a detailed explanation, of how the worklist was built, here on the RedStack blog, which you can follow to learn how to build your own custom worklist,
• As a set of code that you can check out and use as an example or a head start on building your own custom worklist, and
• As a WAR file that you can deploy on your own server to experiment with.

Additionally, I did a presentation at the InSync11 conference which is organised by Oracle User Groups that provided an overview of the sample.  I am sharing the presentation material here for those who may be interested but were not able to attend the conference.

The Walkthrough

The walkthrough is presented as a series of posts, you should probably work through these in the order presented:

• An overview of the application and its design/architecture
• Preparing your development environment
• Creating the skeleton project and setting up the POM
• Creating the ‘domain’ layer to wrap the BPM APIs and a few utility classes
• Establishing the skeleton pages, page fragments (header, footer) and style (CSS)
• Setting up security and writing the Login and Logout Controllers
• Creating the Task List Controller and View
• Creating the Task Details Controller and View
• Creating the Add Comment Controller
• Creating the Process Task Controller
• Creating the Controllers and View to Initiate a Task
• Deploying and running our worklist!

But wait, there’s more…

This is not the end of the story!  We are planning to keep adding functionality to the worklist, which we will present in a series of additional posts covering various topics like the following:  (we will update this page with links to each new post as we publish them)

• Viewing a list of attachments for a task, (added in 1.1)
• Downloading an attachment, (added in 1.1)
• Adding attachments to a task, (added in 1.5)
• Displaying a list of process instances, (added in 1.3)
• Displaying details of a process instance, (added in 1.3)
• Displaying the process instance audit image, (added in 1.4)
• Finding the process instance that a task belongs to, (added in 1.3)
• Find the other tasks that are part of the same process instance, (added in 1.3)
• An experimental rendering for mobile devices (browser not native) using JQuery Mobile,
• Creating a composite with some test Human Tasks to use to test the worklist,
• Adding the ability to invoke processes/composites as (web) services, as opposed to using an Initiate Task in the process,
• Using Hudson to provide continuous integration for the worklist,
• and so on.

We are also planning to present the sample in another common web framework – Microsoft Silverlight.  This would give us the opportunity to show the differences in our approach when using the SOAP client instead of the REMOTE EJB client that is used in this sample.

Do you have other ideas or suggestions?  Let us know by leaving a comment!

Getting the Code

You can check out the code directly from our Subversion repository using the following command:

# svn checkout https://svn.java.net/svn/bpmworklist~worklist/tags/VERSION-1.5

You can update that command with the version number that you want at the end, e.g. VERSION-1.4.

We are still working on enhancements to the Custom Worklist, and you can also check out our latest code from our Subversion repository using the following command.  Note that the latest code may contain some bugs 🙂  If you want a stable version, you should use the one referenced above.

# svn checkout https://svn.java.net/svn/bpmworklist~worklist/trunk

Alternatively, you can browse the Subversion repository here.

If you are planning to build the application yourself, you will also need to download the Process Audit Image Helper JAR file, which is a dependency.  Read this article to learn about the use of this library in the application.

You may also want to download a Maven population script for Windows or Unix-like systems that will add all of the necessary libraries from your Oracle Home into your Maven repository for you.  Warning:  I have not thoroughly tested those scripts, please check the results and let me know if you have issues.

Javadoc for the code is also available for download below.

[Thanks to Judy Nie for testing the Subversion checkout and giving feedback.]

Downloading the Deployable Application

If you just want to install the sample and have a play with it, you can download the DEV WAR file (with logging and JSP recompile turned on) or the PROD WAR file (with logging and JSP recompile turned off) from the links below. You can install it using the WebLogic Server console.  You need to install it onto the managed server that you are running BPM 11g on.  This is normally called soa_server1 in a standard installation or AdminServer if you did a developer’s install (see here).

Version	DEV WAR	PROD WAR	Javadoc	Notes
1.0	1.0-dev	1.0-prod	1.0	Initial release, as per the walkthrough. Requires BPM 11.1.1.4.
1.1	1.1-dev	1.1-prod	1.1	View and download attachments from Task Detail page, properly handle over 200 tasks in the Task List page, a little bit of CSS tidy up. Requires BPM 11.1.1.4.
1.2	1.2-dev	1.2-prod	1.2	Requires BPM 11.1.1.5. Adds a sample chart.
1.3	1.3-dev	1.3-prod	1.3	Requires BPM 11.1.1.5. Adds process instance list view and process instance detail. Demonstrates how to get a list of tasks for a process instance and how to get the process instance that a task belongs to.
1.4	1.4-dev	1.4-prod	1.4	Requires BPM 11.1.1.5. Adds process instance audit image and proper filtering on the process instance list page.
1.5	1.5-dev	1.5-prod	1.5	Requires BPM 11.1.1.5. Adds the ability to upload and attach a new attachment to a task.
1.5.FP	1.5-dev	1.5-prod	1.5	Same as version 1.5, but compiled with the ‘Feature Pack‘ patch installed.
1.6	1.6-dev	1.6-prod	1.6	Same as version 1.5, but compiled for BPM 11.1.1.6.

You will then be able to access the worklist on your server at the URL:

http://yourserver:8001/worklist

Note that you will need to substitute in your own host name and port number.  8001 is the default for a normal install and 7001 for a developer install.

Log on using any valid WebLogic user.  You will need to have some human tasks in your system, or there will not be much to see…

Acknowledgements

When you set out to develop a sample like this, there are many people who help, support, encourage and inspire you in those efforts.  In addition to all those who work on the products themselves and the product documentation, I would like to thank those who take the time to write blog posts and answer questions on user forums about Spring, JSTL, Maven, and, of course, Oracle Fusion Middleware.  We can all use a little help from time to time.  Thank you for sharing your experiences.

I would also like to thank the authors of Professional Oracle WebLogic Server which was a guide and companion to building Spring applications on WebLogic Server, and (in alphabetical order) my colleagues Steve Button, Manoj Das, Ted Farrell, Mohan Kamath, Yogeshwar Kuntawar, Duncan Mills, Ali Mukadam, Mikael Ottoson, Robert Patrick, Ravi Rangaswaramy, Mahesh Rao, Dave Read, Dave Shaffer, Meera Srinivasan, and all the Oracle folks around the world who help and support our BPM customers who are interested in building a custom worklist or adding some BPM functionality into their applications and portals.

If I have forgotten anyone, the mistake is mine and please accept my humble apologies.

Find a Problem?

If you happen to find a problem in the sample, please feel free to leave a comment here to let us know.  The sample is provided ‘as is’ without support of any kind, but if you let us know of any issues we will try to address them when we are able to.

Enjoy!