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:

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)

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!

34 Responses to Worklist

  1. Pingback: Worklist Overview | RedStack

  2. Pingback: Setting up the development environment for the Worklist | RedStack

  3. Pingback: Creating the worklist project | RedStack

  4. Pingback: Creating the domain layer for the worklist | RedStack

  5. Pingback: Building the skeleton worklist | RedStack

  6. Pingback: Setting up security for the worklist | RedStack

  7. Pingback: Implementing the Task List | RedStack

  8. Pingback: Page not found | RedStack

  9. Pingback: Implementing Process Task | RedStack

  10. Pingback: Implementing Task Initiation | RedStack

  11. Pingback: Running the worklist! | RedStack

  12. Pingback: Worklist update | RedStack

  13. Pingback: Viewing Task Attachments | RedStack

  14. Pingback: Process Instance List and Detail added to Worklist | RedStack

  15. Pingback: Adding Process Instance Audit Images to the Worklist | RedStack

  16. lfheckler says:

    Do you know if it is possible access the contents of a process data object from a specific instance, using the APIs? The idea is access the data by API to capture and export the form data filled by the user in a human task and updated by some other script action in the process.

    • Mark Nelson says:

      I’m not sure I understand exactly what you are trying to do… wouldn’t it be easier to have the process send the data you want out to whatever component you are talking about, rather than having that component use the APIs to find the data?

  17. Pingback: Adding attachment support to the worklist | RedStack

  18. Pingback: Mastering BPM Webinar Series | RedStack

  19. Pingback: Introductory presentation on custom worklist | RedStack

  20. I wanted to know whether all the set of functions under com.oracle.ateam.domain will work with 11.1.1.3 version , as I see here that you have mostly used version 11.1.1.4 and 11.1.1.5

    • Mark Nelson says:

      Hi, I started writing this sample on 11.1.1.3 and keep moving up with the new releases as they become available. Almost all of it would work on 11.1.1.3. The things that might not are getting the process audit image and adding an attachment.

  21. Hi,
    Thans for your great introduction about worklist APIs. Could you provide intro on how to use these APIs in .NET Client or is there any .NET compitable API suite?

    Thanks

  22. asnblogger says:

    Hi Mark,
    I have been able to render a tomcat web application page for a human task when an user initiates a task from the WorkList.
    I am able to update the outcome of the task from the web application. But, I am not able to succeed in updating the payload of the task.
    I used JAXB to generate the jaxb element for the payload XSD and then marshalled it to org.w3c.dom.Document.
    I get the Document.getDocumentElement and set it in the task.setPayloadAsElement (…).

    I tried using the ITaskService.mergeAndUpdateTask and updateTask methods but was unable to find the updated payload when i next viewed the payload on a read message screen.

    Is there something different I should be doing to update the payload element in the task and persist in the applicaiton?

    • asnblogger says:

      Hey Mark,

      I just found what the problem is.
      It was not that the API was not updating the payload element.
      But, it was the that setPayloadAsElement expects a default root node “payload” all the time and my XML generated using JAXB was not having it.

  23. Pingback: Using the TaskQueryService from .Net (C#) | RedStack

  24. asnblogger says:

    Hi Mark,

    I was able to develop an external GUI application and integrate it with the the BPMS workspace.
    The web application works well when deployed on the weblogic (soa_server). But when I integrate with the gui application deployed on a tomcat, then I get an exception when I get the WorkFlowServiceclient.
    Exception:
    java.lang.NoClassDefFoundError: oracle/j2ee/ws/common/jaxws/ServiceDelegateImpl
    /////////////////////////////

    I get the workflowserviceclient using:
    WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.REMOTE_CLIENT, properties,null);

    and the properties set are:
    properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.SOAP_END_POINT_ROOT,”http://localhost:8001″);
    properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_PROVIDER_URL,”t3://localhost:8001″);
    properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS,””);
    properties.putIWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL,””);

    Can you please let me know if I am doing it right and if you know what needs to be corrected to get it working?

    Thanks,
    Abhi

    • Mark Nelson says:

      Looks like you are just missing some jar file. oracle/j2ee/ws/common/jaxws/ServiceDelegateImpl is in /oracle_common/webservices/wsclient_extended.jar

  25. Pingback: New build of custom worklist for BPM 11.1.1.5 ‘Feature Pack’ patched systems | RedStack

  26. Pingback: Updating a task from .Net | RedStack

  27. Pingback: Worklist build for 11.1.1.6 (PatchSet 5) released | RedStack

  28. Pingback: Manipulating Human Tasks (for testing) by Mark Nelson | SOA Community Blog

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s