DB2 Content Manager / Process Choreographer Integration Quick Start

Revision1

DB2 Content Manager Enterprise Edition Version 8.3 introduced a tutorial and sample code "Integrating with business processes" using the Process Choreographer component of WebSphere Business Integration Server Foundation V5.1.1.. This Integration Quick Start Guide replaces the tutorial and describes Revision 1 of this integration based on the following chapters:

  1. Introduction
  2. Setting up the Development Environment and Testing the Sample Process
  3. A Tour of the Sample Process
  4. Developing a Custom Content Manager / Process Choreographer Integration Solution
  5. Deploying an Integrated Solution on a Production Simulation Environment
  6. Hints and Troubleshooting
  7. Further Reading

1. Introduction

DB2 Content Manager Enterprise Edition V8.3 includes a high-performance document routing engine to manage the lifecycle of content objects. For complex process environments that involve a variety of applications and services in a heterogenous IT and business environment WebSphere Business Integration Server Foundation Version 5.1.1 is the process management environment of choice as it provides a rich infrastructure for intra-enterprise and inter-enterprise services based on the WebSphere Application Server. These processes can involve both human and IT resources. The types of processes can vary greatly, ranging from Web services or Web page navigation to business transaction support. Processes can be based on automated steps that together constitue a single transaction of they can involve human interaction any may run for days weeks or months.

The Content Manager / Process Choreographer (CM/PC) Integration Quick Start provides some key ingredients for the creation of content-centric processes. The term content-centric process refers to a process in which a content object stored in the Enterprise Content Management system plays an important role. This typically means that the content object may be investigated at human-activities and that it is modified throughout the process. This content object (a Content Manager item) which typically is a container of content objects (a folder) is said to be routed through the process or (work)flow. Modifying it can mean a number of things such as adding or removing objects from it (if it is a folder), changing attribute values, modfying access rights, adding annotations, signatures, or watermarks, etc.

The main purpose of the Integration Quick Start is to provide best practices and pre-assembled building blocks that support the creation and management of content-centric processes based on the Process Choreographer environment.

1.1 What's New in Revision 1

Revision 1 of the Content Manager / Process Choreographer Integration Quick Start consists of the following elements:

The Integration Toolkit is a collection of service components (Java classes, EJBs) that implement the following interaction patterns between the content management and process management system:

The Quick Start Client is a Web application that enables process users to see work that is assigned to them, fetch work items and work with content objects in DB2® Content Manager Enterprise Edition V8.3. Though the Quick Start Client is customized for use with the Auto Claims Process it provides generic out of the box capabilities and can easily be adjusted to the needs of other processes.

The Auto Claims Process illustrates how the Integration Toolkit can be used to create a content-aware process. This process involves human-based activities that can be performed using the Quick Start Client, services provided by the Integration Toolkit and some simulated internal or external Web services that may involve legacy applications or B2B transactions.

Both, the Integration Toolkit and the Quick Start Client are provided as sample code. They also serve as educational resources for learning how to integrate the two products. The Quick Start Guide that can be downloaded below describes how the source code can be modified to meet specific requirements of a custom integration solution. See the license statements in the documentation or source files for details.

1.2 Notices, License and Support Terms

Note that the following statements apply to the source code of the Content Manager / Process Choreographer Integration Quick Start:

Licensed Materials - Property of IBM
IBM DB2 Content Manager Enterprise Edition V8  (program number 5724-B19)
(c ) Copyright IBM Corp. 1994, 2005. All Rights Reserved.

US Government Users Restricted Rights                                  
Use, duplication or disclosure restricted by GSA ADP Schedule          
Contract with IBM Corp.     

DISCLAIMER OF WARRANTIES :                                             
                                                                       
Permission is granted to copy and modify this  Sample code, and to distribute modified versions
provided that both the copyright notice, and this permission notice and warranty disclaimer
appear in all copies and modified versions. 

This software is provided "AS IS."  IBM and its Suppliers and Licensors expressly disclaim all
warranties, whether EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE OR WARRANTY OF  NON-INFRINGEMENT.
IBM AND ITS SUPPLIERS AND  LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFEREDBY LICENSEE
THAT RESULT FROM USE OR DISTRIBUTION OF THE SOFTWARE OR THE COMBINATION OF THE SOFTWARE WITH
ANY OTHER CODE.
IN NO EVENT WILL IBM OR ITS SUPPLIERS  AND LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR
DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE
SOFTWARE, EVEN IF IBM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Note that the integration toolkit requires a DB2 Universal Database-based library server and that it does not support WebSphere Process Server V6, the z/OS or i5/OS environments, nor clustered environments.

See Trademarks for details on the trademarks used in this document.

1.3 Software Requirements

For both the development and runtime environments, the Content Manager library server needs to be based on a DB2 Universal Database V8.2. The integration toolkit only supports a DB2 Universal Database-based library server.

The following system configuration is required for the development and test environment (chapter 3):

  1. Development workstation A hosts:
  2. Repository server B with:

For simulating a production environment (chapter 5) the repository server B additionally requires:

The development workstation as well as the server should have at least 1 GByte of main memory. However, recommended are at least 2 GByte.

This guide uses Windows platform conventions for path names. Before proceeding we recommend that you look up the install directories of the following products as they will be used later in this guide:

