Integrating BPEL with the CRM Worklist

This chapter provides an overview of business process worklist entries and discusses how to:

Set up outcomes.
Complete business process worklist entries.

Understanding Business Process Worklist Entries

This section discusses:

Worklist integration.
Outcomes.
Worklist entry completion.

Worklist Integration

A BPEL business process is composed of a list of ordered tasks. These tasks, called activities, can be automated, which means that they can be completed by calling appropriate web services (synchronous or asynchronous) that are supplied by internal or external systems. There are also manual tasks that need to be processed by CRM users. For example, in a business process that fulfills hardware requests for company employees, getting approval from employees' managers is often a necessary step. The approval can be verbal, in the form of an email, or a change of status in a system, each of which is a user intervention.

The CRM system provides business processes with the ability to manage manual tasks through CRM worklists. Using the web service provided by PeopleTools, CRM allows the creation of worklist entries from business process activities. Users receive external business process worklist notifications on My Worklist like other worklist items. Notifications can be informational, or they can be reminders of actions that users need to perform and update the result in the worklist entries afterwards. If users click worklist items that require a response, the system transfers them to the corresponding Worklist Outcome page where they indicate their response (called an outcome). Typically it is a status update for the activity that users are supposed to perform (for example, asking for manager approval in a hardware request business process). In some cases users provide outcome information that is specific to transactions if business activities expect such input. To accept outcomes from users, you need to define a set of outcomes that the business process recognizes and associate the outcome set with the Worklist Outcome page where users respond. The outcome values must match the ones that the associated business process uses, otherwise the business process monitor may not be able to display the status information of the activity properly.

Note. In order for the business process monitor to display the outcome of worklist entries as a result of the milestone, you must annotate the scope of the asynchronous receive activity and sensor its runtime property (returned response) at the scope level. Regardless of the level of the process, the conversation ID of the root business process must be included for invoking activities that create worklist entries in the CRM system.

From My Worklist, CRM users can enter application-specific information if applicable and mark business process worklist entries as completed after relevant actions are performed. The outcome is then returned to the business activity to continue the process execution. Outcome can be optional in some activities and mandatory in others. If users try to change the status of worklist entries to completed without specifying the outcome when it is required, a configuration option can be set to display a message to remind users that they need to provide an outcome for those worklist entries before marking them as completed.

On the Worklist Outcome page, users can access the initiating transaction of the business process instance to which this open worklist entry pertains provided that a valid conversation ID is included by the invoking activity which created the worklist. Users can also view the overall and milestone-level statuses of the business process instance on the business process monitor. The monitor displays the status information of worklist activities if the associated worklists items are completed. Users can access the Worklist Outcome page from either My Worklist or the business process monitor, and the mode of the page (read-only or editable) changes based on the status of the worklist entry. The page is displayed in edit mode if the entry is just created or in the process of being updated. If the entry is either completed or cancelled, information on the page is read-only. Because the business process monitor displays worklist activities only if the associated entries are completed, the page is always in read-only mode when users transfer to it from the monitor.

This diagram illustrates the life cycle of a business process worklist entry, starting from the initiation of its corresponding process instance, the request to create the worklist entry from its activity, the creation, management, and completion of the entry in the CRM system, to the passing of the outcome information back to the activity in the business process instance:

Creating and managing business process worklist entry process flow

The CRM worklist handler is the centerpiece of the worklist integration. It is responsible for:

Calling the PeopleTools-delivered handler to create the PeopleTools worklist entry and populate the Worklist Reply-to table.
Collecting the data from the initiating business process to create the CRM worklist entry.
Creating the CRM worklist entry and performing any application-specific processing.

Note. Any update made to a business process worklist entry does not reflect in its associated business process instance.

The CRM system delivers business processes that customers can adopt or modify to suit their needs. Activities that generate worklist entries are sometimes served as placeholders that can be replaced by third-party web services if applicable. For example, the delivered loan application business process includes an activity that sends a CRM worklist entry instructing the user to manually enter a loan rate to be returned to the activity. This step can potentially be accomplished by calling a web service that gets a loan rate from a financial institution. Having worklist activities in place gives organizations the option of handling these activities manually until they identify the appropriate web services to perform the operations.

Note. Forwarding, reassignment, and deletion of business process worklist items are not supported.

Outcomes

When users mark worklist entries as completed, any user-specified outcome on the Worklist Outcome page is sent to the associated business activity as response. Outcome represents the final status of that activity and it can include additional application-specific data based on the requirements of the business process.

Because a business process may expect a specific set of input values and the execution path it takes is based on the returned value, the CRM system provides you with the ability to define application-specific outcome sets. You can also design a application-specific Worklist Outcome page where users can enter additional transaction data to be sent back to the associated activity.

