26 Integrating the Worklist Service

This chapter describes how to integrate the Worklist service into your application. Worklists enable users to view and take action on all tasks and notifications from a BPEL (Business Process Execution Language) server all in one place.

This chapter includes the following sections:

For information about managing and using the Worklist service, see:

26.1 Introduction to the Worklist Service

The Worklist service enables you to show Business Process Execution Language (BPEL) Worklist items assigned to the currently authenticated user. The BPEL Worklist items are open BPEL tasks from one or more BPEL Worklist Repositories to which your application is connected. The Worklist displays BPEL Worklist items that are a result of a task invoked as part of a BPEL Workflow process, or are a result of a message being sent to the Worklist channel on the Oracle User Messaging Service.

This section contains the following subsections:

26.1.1 Understanding Worklists

The Worklist service provides a personal, at-a-glance view of business processes that require your users' attention. These can include a request for document review or other types of business processes that come directly from your enterprise applications.

Worklist items come from a variety of sources. Some Worklist items are kicked off by events that are associated with an externally defined workflow. A workflow maps the route an item follows once an event kicks off. This type of workflow is defined in a Worklist BPEL server, such as Oracle BPM Worklist.

Messages, alerts, and notifications might also come from the User Messaging Service (UMS). The Worklist task flow includes a control for accessing messaging preferences on this server. Use these controls to specify the channels over which to receive Oracle User Messaging Service messages and to define messaging filters.

See Also:

Oracle Fusion Middleware User's Guide for Oracle WebCenter for more information about the service at runtime.

26.1.2 Requirements for the Worklist Service

To use the Worklist service, you must have a BPEL server installed. For information on installing BPEL for the Worklist service, see the "Back-End Requirements for the Worklist Service" in the Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

For the Worklist to properly function, it must reside on a secured page, as the service uses the currently authenticated user to access the BPEL server. If the page or application that contains the Worklist service is not secured, you will encounter exception errors.

26.1.3 What Happens at Runtime

At runtime, the Worklist task flow fetches latest Worklist workflow items from BPEL workflows configured in the BPEL server. For more information, see the chapter "Working with the Worklist Service" in Oracle Fusion Middleware User's Guide for Oracle WebCenter.

To get a list of the items assigned to a user, the Worklist service uses the WebService access function of the public BPM client API. The Worklist service uses SAML authentication to authorize the logged-in user to fetch the list of latest items from the BPEL repository. The Worklist service fetches 25 most recent items for each Worklist connection, and determines the order of these items by using a predicate on the TaskQueryService API. For more information, see "Building a Custom Worklist Client" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Figure 26-1 shows the Worklists service at runtime.

Figure 26-1 Worklist Service at Runtime

Description of Figure 26-1 follows
Description of "Figure 26-1 Worklist Service at Runtime"

26.2 Basic Configuration for the Worklist Service

This section describes how to set up a connection for the Worklist service and add the task flow to your custom WebCenter application.

This section contains the following subsections:

26.2.1 Setting up Connections for the Worklist Service

To use the Worklist service, you must establish a connection to one or more BPEL servers. This section describes these connections and how to create them in a custom WebCenter application. Worklist Service Connections

The Worklist service relies on a BPEL server. Once you create a connection using the Create Worklist Connection dialog, the connection is registered in your application's connections.xml and referenced in your application's adf-config.xml. You can see the connections to your BPEL Worklist Repositories in the Application Resources pane.


While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter. How to Set Up Connections for the Worklist Service

The Worklist service provides a task flow that you can add to your application at design time or at runtime. Before you can run the task flow, you create a connection from your application to a BPEL server.


The application you use must be prepared for service consumption. For information about doing so, see Chapter 4, "Preparing Your Application for Oracle WebCenter Services."

To set up the connection for the Worklist service:

  1. In the Application Resources panel for your application, right-click Connections, then choose New Connection> Worklist.

  2. In the Create Worklist Connection dialog, choose whether to create the connection in the Application Resources (only the current application can use this connection) or IDE Connections (other applications you create can use the same connection).

  3. In the Connection Name field, enter a name for your connection. This name will be used as the display name of the Worklist server.


    At runtime, when users view their worklist items, they can choose to group the items by "Worklist Server." The Worklist Server name used is the name you enter in the Connection Name field.
  4. In the URL field, enter the location of your BPEL/SOA server, such as http://bpel.example.com. This is the URL for the managed server running the SOA processes.

  5. Select the SAML Token Policy URI to use for this server (Figure 26-2).

    SAML (Security Assertion Markup Language) is an XML-based standard for passing security tokens defining authentication and authorization rights. An attesting entity (that already has trust relationship with the receiver) vouches for the verification of the subject by method called sender-vouches. Options available are:

  6. Click Test Connection to validate the URL.

  7. Click OK.

    The new connection displays in the Application Resources panel under Connections.

26.2.2 Adding the Worklist Service at Design Time

This section describes the Worklist task flow and how to add it to your application. Worklist Service Task Flows

There is one task flow associated with the Worklist service, called "Worklist." You can find this task flow in the WebCenter Services Catalog in the Resource Palette. How to Add the Worklist Service to your Application

You can add the Worklist service to your application before or after you have created your connection. However, you must set up your connection before you run the service.

To add the Worklist task flow to your application:

  1. Follow the steps in Section 4.1.1, "How to Prepare Your Application to Consume Services" to implement security and create a customizable page in your application.

  2. Open the page where you wish to add the Worklist task flow.

  3. In the Resource Palette, in the My Catalogs pane, open the WebCenter Services Catalog, then open the Task Flows folder.

  4. Drag the worklist task flow onto the desired region on the page, then choose Region from the pop-up list. The task flow displays on the page. For example, in the Source view, you will see Figure 26-3.

    Figure 26-3 Worklist Task Flow in the Page Source

    Description of Figure 26-3 follows
    Description of "Figure 26-3 Worklist Task Flow in the Page Source"

  5. Save your project, then run your page to a browser. The Worklist service displays in your browser.

26.2.3 Setting Security for the Worklist Service

The Worklist service displays the tasks for the currently authenticated user. So, for users to store and retrieve Worklist tasks on the BPEL server from your application, you must set up security on the application (as described in Section, "Implementing Security for Services"). The user names need to either exist in a shared user directory (LDAP), or set up similarly (same user name) on both the custom WebCenter application and the BPEL Server. For example, if the user rsmith needs to use the Worklist service in your custom WebCenter application to store and retrieve tasks from the BPEL server, you must ensure that the user rsmith exists on both the BPEL server and within your application.

To enable users to perform actions on assigned Worklist tasks, you can configure SSO. If you do not configure SSO, the users will be prompted to log into the Worklist Task Details page on the BPEL server. For more information, see the Oracle Fusion Middleware Security Guide.

Only authenticated users can view Worklist tasks on the BPEL server to which they have permissions to view. If the application end user does not supply appropriate credentials, or if the page containing the Worklist service is not secured, she will not see any Worklist items stored on the BPEL server and exception errors may occur.

26.3 Advanced Information for the Worklist Service

The Worklist service collates all the Worklist items for the authenticated user from all connections in your application defined for the Worklist service. You can use the create connection method described in Section, "How to Set Up Connections for the Worklist Service" to create additional connections, or right-click the connection name in the Application Resources list and choose Delete to remove a connection.