<IBMCMROOT> = Content Manager installation folder (e.g. c:\Program Files\IBM\db2cmv8 or /usr/db2cmv8)
<DB2HOME> = home folder of the DB2 instance which hosts the Content Manager library server (e.g. c:\Program Files\IBM\sqllib or /home/db2inst1/sqllib)
<WSADIE_HOME> = WebSphere Studio Application Developer Integration Edition install folder (e.g. c:\Program Files\IBM\Websphere Studio\Application Developer IE\v5.1.1)
<WAS_HOME> = WebSphere Application Server install folder (e.g. c:\Program Files\IBM\Websphere\Appserver)

1.4 A guideline for reading this document

We recommend starting with 2. Setting up the Development Environment and Testing the Sample Process as this lays the foundations for further explorations in the area of integrating content and workflow. This chapter describes how to set up the infrastructure to build and test integrated workflows. You may want to take a tour of the sample process as described in 3. A Tour of the Sample Process and continue either with 4. Developing a Custom Content Manager / Process Choreographer Integration Solution to understand what it means to create a custom CM /PC integration solution based on the Integration Toolkit and Quick Start Client or to 5. Deploying an Integrated Solution on a Production Simulation Environment which explains how the sample process can be deployed on a production environment. 6. Hints and Troubleshooting provides some hints and tips which may be useful when working with the sample. 7. Further Reading provides links to product documentation, Redbooks and Support pages.

2. Setting up the Development Environment and Testing the Sample Process

This chapter describes the steps needed to set up a development environment for the Integration Quick Start. At the end of this chapter the Quick Start Client can be used to work the sample process and to explore the results of running the server-side integration functions. Depending on the reader's previous experience with the WebSphere Studio Application Developer environment completing this paragraph will take approximately 1-2 hours.

2.1 Prerequisites and Installation Hints

Detailed instructions on how to install and configure the required software can be found in the product documentation. See 7. Further Reading at the end of this document. This section gives some hints about configuration settings that are specific to the use of these products in the context of the Integration Quick Start. See 1.3 Software Requirements for details on the system configuration required for chapter 1.

Installation hints for Information Integrator for Content

In each of the following installation windows, perform the described task:

Installation hints for WebSphere Application Developer Integration Edition

Note that WebSphere Business Integration Server Foundation and Tivoli Directory Server are not required in the development and test environment.

2.2 Preparing the Content Manager Sample Data for use with the Sample Process

The Quick Start sample process is based on a modified version of the Content Manager sample data. This step describes how to load the sample data and adjust it for use with the sample process. The sample process uses a new attribute XYZ_ClaimAmount to distinguish 'cheap' cases for which a high process throughput is desirable from 'expensive' cases for which additional research is required. Furthermore, two new attributes WF_OnCreate and WF_OnDelete are required to enable creation and termination of process instances based on content events (see Content Event Handling for details).


2.3 Setting up the Test Environment

This section copies the files that are required for the build environment to the appropriate locations of the development workstation's file system. Two JAR files need to be located in the lib directory of the application server in order to be accessible from Java snippets in business processes. The build environment uses a file-based custom user registry for authentication with the process environment (via the application server). This user registry stores userIDs and passwords of the process staff in two files that need to be placed into a folder in the application server install directory. The settings in the password file (especially for userID icmadmin) need to be adapted to the settings of the Content Manager server. Note that the runtime environment uses a common LDAP-based user repository for both Content Manager and the process environment so there will be no duplication of credentials and passwords will not be stored in readable form when moving to the runtime environment. The file-based approach is only used for the development environment.

2.4 Configuring the Build environment and Importing the Sample Projects

This step adjusts compiler settings and makes the project files available to the build environment. We recommend setting the browser configuration so it opens the Web browser in a new window which provides more flexibility when watching project contents and running the Web client at the same time.

If Fix Pack 1 of DB2 Content Manager Enterprise Edition V8.3 is installed we recommend taking the step Upgrading the content viewer applet to Fix Pack 1 or (re-)creating the content viewer applet to upgrade to the latest version of the content viewer applet.

You may now want to spend a moment and investigate the process and its elements. Useful resources are the process definitions (ClaimsHandlingProcess.bpel, ClaimsHandlingProcess.wsdl, ClaimsHandlingProcess.component) located in the Service Project ClaimsHandlingProject.

2.5 Enabling Content Manager for Single Sign On

The Quick Start Client uses Single Sign On (SSO) so users need to authenticate only once instead of having to logon to the process environment and to the Content Manager server. This step configures Content Manager so it can use the credentials provided by the application server to authenticate a user. Note that some of these settings are global (allow trusted logon, password not required for all users) so it is important to understand their potential impact on other Content Manager-based applications.

2.6 Configuring and Starting the Test Server

The Server project imported with the previous step configures a test server that can be used to run the sample process within WebSphere Studio Application Developer Integration Edition. The test server configuration points to the WebSphere Business Integration Server Foundation located in <WSADIE_HOME>\runtimes\ee_v51 (note that it was formely named Enterprise Edition). This step adjusts the environment and security settings of the test server configuration to the settings of your Content Manager Server.

3. A Tour of the Sample Process

A note on the new sample process: the integration sample process provided with DB2 Content Manager Enterprise Edition V8.3 was designed to be compatible with the sample process used to illustrate document routing (DB2 Content Manager Enterprise Edition V8.3 includes a document routing engine for use with document lifecycle management within Content Manager).

The new sample process provided with CM / PC Integration Quick Start focuses on the integration of different services both human-based and automatic. Automated services such as retrieval of the insurance policy or the fraud history check illustrate the inclusion of third party applications or B2B transactions with external service providers.