Not all worklist activities require outcomes. For activities that do not need outcomes, for example, informational notifications, the Worklist Outcome page that they use is not linked to any outcome set. In this case, a signal is sent back to the associated activity without any user response.

The CRM system delivers a common Worklist Outcome page and several outcome sets that are ready to use.

Simple Outcomes

This type of response contains a single outcome that is returned to the activity for further processing. Users access the Worklist Outcome page from My Worklist and select one value from the predefined set of values that is associated with the page. The CRM system delivers common and application-specific outcome sets and you can build new ones if needed. You can clone from an existing outcome set and add additional outcome codes that are specific to your transactions.

In the outcome definition, you select a Worklist Outcome page to which the outcome set applies. Specify if users must provide an outcome if the given outcome set is used, and identify a default outcome value that shows on the Worklist Outcome page, especially if outcome is required. If outcome is required to complete a worklist item but users forget to select one when they try to mark the item as completed, you can enable the Force User to this Page option and let the system to validate worklist items before changing their statuses to completed.

Note. Ensure that outcomes are set up appropriately so that valid information can be returned to the business process monitor for display. There is no cross-system validation to ensure that the values established in the CRM system match the values that are needed by the business process.

Expanded Outcomes

This type of response contains a single outcome as well as any application-specific data that the initiating activity expects to receive. You can modify the Worklist Outcome page that is used in this scenario to include an additional section where users provide the needed information.

Here are some guidelines on developing application-specific Worklist Outcome pages, which is a consulting effort not supported by PeopleSoft CRM:

Design the application-specific Worklist Outcome page by copying the system delivered page (RBB_OUTCOME_PAGE).

Copy all related peoplecode.
Add this page to the common Worklist Outcome (RBB_RESPONSE) component and save the change.
Create a new subpage that is used to capture the application-specific information users enter.
Insert this new subpage to the bottom of the new page created in step 1.
Include relevant PageActivate peoplecode as necessary to render and process outcome information properly.

Code should be in place to display application-specific data in the right mode for in-progress or completed worklist entries and validate user-entered data before marking worklist entries as completed
Save the new application-specific page.
Determine which outcome set to use or create a new set if necessary.

Associate the new page with the outcome set on the Define Outcome page.

You can include additional processing upon the creation of worklist entries. To do so, you define your own application class that extends the RBB_WS_WORKLIST:Extentions:WorklistProcessor class. Overwrite the preProcess and postProcess methods as needed. Then, register your application class in the CRM system and associate it with a unique mapping ID, which needs to be included in the RBBCreateWorklistData item of the RBBCreateWorklistMsg message in CreateWorklistEntryRequest. The information specified in CreateWorklistEntryRequest is used to generate the worklist entry.

Worklist Entry Completion

Worklist entries can be marked as completed:

By users manually on My Worklist.

On My Worklist, users can select multiple worklist items and mark them as completed as a group, or they can open the items and mark them as completed individually.
By an Active Analytics Framework (AAF) action automatically.

You can use the Complete BP Worklist Entry action in a policy to send outcome information back to the associated activity.

See Configuring Actions in Policies.

Note that the transaction must be enabled for AAF to use this action.

After a completion request is submitted, the system performs checks on outcome and application specific data (if applicable) and composes the response to be returned to the associated activity. This diagram illustrates the process for completing business process worklist entries:

Worklist completion process flow

Setting Up Outcomes

This section discusses how to:

Define outcomes.
Extend the worklist processor base class.

Pages Used to Set Up Outcomes

Page Name	Object Name	Navigation	Usage
Define Outcome	RBB_OUTCOME	Set Up CRM, Common Definitions, Business Process, Worklist, Define Outcome, Define Outcome Click the Clone Outcome button on the Define Outcome page.	Define new outcomes or clone from existing outcomes.
Define Application Processor	RBB_WL_PROCESSOR	Set Up CRM, Common Definitions, Business Process, Worklist, Define Application Processor, Define Application Processor	Associate outcomes with business process activities.

Defining Outcomes

Access the Define Outcome page.

Outcome Description

Outcome ID	Displays the unique identifier for this outcome set.
Outcome Label	Enter the short description of this outcome set. The CRM system uses this value as an activity name, as well as the label of the worklist item link on My Worklist if the data is not available in the initiated business process instance.
Instructional Text	Enter the text that shows on the corresponding worklist outcome page to provide information on specifying outcomes.
Clone Outcome	Click to copy the existing outcome set and configuration to a new outcome definition and be used by another application and Activity Status page.

Outcome Details

Outcome is Required	Select if an outcome is mandatory for the activity using this outcome set. If this check box is selected, identify at least one outcome in the outcome list to be the default value.
Page Name	Select the application-specific page that uses this outcome set and users enter the required data in this page to be returned to the business process. If this value is not specified, the CRM system renders the delivered Worklist Outcome page (RBB_OUTCOME_PAGE).
Force User to this Page	Select to display a message to remind users to select outcome responses (if the Outcome is Required check box is selected on this page) on worklist entries in order to complete them. This option is useful when the user tries to mark multiple worklist entries as completed on My Worklist. A message appears if any of the selected worklist entries is missing an outcome when it is required, reminding the user to specify outcomes for those entries before marking them as completed. If this check box is clear, the CRM system bypasses any application-specific validation and marks the worklist entry as completed after the user finishes the work from My Worklist.
Default	Select to make the corresponding outcome a default value to use if the Outcome is Required check box is selected and the user has not selected an outcome for the activity.
Outcome Code	Enter the code of the outcome. When the user selects an outcome, its code is sent to the activity. Note. Make sure that the outcome codes defined in the CRM system match the same codes that the business process recognizes.
Short Description	Enter the label of the outcome value that is displayed on the worklist outcome page.

Extending the Worklist Processor Base Class

Access the Define Application Processor page.

Application Mapping ID

Enter the unique ID of the application if application-specific processing is required upon the creation of a worklist entry.

Application Class ID and Application Class Path

Select the application class and the path to the method that is (called by the CRM Worklist handler) used for application-specific processing.

Completing Business Process Worklist Entries

This section discusses how to:

View business process worklist entries.
Complete general business process worklist entries.
Complete application-related worklist entries.

Pages Used to Complete Business Process Worklist Entries

Page Name	Object Name	Navigation	Usage
My Worklist	RB_WF_WORKLISTS	My Worklist, My Worklist	View and manage a list of business process worklist entries.
<worklist outcome: varies by component >	RBB_OUTCOME_PAGE RBF_OUTCOME_CREDIT RBF_OUTCOME_EMPVER RBF_OUTCOME_INT_RT RBF_OUTCOME_APPRV	Varies by component: refer to the documentation for the parent component.	View and modify business process worklist entries.

Page Name

Object Name

Navigation

Usage

My Worklist

RB_WF_WORKLISTS

My Worklist, My Worklist

View and manage a list of business process worklist entries.

RBB_OUTCOME_PAGE

RBF_OUTCOME_CREDIT

RBF_OUTCOME_EMPVER

RBF_OUTCOME_INT_RT

RBF_OUTCOME_APPRV

Varies by component: refer to the documentation for the parent component.

View and modify business process worklist entries.

Viewing Business Process Worklist Entries

Access My Worklist.

The Worklist grid displays additional columns for business process worklist items, for example, due date and time, notification purpose, assigned to user, initiating transaction, outcome ID, service operation name, and the link to the business process monitor (if the conversation ID of the associated process instance is present).

Users cannot delete, reassign, or forward business process worklist entries.

Worklist Item

Click to access the corresponding worklist outcome page where the user can enter information for the worklist entry.

The label of this link is configurable by the application of the entry. If unavailable, the outcome label specified on the Define Outcome page is used. If unavailable, the text View Activity is used.

Type

Displays the type of business process worklist entries, which is External Business Process.

Completing General Business Process Worklist Entries

Access the common worklist outcome page.

The common Worklist Outcome page consists of two sections:

The activity summary section displays the name of the service operation that creates the worklist entry, the status of the corresponding business process instance, the start and end dates of the process instance, and any instructional comment.
The worklist detail section displays information that pertains to this worklist entry, such as the name of the worklist, the current owner of the worklist, the originator of the worklist, the date when the worklist was created through a web service, and due date if available.

The outcome response shows the default outcome value of the outcome set that is associated with the Worklist Outcome page. This field is shown if the associated activity passed an outcome ID.

Note. This section is unavailable if the activity is not associated with a worklist.

Users can:

Specify outcome for the activity as needed.
Mark the worklist entry as done, which sends the outcome information back to the activity.

If outcome is required, make sure that an outcome is selected before clicking the Done button.
Return to My Worklist without doing anything.
Access the business process monitor to view the status information of the entire business process instance.

From the business process monitor, users can see business process worklist activities only if the worklist entries are already completed.
Access the transaction that launched the business process, which created this worklist entry.

Completing Application-Related Worklist Entries

Access an application-specific worklist outcome page.

Users enter application-specific information, which is sent back to the associated activity when they click the Done button.

Application Mapping ID	Enter the unique ID of the application if application-specific processing is required upon the creation of a worklist entry.
Application Class ID and Application Class Path	Select the application class and the path to the method that is (called by the CRM Worklist handler) used for application-specific processing.