This is a more natural way of demonstrating the use of Process Choreographer since the Content Manager Enterprise Edition V8.3 sample process is a simple human-centric document flow example that can easily be implemented on the basis of Document Routing.

3.1 The sample process

The sample process provided with the CM / PC Integration Quick Start implements a simplified Claims Handling Process. Though it uses some insurance terminology and corresponding sample data it can be seen as an example of a more abstract review and approval process.

If your library server name is not icmnlsdb you need to open <WORKSPACE_FOLDER>\QuickStartClient\JavaSource\com\ibm\bpe\cm\util\ProcessData.java in WebSphere Application Developer Integration Edition, change the value of CM_DATASTORE_NAME accordingly, and re-build the project QuickStartClient . Note that the update is enabled in the active Web project on the fly so the server does not need to be re-started.

3.2 Process initiation

This section explains the different ways to create process instances corresponding to a variety of options to import documents into the Content Manager server. The key distinction is if process instances are created explicitly by an application or implicitly based on events. The former option may be preferred if the application that manages incoming documents is within the control of your organization so that code can be added to explicitly create process instances where needed. The code used to create instances based on existing items may be investigated to see how this works. The latter option may be preferred in cases where document import is treated as a black box or the corresponding application is not within the control of your organization.

3.3 Data validation

3.4 Approval or rejection

3.5 Exploring alternative options

4. Developing a Custom Content Manager / Process Choreographer Integration Solution

This chapter describes the elements of the Integration Toolkit and outlines how they can be combined to create a custom integration solution.

4.1 How a CM/PC integration workspace is organized

The following sections assume a basic familiarity with DB2 Content Manager Enterprise Edition V8.3, WebSphere Studio Application Developer Integration Edition V5.1.x, and WebSphere Business Integration Server Foundation V5.1.x. They focus on the concepts that are specific to an integration solution based on the Integration Toolkit and Quick Start Client. Valuable resources to get familiar with the environment are the redbooks and documentation referenced in the literature section at the end of this document. From the point of view of business process creation we recommend the business process samples that can be found in WebSphere Application Developer Integration Edition under New > Other > Examples > business integration > scenarios > BPEL. We recommend working through at least one of the 'build it yourself' style samples and taking the time to look up new concepts in the redbooks or documentation.

A workspace of a custom solution that integrates DB2 Content Manager with Process Choreographer typically consists of the following projects:

In the following we describe the elements of an integration solution based on the three types of projects and their interaction.

4.2 The Integration Toolkit

The Integration Toolkit is a set of Java classes and EJBs that support the creation of content-centric processes. See the figure below for a schematic representation of the Quick Start architecture:

The three red blocks mark the three elements of the Content Manager / Process Choreographer Integration Quick Start: the Quick Start Client, the claims handling sample process and the Integration Toolkit.

The Integration Toolkit methods are implemented within a stateless session bean context that permits the current global transaction to be suspended while invoking the Content Manager API. This enables efficient use of Content Manager within the WebSphere Application Server environment. A Java class named ContentManager provides static methods that simplify programmatic exploitation of underlying services, including EJB access. This class is especially useful in the Process Choreographer Java Snippet environment, where process designers may have limited Java skills.

The API documentation for the static methods in ContentManager can be found in ContentManagerIntegrationJar\doc\index.html

Startup beans are WebSphere-specific stateful session beans that are automatically notified when a WebSphere application is started or stopped. A bean is designated as a startup bean by implementing special home and remote interfaces. When WebSphere starts an application, it looks for beans that implement these special startup bean interfaces. If it finds any, it arranges to invoke the beans start() and stop() methods on application initialization and termination. The Integration Toolkit uses the startup bean to start and stop the asynchronous bean described below.

Asynchronous beans are WebSphere-specific enterprise beans that are executed asynchronously and provide support for application threading within a J2EE environment. There are three types of asynchronous beans:

The Integration Toolkit uses a worker asynchronous bean. A worker asynchronous bean is like a Windows service or a Unix/Linux daemon process. It runs until asked to terminate. The integration asynchronous bean runs in a loop, doing its work and then sleeping for a period of time before waking up and repeating the process. When started by the startup bean, the asynchronous bean used by the Integration Toolkit invokes methods in the Content Manager Integration Stateless Session Bean to perform the following operations:

The asynchronous bean loops until its stop method is invoked by the startup bean at application termination.

The Collection Point MDB (Message Driven Bean) is invoked in response to messages from Collection Point activities in content-centric processes. In other words, when such a process encounters an Invoke activity which is bound to the Collection Point service, it puts a message on a specific Java Message Service (JMS) queue (CollectionPointQueue). When that message reaches the head of the queue, an associated listener gets the message from the queue and WebSphere invokes the Collection Point MDB. The Collection Point MDB retrieves the elements of the request (item id, name and quantity of items to wait for) and invokes a method in the Content Manager Integration Stateless Session Bean to register the collection point for subsequent processing by the Content Manager Integration Asynchronous Bean, which sends a reply message back to the business process when the collection point condition is satisfied.
You can invoke an asynchronous service (e.g. bound to a JMS implementation) with a single invoke activity or use a invoke/receive pair in the BPEL process to communicate asynchronously with a partner. In the first case a correlation set needs to be maintained to locate the process instance to which the response should be sent. With JMS binding locating the appropriate process instance can more easily be done based on the JMS message ID.

The Content Manager Integration Stateless Session Bean does most of the work. Note that the implementation of most of these functions can be found in the com.ibm.bpe.cm.util package of the ContentManagerIntegrationJar project.

At the level of content / workflow interaction patterns the Integration Toolkit offers the following functions:

A process that uses any of the toolkit functions needs to comply with the following conventions:

ContentManager.initializeCustomProperties(this, get<ProcessRequestVariableName>().getItemPid());

When creating a new CM/PC integration project make sure that ContentManagerIntegrationJar is included in the list of project references of the corresponding service project. The initial Java snippet copies the itemPid value of the input message to process properties where they are available e.g. for combined query evaluation. The Integration Toolkit stores an item's unique identifier as both a fully specified itemPid and as a triple <ITEMID, COMPONENTID, VERSIONID>. When starting a process instance based on content event handling, only the triple-based information is available. During initialization of the process, the method initializeCustomProperties() retrieves the fully specified item PID that contains among other information the library server name and item type.



4.3 Content Event Handling

With content event handling, activities in DB2 Content Manager generate events that can be handled by the business process management system. The Integration Toolkit provides an implementation of content event handling that deals with item creation and deletion events. If defined properly, an item creation event triggers the creation of a process instance as soon as an item of a certain type is stored in DB2 Content Manager. The newly created process instance contains a reference to the item just created. If capturing of deletion events is specified, the deletion of an item in DB2 Content Manager triggers the removal of any process instances 'carrying' it.

How to use Content Event Handling

The administrator specifies which items trigger creation or deletion events based on the custom attributes WF_OnCreate and WF_OnDelete that need to be assigned to the item types for which content event handling should be enabled. Both attributes need to be defined as a variable length character string with a minimum length of zero and a maximum length of 254 as shown below:

To enable an item type for content event handling add WF_OnCreate or WF_OnDelete to its list of attributes and enter the template name of the process to be notified as the default value.

The value of the attribute WF_OnCreate specifies the name of a process to start whenever the corresponding event occurs. So, for example, if the WF_OnCreate attribute for the XYZ_ClaimFolder item type is set to ClaimsHandlingProcess, then whenever a user creates a new item of type XYZ_ClaimFolder, a new instance of the ClaimsHandlingProcess is started with a reference to this item in its input message. Note that this assumes a certain definition of the input message for these processes, in particular the message must contain at least a String part named itemPid. If multiple versions of this process are deployed, the most recent process with respect to the Valid From date is selected. If the attribute WF_OnDelete is present in the definition of the item type XYZ_ClaimFolder with a default value of ClaimsHandlingProcess, deleting an item of this type terminates all instances of the ClaimsHandlingProcess that carry this item.

With this create and delete linkage, content event handling enables some degree of referential integrity between the content repository and the process management system in the sense that document creation or deletion causes corresponding action in the process management system in order to keep the two systems synchronized.

How Content Event Handling is implemented

Item type definitions that have a WF_OnCreate or WF_OnDelete attribute are registered in a table BPECONTENTENVENTS that the Integration Toolkit creates in the library server database. Each row in the BPECONTENTEVENTS table constitutes a content event request. The method checkContentEvent() of the stateless session bean is called regularly from the asynchronous bean to see if a new process instance should be created or if process instances should be deleted. It scans the BPECONTENTEVENTS table in the order and performs the corresponding creation or deletion operations in the order in which requests have been added to the table deleting the rows as soon as the corresponding action has been performed successfully. If an action fails, an error message is written to the log the row remains in the table and the event is retried during the next cycle of the asynchronous bean. The BPECONTENTEVENTS table is created during server startup if it does not exist yet.

The BPECONTENTEVENTS table has the following structure:

CREATETS        TIMESTAMP
ITEMID          CHAR(26)
COMPONENTID     CHAR(18)
VERSIONID       SMALLINT
REQUEST         SMALLINT
PROCESSNAME     VARCHAR(254)

The CREATETS column is the creation date and time of the content event. It ensures that content events are processed in the order in which they are received. The ITEMID, COMPONENTID and VERSIONID columns are the key values of the corresponding itemPid the creation or deletion of which triggered the event. The REQUEST column indicates the type of CM event: 1 for creation, 2 for deletion. The PROCESSNAME column indicates the name of the process to be created in case of creation events. Rows are written to the BPECONTENTEVENTS table using database triggers. These triggers are automatically created by the Asynchronous Bean for Content Manager item types that contain the custom attributes WF_OnCreate or WF_OnDelete. The trigger is created on the underlying Content Manager Component Table (a table of the form ICMUTnnnnnsss). Once the trigger is created, create and delete operations for the item type result in requests being written to the BPECONTENTEVENTS table. This has the benefit of decoupling the Content Manager transaction from the subsequent Check Content Event transaction so that the performance impact to the Content Manager transaction is minimal. The BPECONTENTEVENTS table is created (if it doesn't already exist) via the ejbCreate method, the first time the Content Manager Integration Stateless Session Bean is created.

Apart from this specific mechanism content event handling can also be viewed as specific instance of a more general concept that may be applied to other special processing, as needed.

Examples might be:

4.4 The Collection Point Service

A collection point can be used where the item that is routed through the process is a folder. A collection point is an activity in the process which waits until a certain folder condition is valid. This condition is expressed in terms of <ITEMTYPE, QUANTITY> pairs. A set of such pairs specifies how many instances of the named item types need to be in the folder for the process instance to resume execution. <1, XYZ_ClaimForm>, <2, XYZ_AdjReport>, <1, XYZ_PolReport> is an example that lets the process instance wait until one claim form, two adjuster reports, and one police report are available in the claim folder that is routed through the process.

How to use the Collection Point Service

A collection point is modeled by two activities, a Java Snippet that defines the collection point conditions and an invoke activity that calls the collection point service provided by the Integration Toolkit. Note that a process using a collection point must be defined as long running since the availibility of documents usually depends on some external conditions that are beyond the control of the process and typically person-based. Furthermore, a timeout may be specified to ensure the process instance resumes execution in lack of the required documents. In most cases, the timeout triggers a reminder or corrective action to ensure the process instance does not wait forever.

The collection point service takes an input message consisting of two arrays with the item type names and their respective quantities and a numeric part for the timeout. It returns a numeric status value that represents one of the following situations:

A typical implementation of the collection point looks as shown below:

The Java snippet InitializeCollectionPoint instantiates the input message of the collection point service. It stores the item PID of the folder, and defines the collection point condition and timeout value as shown above. A decision inside the loop evaluates the return value of the collection point service and triggers corresponding actions such as sending a notification in case of a timeout or terminating the process instance in case of a failure.

A collection point service can be added to a process definition by dragging the CollectionPoint.wsdl from ContentManagerIntegrationJar/com.ibm.bpe.cm/ and dropping it into the appropriate location of the process diagram. Since the collection point condition is specified by the input message of the collection point service, it can be read and modified at process runtime. The ValidateAndAdjust activity of the sample process demonstrates how a person with this role can adjust the collection point conditions within a certain range.

How the Collection Point Service is Implemented

Invoking a collection point service produces a JMS message that triggers the registration of a collection point. For each message, registerCollectionPoint() retrieves the parameters initialized by the process and writes them to a table BPECOLLECTIONPOINTITEMTYPES in the Content Manager library server using JDBC.

The Content Manager library server database contains two tables for collection point support provided by the Integration Toolkit.

The table BPECOLLECTIONPOINTITEMTYPES contains one row for each item type and quantity specified in the collection point request. It is defined as follows:

CORRELATIONID       VARCHAR(254)
ITEMTYPENAME        VARCHAR(254)
ITEMTYPEQUANTITY    INTEGER

The CORRELATIONID column contains the JMS Correlation ID of the original message. The ITEMTYPENAME column contains the name of the item type to wait for. ITEMTYPEQUANTITY specifies the number of items of type ITEMTYPENAME to wait for.

The table BPECOLLECTIONPOINTS contains one row for each active collection point request. It is defined as follows:

CREATETS        TIMESTAMP
CORRELATIONID   VARCHAR(254)
ITEMID          VARCHAR(254)

The CREATETS column is the creation date and time of the collection point request. It ensures that collection point requests are processed in the order in which they are created. The CORRELATIONID column is the JMS Correlation ID of the original message. Process Choreographer uses it to correlate the response message with the request message so that the Invoke activity in the process completes. The ITEMID column is the Item ID of the folder to be checked.

There is a one-to-many relationship between BPECOLLECTIONPOINTS and BPECOLLECTIONPOINTITEMTYPES, based on the CORRELATIONID. Any of these tables is created during server startup if it does not already exist.

The method checkCollectionPoint() uses JDBC to perform an SQL query which returns a list of collection points that are satisfied. For each satisfied collection point, it deletes the collection point request from the BPECOLLECTIONPOINTS table and sends a response message back to the Collection Point Invoke activity of the process. A request is also removed if the folder that is routed through the process has been deleted before the collection point condition is satisfied. Each row in the BPECOLLECTIONPOINTS table represents a collection point, and each row in the BPECOLLECTIONPOINTITEMTYPES table represents an item type condition for a collection point. checkCollectionPoint() joins these tables with the Content Manager Links, Items and NLS Keywords tables to efficiently identify all satisfied collection points in a single request to the library server database. checkCollectionPoint() uses the "Folder Contains" link type to determine the contents of folders. It sums the items for the specified Content Manager folder, and if the resulting counts are greater than or equal to the quantities specified in the collection point conditions, then the collection point is considered to be satisfied. The NLS Keywords table maps the Content Manager item type names to numeric Item Type ID's using the base name for the item type, which may be expressed in any language. However, to avoid a potential cross product, the join is limited to ENU, which must be present (though not necessarily in use). The collection point tables are created (if they don't already exist) via the ejbCreate() method, the first time the Content Manager Integration Stateless Session Bean is created. Rows are written to the BPECOLLECTIONPOINTITEMTYPES by registerCollectionPoint(). checkCollectionPoint() is invoked from the Content Manager Integration Asynchronous Bean.

4.5 Content Attribute Access

There are a number of situations in which there is a need to access the attribute values of the item that is routed through the process or of items in the folder that is routed through the process. Typical situations are conditions on links in a parallel section (flow) of the process or on switch statements in a 'case' section that determine the path to be taken depending on the value of an attribute. Another typical situation is instantiating the input message of a staff activity or other service by extracting attribute values from the folder or from an item in the folder and placing them into parts of the input message to make them available as input parameters to the service. The integration toolkit offers the following methods to extract attribute values from items or to evaluate conditions over attributes:

Object ContentManager.getContentAttribute(processBean, attributeSpec)
Object[] ContentManager.getContentAttributes(processBean, attributeSpec)
Object ContentManager.getFolderContentAttribute(processBean, attributeSpec)
Object[] ContentManager.getFolderContentAttributes(processBean, attributeSpec)
boolean ContentManager.evaluateCondition(String xPath)
boolean ContentManager.evaluateCondition(ProcessBean bean, String xPath)

Each of these methods takes a reference to the process bean and an attribute specification as input parameters. The attribute specification is an array of Strings of the form <itemTypeName>/<attributePath>, where <itemTypeName> specifies the type of item that holds the attribute value of interest (the same attribute may be defined for many different items). <attributePath> can be an atomic attribute name or a sequence of attribute names separated by '/' in case of an attribute hierarchy (as for example in customer/address/city).

getContentAttribute() and getFolderContentAttribute() can be used if no more than a single value can be returned from the query (if the queried attribute is single-valued and no more than a single item of this type is contained in the folder). getContentAttributes() and getFolderContentAttributes() return arrays of objects and are thus capable of returning multiple values.

Decision points are an example for using attribute value access. Many business processes contain conditional processing, in which the path through the process is controlled by the value of attributes or variables in the process. Furthermore, the links between activities in a parallel section (flow) can be conditional, meaning that the link is only followed if the condition is true. These conditions can be specified in a variety of ways, including Java expressions. To use a decision point, a process designer adds a link between activities, specifies the value of the condition as Expression, and enters a Java expression that uses one of the methods listed above to evaluate the condition.

Here is an example of a Decision Point condition based on getFolderContentAttribute(). The condition verifies if the value of the attribute XYZ_ClaimAmount exceeds a certain limit. The query looks for this value in items of type XYZ_AdjReport located in the folder which is routed through the process. If the attribute would be multi-valued or more than one item of this type could be part of the folder, getFolderContentAttributes() should be used instead because getFolderContentAttribute() accesses only the first element of the result set.

evaluateCondition() is based on a different concept to implement conditions on links or switch statements. When called with the process bean and an XPath expression as parameters, it returns true if the result of the query is non empty. The evaluateCondition(ProcessBean bean, String xPath) form of this method supports the following substitutable parameters, which can be included in XPath expressions to further qualify the results:

%ITEMID%
%COMPONENTID%
%VERSIONID%

These substitutable parameters are replaced with the values of the Item ID, Component ID and Version ID (respectively) of the CM item associated with the process (typically a folder). The Item ID and Component ID parameters are character strings, and the substituted values include quotes to produce a valid XPath expression. The Version ID parameter is a number, which can be used in numeric expressions (e.g. %VERSIONID% > 3). Note that use of these substitutable parameters is optional and that the XPath expression is not limited to querying attributes of items associated with the process.

Here is an example of a Process Choreographer conditional link expression that checks to see if the mortgage amount exceeds $333,700:

This Java expression uses the %ITEMID% substitutable parameter to get the CM Item ID associated with the process. This Item ID qualifies the search so that it only applies to the CM item associated with the current process. In this example, the item type is Mortgage and the name of the CM attribute is Amount. If the mortgage amount exceeds $333,700 for the item associated with the current process instance, then the link will be followed and the next activity on that link will be executed.

4.6 Folder Service

The folder service adds one or more items to a folder. The two available operations are addFlowItemToFolder and addItemToFlowFolder. Both operations take the itemPid of the item that is routed through the folder and an XPath query as input and return a numeric value that represents the size of the result list obtained from running the XPath query. The operations differ as follows:

addFlowItemToFolder
In this case the XPath query needs to return a folder. This operation adds the item that is routed through the process to this folder. If the item routed through the process is itself a folder this will create a nested folder structure.

addItemToFlowFolder
In this case the item routed through the process needs to be a folder. This operation adds the items returned by the XPath query to the folder that is routed through the process.

4.7 Combined Query

Typically, end users are not aware of underlying technologies and need not be concerned with whether they are using a process management system or a content repository. Ideally, these users have a single user interface that enables them to efficiently search for information, regardless of how that information is stored. In order for this to be the case, the Integration Toolkit provides a combined query capability that efficiently searches for information in both the Content Manager library server and the process engine database (i.e. not only content and its attributes, but also properties of the enclosing process instance). This query capability utilizes search criteria for both systems (the "where" clause) as well as attributes (the "select" clause). Combined query results only include items to which the caller has access. This means that the item must exist in a work list, and that the caller be authenticated as a user who has access to the work item.

To take advantage of this combined query capability, a Web programmer uses the combinedQuery method of the Integration Toolkit which has the following interface:

public QueryResultSet combinedQuery(
    String selectClauseWorkflow,
    String flowItemTypeNameContent,
    String flowItemTypeAttributesContent,
    String additionalAttributesContent,
    String whereClauseWorkflow,
    String xPathContent,
    String orderByClauseWorkflow,
    java.util.TimeZone timezoneWorkflow);

The combinedQuery method returns a com.ibm.bpe.api.CombinedQueryResultSet which enables a programmer to access the combined query results. This interface is designed to be used e.g. in a Web application. The Integration Sample Client implements the concept of user work lists based on the combined query capability of the Integration Toolkit. below.

4.8 Staff Resolution

As work flows through a process management system, it is acted on by a variety of automated and manual steps. When a work item arrives at a manual step, the process management system must decide which users should have access to the item. This is referred to as staff resolution. Process Choreographer provides a highly configurable staff resolution facility that uses a role / verb model to identify user access for a work item. These are the predefined roles that describe the types of access supported:

Process Choreographer uses staff verbs to assign users to these staff roles. The staff verbs are configurable queries to an underlying directory service, and are limited only by the power and flexibility of that service. For example, if the directory service supports a "manager of" relationship, then the staff verb can utilize that relationship to resolve a role to a manager of a user. Process Choreographer utilizes a pluggable interface to the underlying staff repository, and comes preconfigured with interfaces for LDAP, the WebSphere User Repository and a System directory.

The Integration Toolkit includes a WebSphere User Registry implementation for DB2 Content Manager. This uses the Content Manager user and group definitions to support group membership. This means that users only need to be defined once, using the Content Manager system administration interface, and that staff resolution can be performed at the group level. Alternatively an LDAP server can be used as a centralized repository for user and group definitions as will be done in Chapter 5 of this document.

Note that the WebSphere user registry for DB2 Content Manager provided by the Integration Toolkit can not be used to implement Single Sign On (SSO) since enabling Content Manager for SSO requires disabling of the password checks. When used with an SSO-enabled application server this would bypass password checking and allow users to log on with an arbitrary password. The preferred way to implement SSO is by using a simple file-based user registry in the build environment (based on the files users.prop and groups.prop) and to use an LDAP system such as the Tivoli Directory Server for the runtime environment.

Note: Using a custom WebSphere User Registry affects all application running on the Application Server such as the Administrative Console. With a dedicated WAS installation for Content Manager and Process Choreographer (potentially also hosting the Resource Manager application) this should typically not be a problem as we recommend to use the library server userid (icmadmin) as Application Server and process administrator. If the Application Server is intended to host other applications as well, potential side effects when using a custom user registry need to be well-understood.

4.9 Customizing the Quick Start Client

The Quick Start Client is a generic DB2 Content Manager and Process Choreographer client that does not cover the full range of capabilities offered by DB2 Content Manager and Process Choreographer but it provides what can be thought of as a reasonable set of the most typically used functions and since it is available as source code it can be adjusted to the specific needs of your application.

The process-specific information is stored in QuickStartClient\JavaSource\com\ibm\bpe\cm\util\ProcessData.java. The following settings may need to be adjusted:

Global constants

QuickStartClient\JavaSource\com\ibm\bpe\cm\util\Helpers.java contains a method prepareName() that can be used to map a display name to some potentially truncated form that displays well on the client pages. For the First Steps sample data this means cutting off the comment in parenthesis: (Content Manager V8.1 Sample Item Type) or to truncate the display name of the XYZ_ClaimFolder Claim Application Folder to contain other claim related documents (e.g. adjuster report, auto photos, claim form, etc) and linked by Claim Number at character position 24. This method may be helpful in cases like this where the display name serves as a 'description' of the item type in addition to being the (localizable) name that is displayed to users. prepareName() assumes display names have the form <actual display name> (<description>) where <actual display name is the name to be shown in the client and (<description>) is the comment that describes the item type in more detail. The constants DISPLAY_NAME_SIZE_LIMIT and DISPLAY_NAME_TRUNCATION_POS can be used additionally to truncate long names (those the length of which exceeds DISPLAY_NAME_SIZE_LIMIT) to a maximum size of DISPLAY_NAME_TRUNCATION_POS. Note that specific rules may need to be applied depending on the locale (see the section on Globalization and Accessibility Considerations for more details on this topic).

Roles

Roles define certain aspects of the client's look and feel. A user who logs on to the client gets a role ID assigned by one of the following two mechanisms:

a. it is passed as a parameter to listWorkItems.jsp with a URL such as http://localhost:11605/QuickStartClient/listWorkItems.jsp/role=5. This is the preferred option used with the ClaimsHandlingProcess sample.
b. a map translates user IDs into role IDs (see the comments in header.jsp for an example of how this could be done)

Role IDs are used as an index into three arrays: workListStyleMap, addToFolderActionItemTypes, and addToFolderActionNames. They should be defined using symbolic constants as in the following example:

static public final int USER1_ROLE = 0;
static public final int USER2_ROLE = 1;
static public final int NUM_OF_ROLES = 2;
static public final int DEFAULT_ROLE = USER1_ROLE;

The workListStyleMap defines the columns of a worklist for this role in terms of process properties and item attributes. A WorkListStyleMap defines the parameter of the combined query to be run when retrieving work items for this role.

addToFolderActionItemTypes and addToFolderActionNames define which documents a user with this role can add to the folder that is routed through the flow. For example 

addToFolderActionItemTypes[USER1_ROLE] = { "AdjReport", "FraudReport", "ReliabilityStudy" };
addToFolderActionNames[USER1_ROLE] = { "Adjuster Report", "Fraud Report", "Reliability Study" };

...means that a user with role USER1_ROLE may add instande of the item types AdjReport, FraudReport, ReliabilityStudy to the folder that is routed through the flow. The action column of the work page will refer to these actions by 'Add Adjuster Report', 'Add Fraud Report', 'Add Reliability Study' based on the elements of addToFolderActionNames .

User Actions

The method staffActions(String activityName, WSIFDefaultMessage inputMsg) defines the display elements for the 'Process activity' section of the work page. This section is defined as a table segment spanning four columns. There is no limit on the number of rows. The final column always contains the available actions (Complete and Cancel). This section typically displays some parts from the input message of this staff activity (2nd parameter) and contains form elements that can be used to instantiate its output message. The name of the form element needs be of the form msgpart.xxx where xxx is the name of the corresponding message part. If all parts of the output message are of type String, no custom logic needs to be added to the servlet CompleteWorkServlet that maps the form values to the output message. If non-string-typed variables are involved, either output message parts are mapped to the target type by a Java snippet in the process or custom logic needs to be added to the CompleteWorkServlet

Here a simple example of a 'review activity' with an input message that contains the text to be reviewed and an output message consting of a rating in the range 1..5.

static public String staffActions(String activityName, WSIFDefaultMessage inMsg) {

   try {
     String result = "<td colspan=\"4\"></td>";   // default

     if (activityName.equals("Review")) {
	   String textToBeReviewed = (String)inMsg.getObjectPart("TextToBeReviewed");
	   result = "<TD colspan=\"2\">\n" +
			    "Text to be reviewed:" + textToBeReviewed +
                "</TD>" +
				"<TD colspan=\"2\">\n" +
                "<SELECT name=\"msgpart.NumAdjReports\">" +
				"<OPTION value=\"1\" SELECTED>1</OPTION>" +
				"<OPTION value=\"2\">2</OPTION>" +
				"<OPTION value=\"3\">3</OPTION>" +
				"<OPTION value=\"4\">4</OPTION>" +
				"<OPTION value=\"5\">5</OPTION>" +
				"</SELECT>" +
				"</TD>";
     } // 'Review' activity
     else if (activityName.equals("SomeOtherActivity")) {
        ....
     }
  } catch (WSIFException e) {
		e.printStackTrace();
  }
return result;
}

4.10 The project structure of a custom integration solution

To create a custom integration solution the following projects need to be import from quickStartSampleRev1wbi.zip:

Make sure that the properties of the service project that hosts the custom process includes ContentManagerIntegrationJar in the list of project references and in the list of projects that participate in the build path. CollectionPoint or FolderManagement services can be added to the process definition by dragging their .wsdl file from ContentManagerIntegrationJar\com\ibm\bpe\cm and dropping at the appropriate position of the process flow and adding the corresponding Java snippets or assign activities that create and interpret in- and output messages of the service. When generating deploy code for the process the corresponding XXXService.wsdl files need to be located in the 'Referenced Partners' section of the Generate Deploy Code window. See the section on how to Resolve BPEL references by binding services to port types for details.

4.11 Globalization and accessibility considerations

All Web pages of the Quick Start Client use UTF8 encoding. The static content can easily be localized by creating translated versions of these pages. To avoid code duplication for JSPs we recommend using a different approach for most of the JSPs except help.jsp, namely using Java Resource Bundles since most JSPs only contain small portions of static text such as banner or column titles. A similar approach needs to be taken to internationalize messages of the Integration Toolkit such as those thrown in case of an IntegrationException.

Note that using images to represent the process flow as in index.jsp requires a corresponding text-only version to meet accessibility requirements.

5. Deploying an Integrated Solution on a Production Simulation Environment

This chapter describes the steps needed to set up a stand-alone environment that can be used to simulate and test the process in a system configuration that matches a production environment. This is done by deploying the process, Integration Toolkit runtime and Quick Start client on a WebSphere Business Integration Server Foundation, using an LDAP server as a common user repository and storing the Process Choreographer data in a DB2 database. Depending on previous experience with LDAP and the WebSphere server environment completing this paragraph will take about 2 hours.

5.1 Prerequisites and Installation Hints

See 1.3 Software Requirements for details on the system configuration required for chapter 5.

Configuring the business process container

The Quick Start Integration assumes both, the Content Manager data and Process Choreographer data reside in DB2. Therefore the business process container has to be configured to use the DB2 Universal Database.

5.2 Setting up LDAP

Refer to the product documentation (DB2 Content Manager V8.3 Information Center) and follow the instructions Planning and Installing Your Content Management System > After-installation configuration and setup procedures > Integrating with business processes > Part2: Setting up a production environment > Preparing a common organizational directory to perform the following steps:

5.3 Configure the server environment

5.4 Configure JDBC connections and data sources

5.5 Configure connection factories, queues, and consumers

5.6 Configure security

5.7 Deploying an Integrated Solution on WebSphere Business Integration Server Foundation

Though the title of this section refers to the sample process the same set of steps needs to be performed when installing a custom Content Manager / Process Choreographer Integration solution. Note that connection factory and queue definitions may not be needed if the solution does involve Content Event Handling or the Collection Point Service. In this case the corresponding dependencies need to be disabled in the Integration Toolkit (e.g. the Asynch Bean).

5.8 Install the runtime files, start the server and run the sample

6. Hints and Troubleshooting

Traps when working with the sample

Resolve BPEL references by binding services to port types

If a project has been deleted and needs to be re-installed the references may need to be re-bound as follows.

Clean up the process environment

Upgrading the content viewer applet to fix pack 1 or (re-)creating the content viewer applet

The Quick Start Client uses a modified version of the Content Manager viewer applet to display document content. This applet and the required resources need to be placed into a specific directory where the files are available for download by the client. This step copies the required resources from the Content Manager install directory and (re-)creates the JAR file for the modified viewer applet. This step should be performed when Fix Pack 1 is used or when the code in TViewerApplet.java has been changed (See DB2 Content Manager Enterprise Edition (multiplatform) Support for Fix Pack downloads, etc.).
Important: (Re-)creating the applet viewer requires DB2 Content Manager Enterprise Edition V8.3 Fix Pack 1 to be installed. If Fix Pack 1 is installed we recommend to (re-)create the viewer applet to take advantage of the latest changes in the viewer code.

Creating and deploying a new Integration Toolkit library

7. Further Reading

Product documentation

Background information and documents on specific topics

Product support Web sites

Trademarks

The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

IBM i5/OS z/OS
Redbooks AIX Cloudscape
DB2 DB2 UDB DB2 Universal Database
WebSphere Lotus Tivoli

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, and service names may be trademarks or service marks of others.