DB2 Content Manager / WebSphere Process Server Integration Quick Start

Revision2

This tutorial describes the integration of DB2 Content Manager Enterprise Edition Version 8.3 with WebSphere Process Server V6.0.1. This document consists of the 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 DB2 Content Manager / WebSphere Process Server Integration Solution
  5. Invoking DB2 Content Manager Web Services from within a process
  6. Hints and Troubleshooting
  7. Further Reading

1. Introduction

DB2 Content Manager Enterprise Edition V8.3 includes a high-performance document routing engine to direct documents and folders of documents from one user to another. For complex process automation requirements such as those that involve human tasks outside the document environment or integrations with a variety of applications, systems and services, WebSphere Process Server is the process management environment of choice.

WebSphere Process Server uses a service-component architecture to deliver one programming model to connect and use existing IT resources to solve business problems. Using simplified tooling to describe and create the solution, components can be brought together to create a managed business process. Processes can be based on automated steps that together constitute a single transaction or they can involve human interaction and can run for days, weeks or months. Processes types vary greatly, ranging from Web services or Web page navigation to business transaction support.

The DB2 Content Manager / WebSphere Process Server (CM/WPS) Integration Quick Start provides some key ingredients for the creation of content-centric processes. The term "content-centric" refers to a process in which a content object, typically a document or image, stored in the content management system plays an important role. Examples are review processes such as those involved in publishing, invoice processing, or claims handling. Content-centric processing is also seen in Business To Business (B2B) scenarios where electronic documents are exchanged between different companies.

Human activities and automated steps that modify the content object are key elements of content-centric processes. The content object is usually a folder and is said to be routed through the process or (work)flow. Modifying it can mean a number of things such as adding documents to or removing documents from the folder, changing attribute values on documents, modifying access rights, adding annotations, signatures, or watermarks, etc.

The DB2 Content Manager / WebSphere Process Server Integration Quick Start provides best practices and pre-assembled building blocks that support the creation and management of content-centric processes based on the WebSphere Process Server and DB2 Content Manager environments. Typical interaction patterns between the process engine and the content management system are demonstrated through code samples and comprehensive documentation.

This Quick Start builds on previous versions which showed interaction between DB2 Content Manager and the Business Process Choreographer component of WebSphere Business Integration Server Foundation.

1.1 What's New in Revision 2

The main topic of Revision 2 is support of WebSphere Process Server V6. Revision 2 of the Integration Quick Start consists of the following elements:

The Integration Toolkit is a collection of service components (Java classes and 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 can involve legacy applications or B2B transactions.

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

The following statements apply to the source code of the DB2 Content Manager / WebSphere Process Server 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.

The integration toolkit requires a DB2 Universal Database-based library server and it does not support 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 DB2 Content Manager library server needs to be based on a DB2 Universal Database V8. For details on the required DB2 UDB fixpack levels see the DB2 Content Manager product documentation. The integration toolkit only supports a DB2 Universal Database-based library server. Note that Fixpack 2 of DB2 Content Manager V8.3 is a prerequisite of the CM/WPS Integration Quick Start if you want to use the Custom CM-based user registry. Where DB2 Content Manager V8.3 is mentioned in the following sections this alway implies at least Fixpack 2.

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

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

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

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

<IBMCMROOT> = DB2 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)
<WID_HOME> = WebSphere Integration Developer install folder (e.g. c:\Program Files\IBM\Websphere\ID\6.0)
<WPS_HOME> = WebSphere Process Server install folder (e.g. c:\Program Files\IBM\Websphere\ProcessServer)
<WPS_PROFILE_HOME> = folder of the WebSphere Integration Developer profile to be used on the development workstation (e.g. c:\Program Files\IBM\Websphere\IntegrationDeveloper\profiles\ProcSrv01)

Note that we are using the default icmadmin to refer to the ID of the library server administrator. If the ID of your library server administrator is different, replace all occurences of icmadmin with the ID used on your system.

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. 4. Developing a Custom DB2 Content Manager / WebSphere Process Server Integration Solution introduces the individual elements of the Integration Toolkit and describes the steps necessary when creating a custom CM/WPS integration solution based on the Integration Toolkit and Quick Start Client 5. Invoking DB2 Content Manager Web Services from within a process outlines how Content Manager Web Services can be incorporated into a process. 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 contains 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 the test environment

You can either install with the WebSphere Integration Developer V6.0.1 with a test environment or install WebSphere Process Server V6.0.1 separately. We recommend a separate installation of WebSphere Process Server as this offers more explicit control over port and user settings. If you want to install WebSphere Process Server with the WebSphere Integration Developer product you need to check Integrated Test Environment during installation. In this case a default profile is created automatically with <WPS_PROFILE_HOME> set to <WID_HOME>\pf\wps .


If you decide to install WebSphere Process Server separately, you need to create a profile to be used as test environment based on the following steps:

  1. Start the Profile Creation Wizard
  2. Select a profile name. The suggested name ProcSrv01 may be OK. You may want to make this your default profile.
  3. Specify a profile directory. We recommend that you make the path to this directory as short as possible especially on Windows systems where the operating system limit of 256 characters is exceeded easily.
  4. Verify if the node name and fully specified host name are correct. They should usually be OK.
  5. Carefully investigate the port assignments on the 'Port valua assignment' page. Make sure there is no conflict with other applications on the server. Potential candidates might be the (probably WebSphere Application Server V5-based) servers that are hosting the administrative console (server1) resource manager (icmrm) or the Content Manager Web services (cmwebsvc). If necessary, modify the port assignments so there are no conflicts. Make notices of the port assignments for HTTP transport and SOAP communication as these are needed later on.
  6. It is recommended to uncheck 'Run the WebSphere Process Server process as a Windows service'. The process can be started manually as described in section 6.2.
  7. Check 'Configure the Service Integration Bus in secured mode' and enter icmadmin as user ID and the corresponding password.
  8. On the 'Common Event Infrastructure Configuration' page enter icmadmin, the corresponding password, server1 as the server name, and Cloudscape V5.1 as the database product.
  9. On the 'Business Process Choreographer Configuration' page select Configure a sample Business Process Choreographer and enter icmadmin with the corresponding password. As the name of the administrative group enter the administrative group to which icmadmin belongs. On a Windows system this is usually Administrators.
  10. Skip the 'Application Scheduler configuration' page.
  11. On the 'Database Configuration' page select Create new (local) database and accept the default settings for the database product (Cloudscape) and name (WPRCSDB).
  12. Double-check the summary, click Next and wait until the wizard signals completion.

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

The Quick Start sample process is based on a modified version of the DB2 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 and '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).

  1. Ensure that the resource manager application is started. This can be verified by running serverStatus.bat -all in the bin folder of the WebSphere Application Server installation that hosts the resource manager. Run startServer.bat icmrm to start the resource manager if it is not yet running.
  2. Start the DB2 Content Manager First Steps program.
  3. If you have worked with the sample data before, click Unload Sample Data to ensure all data is in a clean state.
  4. Click Load Sample Data.
  5. Wait until the sample data creation completes.
  6. Click Work with Sample Data to start the DB2 Content Manager system administration client.
  7. Log on to the system administration client with your library server administrator userid and password.
  8. Select Data Modeling, right-click Attributes, select New to define a new attribute XYZ_ClaimAmount with the properties shown below:


     
  9. Click OK to store the new attribute.
  10. Right-click Attributes, select New to define a new attribute WF_OnCreate with the properties shown below and click OK to store the new attribute:


     
  11. Repeat the previous step to define a new attribute WF_OnDelete with the same characteristics as WF_OnCreate.
  12. In the Data Modeling view, expand Item Types, right-click on XYZ_ClaimFolder, right-click Properties, open the Attributes tab and add two new attributes: WF_OnCreate and WF_OnDelete both with the default value ClaimsHandlingProcess.


     
  13. Right-click XYZ_AdjReport and select Properties.
  14. On the definition tab, change the New version policy for attributes to Never create.
  15. Switch to the Attributes tab and add the attribute XYZ_ClaimAmount to this item type, as shown below:


     
  16. Close the System Administration Client.
  17. Close the First Steps program.

Entering values for the previously created attributes


  1. Start the DB2 Content Manager Client for Windows and log on as library server administrator (icmadmin). Note that if the DB2 Content Manager Client for Windows was already started while you changed the sample data definitions in the previous step, you need to close and restart it so the new definitions are available.
  2. Select Search > Basic and locate all instances of item type Adjuster Report (Content Manager v8.1 Sample Item Type).
  3. Right-click on each of the three entries in the result list, select Attributes and enter different Claim Amount values to the three items: For example 1000 (small claim), 10000 (large claim) , 2000 (small claim) as shown below. The sample process introduced later will handle documents with a small claim amount (i.e. less than or equal to $5000) differently.


     
  4. Close the DB2 Content Manager Client for Windows.

2.3 Enabling DB2 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 log on to the process environment and to the DB2 Content Manager server. This step configures DB2 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 DB2 Content Manager-based applications.

  1. Start the DB2 Content Manager System Administration Client and log on as library server administrator (i.e. icmadmin).
  2. In the navigation panel, click Library server parameters > Configurations.
  3. Right-click Library Server Configuration in the configuration window on the right and select Properties.
  4. Set Max user action to Allow logon without warning and select the Allow trusted logon check box.


     
  5. Click OK to save the changes.
  6. Select Tools > Manage Database Connection ID > Change Database Shared Connection ID from the menu. The Change Shared Database Connection ID and Password window opens.
  7. Enter the connection user password (The default connection user is icmconct). Clear the Password is required for all users check box.
  8. Click OK to save the change.
  9. Click Authorization > Privilege Sets. A list of privilege sets shows up in the right pane.
  10. Right-click ClientUserAllPrivs and select Copy > Advanced. The Copy Privilege Set window opens.
  11. Enter the name ClientUserAllPrivsSSO, select AllowTrustedLogon in the Privileges field and click OK to save the new privilege set.


     
  12. In the navigation panel click Authentication > Users. The right pane now shows the list of DB2 Content Manager users currently defined.
  13. For the each of the users Agent1, Agent2, Adjuster1, Adjuster2, Underwriter1, Underwriter2, UnderwriterAssistant1, and UnderwriterAssistant2 double-click the name to open the properties window and replace the value in the Maximum Privilege set field with ClientUserAllPrivsSSO


     
  14. Close the system administration client.

2.4 Installing supplementary files

  1. Unzip quickStartSampleRev2wps.zip into a temporary folder <TMP>.
  2. Copy the file bpecm.properties from <TMP> to <WPS_PROFILE_HOME>\properties.
  3. Open bpecm.properties with an editor and make sure the propertyContentManagerAuthenticationPwd=... contains the password of the library server administrator (icmadmin). Note that a simple encryption method referred to as ROT13 can be used to avoid storing the password in un-encrypted form. Apply ROT13 encryption by adding a decimal 13 to the numeric character representation of each character in the password string, e.g. ABC would become NOP. Set ContentManagerAuthenticationPwdEncryption to 1 to enable the use of ROT13 encryption. Note that the proposed encryption is for demo purposes only. If you plan to use the code in a production environment you might want to choose a more enhanced encryption method.
  4. Create a folder security under <WPS_PROFILE_HOME> and copy the files users.prop and groups.prop from <TMP> to this new directory.
  5. Open <WPS_PROFILE_HOME>\security\users.prop in an editor, locate the line icmadmin:passw0rd:2:2: and replace passw0rd with the password of the library server administrator (icmadmin) on your system.

2.5 Configuring the Build environment

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.

  1. Start WebSphere Integration Developer and specify a directory that serves as the <WORKSPACE_FOLDER>. If not prompted for a workspace, start it from the command line as follows: <WID_HOME>\wid.exe -setworkspace <WORKSPACE_FOLDER>.
  2. On the menu select Window > Open Perspective > Other. The Select Perspective window opens. Check Show All, select J2EE, and click OK. Click OK on the Confirm Enablement dialogue. Close the Welcome view.
  3. On the menu select Window > Preferences. The Preferences window opens.
  4. Select Java > Build Path > Classpath Variables and click the button labeled New. The 'New Variable Entry' window opens.
  5. Enter IBMCMROOT into the 'Name' field and the value of <IBMCMROOT> into the 'Path' field.
  6. Enter IBMWPSROOT into the 'Name' field and the value of <WPSROOT> into the 'Path' field.


     
  7. Select Java > Installed JREs and change the JVM from default Eclipse to WPS Server v6.0 JRE


     
  8. Select Server and ensure that Automatically publish before starting servers is not checked.


     
  9. Recommended: Select Internet > Web Browser and replace the default Internal Web Browser with a supported browser of your choice.
  10. Click OK to close the preferences window.
  11. Click the Servers tab to switch to the Servers view.
  12. If you have installed WebSphere Integration Developer with the integrated test environment the Servers view already contains a entry for the generated profile wps. Double-click the entry to open the Server Overview editor and modify the settings as follows:
  13. If you have installed WebSphere Process Server separately, you need to create an entry in the server view as follows:


     

2.6 Setting up the test environment

The Integration uses a JDBC connection to access the library server database. This connection and other settings such as global security need to be configured with the Process Server's administrative console.

  1. Perform the steps in 6.2 Starting the Process Server and launching the administrative console and log on as icmadmin. Since security is not yet enabled this only serves as a name for your session. In case you close the admin console without saving your changes you will be able to recover by logging on with this same userid again.
  2. In the navigation panel select Environment > WebSphere Variables and set the scope to Node level by checking the radio button labeled Node and clicking Apply.
  3. Ensure that the variable DB2_JDBC_DRIVER_PATH is present (you may need to switch the scope to Node) and that it points to <DB2HOME>/java


     
  4. Create a new variable IBMCMROOT. In the Scope section click Server: server1 and Apply. Click New, enter IBMCMROOT into the Name field, and <IBMCMROOT> into the Value field. Click OK to store the new variable.


     
  5. In the navigation panel select Servers > Application Servers, click server1.
  6. If Run in development mode is not checked, check it and click Apply. It is checked by default for the integrated test environment but it must be explicitly enabled when using a separate stand-alone installation of WebSphere Process Server. Setting it simplifies development and re-deployment of changed modules as process data does not need to be explicitly deleted. Note that in development mode changes to a deployed process automatically trigger the deletion of any existing process or activity instances. If development mode is not enabled, process instances need to be deleted (e.g. using the BPC Explorer) before the process template can be stopped. The process template needs to be stopped before the process can be un-deployed if development mode is not enabled. See section 6.7 on starting and stopping the process application manually.


     
  7. On the configuration page locate the section Server Infrastructure, expand Java and Process Management, and select Process Definition. In the Additional Properties section of the Process Definition page select Java Virtual Machine.
  8. If you have not updated the WAS JRE as described in 6.4 you need to check Disable JIT to avoid a problem that might cause the server to shut down. However, we strongly recommend to update the WAS JRE as described in 6.4 since disabling the JIT has a significant performance impact.
  9. Enter ${IBMCMROOT}/cmgmt into the Classpath field and click Apply


     
  10. In the Additional Properties section select Custom Properties.
  11. If a property with the name ws.ext.dirs exists, add a semicolon followed by ${IBMCMROOT}/lib;${DB2_JDBC_DRIVER_PATH}/db2java.zip to the end of its value. If no such property exists, create a new one with this value.


     
  12. Click Save on top of the window to open the Save to Master Configuration window. Click Save to make the changes permanent.

2.7 Configure JDBC connections and data sources

  1. In the navigation panel select Security > Global Security.
  2. In the Authentication section select JAAS Configuration > J2C Authentication data.
  3. Verify the existence of the authentication alias <HOSTNAME><NODENAME><CELLNAME>/BPEAuthDataAliasJMS_<HOSTNAME>_server1 that has been created during process container configuration.
  4. Click New, add the following entries and click OK to store them.
    Alias ICMNLSDBAuthDataAlias
    User ID icmadmin
    Password icmadmin's password
    Description (optional) Authentication data alias for CM library server administrator



     
  5. In the navigation panel select Resources > JDBC Providers. Ensure the scope is on server1.
  6. If DB2 Legacy CLI-based Type 2 JDBC Driver (XA) is not listed on the cell, node, or server1 level, perform the following steps to add it at the server1 level:
    1. Set the scope to server1 and click OK.
    2. Step1: select the database type DB2
    3. Step2: select the provider type DB2 Legacy CLI-based Type 2 JDBC Driver
    4. Step3: select XA data source
    5. Click Next
    6. Verify that the Class path field contains ${DB2_JDBC_DRIVER_PATH}/db2java.zip and that the Implementation class name is COM.ibm.db2.jdbc.DB2XADataSource.
    7. Click OK to add the JDBC provider to the list of providers available at server scope.


     
  7. Click DB2 Legacy CLI-based Type 2 JDBC Driver (XA) and click Data Sources in the Additional Properties to display the data sources that are based on this JDBC provider. If the JDBC provider has just been added, the list will be empty.
  8. Click New to create a new data source based on the following information:
    Name replace DB2 Legacy CLI-based Type 2 JDBC Driver XA Data Source with icmnlsdb
    JNDI Name replace jdbc/DB2 Legacy CLI-based JDBC Driver XA DataSource with jdbc/ICMNLSDB
    Description (optional) replace New JDBC Datasource with CM library server
    Component-managed Authentication Alias select <HOSTNAME><NODE>/ICMNLSDBAuthDataAlias from the list
    Container-managed Authentication Alias select <HOSTNAME><NODE>/ICMNLSDBAuthDataAlias from the list
    Mapping-configuration alias select DefaultPrincipalMapping from the list
    Database name icmnlsdb
  9. Click OK to save the data source definition.


     
  10. Back on the Data Sources page click Save on top of the window to open the Save to Master Configuration window. Click Save to make the changes permanent.
  11. Perform the following steps to verify if the data source can be accessed:
    1. Select the check box left of icmnlsdb.
    2. Click Test Connection.
    3. Verify that the information message on top of the page says Test Connection for datasource icmnlsdb on server server1 at node <HOSTNAME><NODE> was successful.



     

2.8 Configure security

The following steps need to be performed for both the integrated test environment and a separately installed WebSphere Process Server.

  1. In the navigation panel select Security > Global Security.
  2. In the User Registries section to the right select Custom.
  3. Enter icmadmin into the Server user ID field and the corresponding password into the Server user password field.
  4. Enter com.ibm.websphere.security.FileRegistrySample into the Custom registry class name field.
  5. Check Ignore case for authorization.
  6. Click Apply.


     
  7. In the Additional Properties section click Custom Properties.
  8. Create a new property with name groupsFile and value ${USER_INSTALL_ROOT}/security/groups.prop.
  9. Create a new property with name usersFile and value ${USER_INSTALL_ROOT}/security/users.prop.
  10. Click OK.


     
  11. In the Authentication section of the Security > Global Security page select Authentication mechanisms> LTPA.
  12. Enter a password into the Password and Confirm password fields (for example icmadmin's password).


     
  13. In the Additional Properties section to the right click Single signon (SSO) and ensure that the Enabled box is checked.


     
  14. Click OK on the Single signon page and OK on the Global security > LTPA page to store the changes
  15. On the Security > Global Security panel check the Enabled check box and uncheck the Enforce Java 2 Security check box.


     
  16. Click Save on top of the window to open the Save to Master Configuration window. Click Save to make the changes permanent.
  17. Stop server1 as described in section 6.2.
  18. Click the Servers tab in WebSphere Integration Developer and double click your test server entry to open the Server Overview editor. Expand the Security section, check Security is enabled on this server and enter icmadmin and the corresponding password (you may need to collapse and re-expand the section to see the input fields). Press CTRL-S to store the changes.
  19. Start server1 (see 6.2 for details).
  20. If you have installed the integrated test environment (you are not using a stand-alone installation of the WebSphere Process Server) you need to perform the following steps to enable it for use with security:

2.9 Importing, deploying, and running the sample

  1. In WebSphere Integration Developer select File > Import from the menu. The Import window opens. Select Project Interchange and click Next. In the From zip file section click Browse to locate <TMP>\projects.zip and click OK. A list of 8 projects (ClaimsHandling, CMBPCIntegration, CMBPCIntegrationBeans, CMBPCIntegrationLibrary, CMConnectionManagement, ContentViewerApplet, QuickStartClient, QuickStartClientApp) shows up in the section below. Click Select All and Finish to import the projects.
  2. In the Project Explorer view of the J2EE perspective expand EJB Projects > CMBPCIntegrationBeans and double-click the Deployment Descriptor
  3. In the Overview tab of the deployment descriptor editor locate and expand the section Ejb Client Jar. Click the Create button. Accept the proposed name CMBPCIntegrationBeansClient in the EJB client JAR Creation dialogue and click Finish to start project creation.
  4. Note that the creation of the client project has updated the build path of the corresponding server project. This raises a number of build path errors that need to be fixed as follows: in the EJB Projects section of the Project Explorer view right-click CMBPCIntegrationBeans and select Properties. Click Java Build Path, switch to the Projects tab and check CMBPCIntegration. Click OK to close the properties window and verify that the exceptions are gone.
  5. In the Project Explorer view expand Enterprise Applications > CMBPCIntegrationApp and double click the Deployment Descriptor
  6. In the Application Deployment Descriptor editor select the Security tab and click Gather to add the CMAdministrator role to the list. Click CMAdministrator and check Users/Groups in the WebSphere Bindings section. Scroll down to the Groups section and add the administrator group of this system (to which icmadmin belongs, on a Windows system typically Administrators) to the list by clicking Add entering the group name and clicking Finish. Scroll down to the Security Role Run As Bindings section and add icmadmin and the corresponding password. Press CTRL-S to save your changes.
  7. Note that the Problems view lists about 100 warnings concerning unused imports and calls to deprecated methods. These refer to the generated resources and can safely be ignored.
  8. Perform the steps described in 6.6 to deploy the three enterprise applications on the test server.
You are now ready to explore the sample process as described in the next chapter.

3. A Tour of the 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 DB2 Content Manager).

The new sample process provided with CM/WPS 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 WebSphere Process Server since the DB2 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/WPS 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 two different ways to create process instances either explicitly by an application or implicitly based on Content Event Handling. Explicit creation 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 can serve as a basis for custom development. Implicit creation 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.

  1. Click the box titled Mailroom and log on as Agent1 with password passw0rd (which by default is the same for all roles of the sample process).
  2. The Mailroom user's initial page contains three sections titled Create documents based on blank forms, Create documents based on predefined form data, and Create process instances for existing items


     
  3. The section titled Create documents based on blank forms can be used to create instances of the four item types XYZ_InsPolicy, XYZ_ClaimForm, XYZ_AdjReport, and XYZ_PolReport. The latter three are linked to a XYZ_ClaimFolder that has the attribute WF_OnCreate with a default value of ClaimsHandlingProcess. Creating an item of type XYZ_ClaimForm triggers the creation of an item of type XYZ_ClaimFolder which contains it due to auto-foldering. The creation of this folder triggers the creation of an instance of the ClaimsHandlingProcess which carries a reference to the claim folder due to the WF_OnCreate attribute and its default value (the process name).
  4. Since creating an item may involve entering many mandatory values, the section Create documents based on predefined form data can be used to create items of the three types based on pre-defined attribute values. These values make use of the DB2 Content Manager First Steps sample data and are expliticly defined in startProcessInstances.jsp. Click any of the links to open the corresponding form.
  5. The section Create process instances for existing items can be used to create process instances based on the sample data already importet into DB2 Content Manager during the 'Create Sample Data' step of the DB2 Content Manager First Steps application. Click Submit to run the default query /XYZ_ClaimFolder which locates all instances of XYZ_ClaimFolder and creates instances of the ClaimsHandlingProcess for each element of the result list. By adding additional conditions (as for example /XYZ_ClaimFolder/OUTBOUNDLINK[@LINKTYPE = "DKFolder"]/@TARGETITEMREF => XYZ_ClaimForm[@XYZ_ClaimNumber = "4-852369"]) the query can be refined to restrict the items for which process instances should be created to e.g. all claim forms with claim number 4-852369. Note that when starting processes for the DB2 Content Manager sample data based on a query you may see warnings in the console indicating that the policy can not be added to the folder since the folder already contains it. This is due to the fact that each folder of the sample data already contains instances of all three item types. The message can be ignored.

Import predefined documents


  1. This tour starts with the section Create documents based on predefined form data since this illustrates the use of content event handling and is based on existing data.
  2. Click Mary Twain in the section titled Claim Forms to display the attributes of a predefined claim form. Review the displayed values and make sure the claim number is a new unique value. If you re-use an already existing claim number the claim form will be added to an existing folder that is already part of a running process so no new process will be created (see 6.1 for details).
  3. Click Save to store an instance of the XYZ_ClaimForm item type in DB2 Content Manager. Due to auto foldering this triggers the creation of a corresponding XYZ_ClaimFolder. Since the XYZ_ClaimFolder item type has the attribute WF_OnCreate defined and pointing to a default value of ClaimsHandlingProcess this triggers the creation of a process instance.
  4. The console output of the test server confirms the creation of an item (-> Item created). If content event handling works properly, another message is displayed that says => Process started with ItemPID [...]. Note that the message prefix indicates its origin. Messages starting with -> originate from the Quick Start Client. Those starting with => result from the integration toolkit and if the prefix is >> they originate from the process. The messages => Looking up policy with number: ... and => Number of matching insurance policies for claim [...]: 1) indicate the successful completion of the first process activity (RetrievePolicy).
  5. The client now displays an Add part link that can be used to attach the actual document. Clicking Add part switches to the Import part page.


     
  6. Locate the TIFF image of a scanned claim form in <IBMCMROOT>\firststeps\data\4-852369.tif and click Import to add it to the new item. Note that the console output confirms the upload with a message (-> imported file of length: 27688 mime type: image/tiff). You may add another part by importing the incident photo <IBMCMROOT>\firststeps\data\1ABC089.jpg. Note that in this case you need to explicitly select the mime type JPEG from the list since automatic detection fails for files of this type.


     
  7. Clicking Create item in the menu leads back to the Mailroom home page from which further items can be created. For now we leave the Mailroom dialogue by clicking Logout at the right end of the client menu.

3.3 Data validation

The message => Number of matching insurance policies for claim [...]: 1 in the server console confirms that an appropriate insurance policy has been located in DB2 Content Manager which has the policy number as entered in the claim form. The RetrievePolicy service has retrieved this item from Content Manager and added it to the folder that is routed through the process.

  1. On the process diagram click the box Validate and Adjust and log on as Adjuster1.
  2. The adjuster's initial page shows the adjuster's worklist. It contains a single work item corresponding to the process instance that has been created in the previous step (Mary Twain's claim form). The worklist might be empty due to the process being in the 'Retrieve Policy' state. In this case the Refresh may need to be clicked to update the worklist to its most recent state. Note that the worklist display results from a combined query that returns item attributes (Date of Incident, Claim Number, etc.) as well as process properties (Activated, Work Item State). The console output shows the DB2 Content Manager query in the form >> Query [/XYZ_ClaimFolder[@ITEMID IN ("...")]]


     
  3. Click Fetch to check out this work item. This makes it unavailable for any other member of the AdjustersGroup and brings up the work item view. The console output confirms that the work item has been checked out with the message -> Work item claimed. Note that Adjuster1 now owns this work item. If another member of the AdjustersGroup runs a work list query by opening his work list page, this work item will not show up any longer.


     
  4. The work item page contains three sections titled Process activity, Folder, and Items in Folder. The Process activity section basically displays the input and output message of the staff activity that consists of the relevant process properties (input message) and of the controls which the adjuster needs to work with to complete this step of the process. The Folder and Items in folder section display the content-related information. The first column shows the folder or item name as specified by the 'represents item' property of the corresponding item type. The second column shows the item type or part number and the third/fourth column display attribute value pairs of the corresponding item or folder.
  5. Optional: At this point you may want to explore how a user would modify attribute values. You can do so by clicking Edit and for example change the value of the Street field in the address to 259 Blue Rd.. When clicking Save you will see the effect of the modification on the updated work item page.
  6. Click View to open the viewer in a separate window. Create an annotation (you may highlight a part of the document or put a note on it) which may be used to communicate important information to a human role (e.g. Underwriter) later in the process.
    Note that the Insurance Policy has been retrieved and added to the folder by the first activity of the process.
  7. Click the Add Report action in the folder section to add an item of type Adjuster Report. This opens the Edit attributes and parts page. Note that the claim number is already instantiated to the claim number of the folder. Enter values for the mandatory fields (marked by a red asterisk) as shown below and click Save to store the adjuster report in DB2 Content Manager.


     
  8. Click Add part and import <IBMCMROOT>\firststeps\data\4-852369_adjustment.tif. Click Work Item in the menu bar to return to the Work Item View and note that the Adjuster Report is now a member of the claim folder.


     
  9. Note that the collection point conditions require an additional Police Report before the process can continue. Click Complete in the 'Process activity' section to move the folder to the next step in the process to experience the effect of a collection point timeout.
  10. After 10 seconds (depending on the 'Remind me' setting) the following message shows up in the console view: Reminder: submit remaining documents for claim number 3-742019 iteration (1). Click Refresh in the menu bar of the Quick Start Client to refresh the adjuster's worklist. Notice that it again contains an entry referring to case 3-742019.
  11. Notice that the 'Reminder count' now has the value 1 since this is the first time the process has cycled back to the ValidateAndAdjust activity due to the collection point conditions not being met.
  12. In the 'Process activity' section set the number of required documents of type Police Report to 0 assuming that the police report is not required for a decision later in the process. This shows how collection point conditions can be set dynamically on a process instance.


     
  13. Click Complete to complete the adjuster's activity and forward the work item to the next step in the process. The console output displays the message -> Work item completed to confirm successful completion of this step.
  14. Since Adjuster1 has changed the number of required Police Reports to 0 the collection point condition is now met by the folder since it contains the three required documents: a ClaimForm, an Insurance Policy, and an Adjuster Report. The console output confirms that the collection point has been passed successfully with the message => Documents are ready for claim: 3-742019 and a confirmation is sent to the person that submitted the claim (=> Dear...). Furthermore, the following two messages are shown: => Claim Amount is large (10000.00) and => Fraud report for Mary Twain is good that result from the decision point and the Check Fraud History service respectively.
  15. Log out Adjuster1 to return to the process overview.

3.4 Approval or rejection

Since the adjuster report created in the previous step lists a claim amount of $10000, the claim is considered a large claim by the decision at the beginning of this section which moves it along the path with the two activities CheckFraudHistory and ReviewLargeClaim .

The CheckFraudHistory service is a service that decides, based on some data extracted from the relevant documents, if the claimant's fraud history is good or bad. This could be realized by a BI tool that investigates certain company-internal data bases such as statistics about incident locations, customer credibility, etc. Alternatively, it could be an external service provided by some sort of agency with which the insurance company shares a contract. The sample implements this as a Java-based service that returns a bad fraud history if the initial letter of the claimant is in the range 'A'...'L' and returns good otherwise.

  1. On the process diagram click the box Review Large Claim and log on as Underwriter1.
    The home page of the underwriter activity shows the Underwriter's worklist. It contains a single work item corresponding to case number 3-742019. Note that the columns in the work list differ from the adjuster's worklist in that they now contain the name of the current activity (members of the group UnderwritersGroup may perform either the ReviewSmallClaim or the ReviewLargeClaim activity) and the creation date of the adjuster report.


     
  2. Click Fetch to check out this work item and open the work item page.


     
  3. The Process activity section displays the result returned by the Check Fraud History service and the controls for approving or rejecting the claim and adding a justification. The justification is stored in a process variable and not in DB2 Content Manager. Thus it is available throughout the process and potentially stored in the process log but not made persistent in the content repository.
  4. Click View in the Actions column for the Auto Claim Form and investigate the annotations which the Adjuster has added to the document.
  5. Type OK into the field Justify decision, select Approve, and click Complete.
  6. The console output of the test server now displays the message =;> Dear Mr. Twain, your claim (3-742019) has been accepted. <Reason: OK>. Yours Sincerely XYZ_Insurance. Note that <Reason: ...< corresponds to a text module which might be rendered into an acceptable text by the communication service.
  7. => Pay claim subprocess started on item [...] [...] [...] indicate a subprocess that performs the corresponding financial transaction in parallel to the notification. Note that in place of a real BPEL process we simulate this activity by a simple Java class that implements the CMProcessInterface and displays this message.

3.5 Exploring alternative options

3.6 How the Sample Process is defined

This section points to some important concepts and artifacts in WebSphere Integration Developer and explains their role for the sample process.

Dependencies The Assembly Diagram

The Process Definition

There are a number of situations in which a step of the process might fail. The sample process illustrates the use of a fault handler by encapsulating all activities following the initial receive activity within a scope and attaching a fault handler to this scope. This fault handler catches faults of the type FolderDeletedFault that occur if the folder on which an active collection point condition is registered is deleted. See the throw activity ThrowFolderDeletedFault in the Data Validation segment of the process for a cause of this fault. The fault is thrown as a consequence of the COLLECTIONPOINT_ITEM_DELETED result code of the collection point service. The Initialize activity at the beginning of the process shows how faults can be thrown from within a Java snippet. Information about the fault is communicated with the variable FaultVariable of type ProcessFault. In our example ProcessFault only specifies a messageText. It may be extended to provide more details about the fault. By adding further fault handlers to the scope other types of faults can be managed accordingly.

4. Developing a Custom DB2 Content Manager / WebSphere Process Server 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 the Integration Quick Start workspace is organized

The following sections assume a basic familiarity with DB2 Content Manager Enterprise Edition V8.3, WebSphere Integration Developer V6, and WebSphere Process Server V6. 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 chapter 7 at the end of this document. From the point of view of business process creation we recommend the Business Integration samples that can be found in the Samples Gallery of the local WebSphere Integration Developer Information center which can be opened by clicking Help > Samples Gallery. We recommend working through at least one of the 'Build it yourself' style samples such as the Loan application sample in the Application Samples > Business Integration section and taking the time to look up new concepts in the redbooks or documentation.

From a resource perspective, a workspace of a custom solution that integrates DB2 Content Manager with WebSphere Process Server typically consists of the following three enterprise applications each consisting of a number of modules:

A solution that uses a custom Web-based (that may be built based on the JSF components of the BPC explorer) or Portal-based client only needs to deploy the first two enterprise applications while the Quick Start Client builts on top of the functions provided by the Integration Toolkit.

The following sections describe the individual elements of the Integration Toolkit and Quick Start Client that can be used to build on custom integration solution in more detail.

4.2 The Integration Toolkit

The Integration Toolkit is a set of artifacts (SCA components, Interfaces, Business Objects, EJBs, and Java classes) that support the creation of content-centric processes. See the figure below for a schematic representation of the Integration Quick Start architecture:

The yellow and red blocks mark the elements of the Integration Quick Start: the Claims Handling sample process, the Quick Start Client, and the Integration Toolkit. The CM-based user registry is a special case as it may be installed and used independently from the other elements of the Integration Quick Start. See section 4.9 for details on the CM-based user registry.

The Integration Toolkit provides building blocks for functions that are typically found in business processes that work with content. They are especially important for content-centric business processes but can also be found in processes that involve content but have a different main focus. This document refers to this set of common functions as content / workflow interaction patterns.

The Integration Toolkit offers building blocks for the following interaction patterns:

These building blocks are available in the form of SCA (Service Component Architecture) components, Enterprise Java Beans, and Java classes. The SCA components are the main vehicle for incorporating the functions offered by the Integration Toolkit into business processes. They are supported by interface definitions and business objects that define how the business process interacts with the SCA components. The EJBs provide the infrastructure needed to implement the Content Event Handling and Collection Point, and Combined Query patterns. The rest of this section provides some background about the available EJBs and their role within the Integration Toolkit.

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 (CMBPCIntegrationBeans\com\ibm\bpe\cm\CMBPCIntegrationStartupBean) to start and stop the asynchronous bean described below. Note that the startup bean starts when the enterprise application is started. It terminates when the enterprise application is stopped.

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 static methods in the CMBPCIntegration class which perform the following operations:

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

The Stateless Session Bean of the Quick Start Integration (CMBPCIntegrationBeans\com\ibm\bpe\cm\CMBPCIntegrationBean) provides a remote interface for the Combined Query function described in 4.8.

4.3 Creating a process based the Integration Toolkit

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

Details can be found in the sample process or in the step-by-step instructions below.

To create a new content-centric process proceed as follows:

  1. Start WebSphere Integration Developer and switch to the Business Integration view.
  2. In the menu click New > Project > Business Integration > Module and enter a name for the Module such as MyModule (the default location should be OK).
  3. In the project tree right-click MyModule and select Open Dependency Editor. In the Libraries section of the dependency editor click Add and select CMBPCIntegrationLibrary. Press CTRL-S to store the change and close the dependency editor.
  4. Double-click the assembly diagram of your new module to open the assembly editor.
  5. Drag CMProcessInterface from CMBPCIntegrationLibrary > Interfaces and drop it into the assembly editor and select Component with no implementation type.
  6. Select the new component and replace its default name Component1 with a more useful name in the properties view such as MyProcess.
  7. Right-click the component MyProcess and select Generate Implementation > Process. On the Generate Implementation dialogue you can define a folder for the process such as com.ibm.bpe.cm.myprocess.
  8. When you click OK a new process definition MyProcess is created based on the interface partner MyProcessComponent and is displayed with the process editor.
  9. In the Variables section to the right of the business process editor create five variables with the data types shown below:
    Variable name Data Type
    ItemId string
    ComponentId string
    VersionNo int
    ItemPid string
    ItemRef ItemRef
  10. Click the Receive activity and select the Details tab in the Properties view. Check Use Data Type Variables and assign the three variables ItemId, ComponentId, and VersionNo to the corresponding input parameters of the startProcess operation. You may now delete InputVariable from the list of variables.
  11. Drag CMServicesInterface from CMBPCIntegrationLibrary > Interfaces and drop it into the Reference Partners section at the right-hand side of the business process editor.
  12. Drag the symbol of an Invoke activity from the graphical menu of the business process editor and drop it right below the Receive activity (within the Sequence block).
  13. Click the new Invoke activity. In the Description tab of the Properties view replace the default name Invoke with CreateItemRef and in the Details tab click Browse and select the CMServicesInterface partner. Select the operation createItemRef from the list and assign the input variables (ItemId, ComponentId, VersionNo) to the corresponding input parameters and the output variable (ItemRef) to the output parameter.
  14. Press CTRL-S to store the project definition.
  15. Switch to the assembly editor. Note that the referenced partners have now changed so the assembly diagram needs to be updated. Right-click MyProcess and select Delete. Press CTRL-S to update the assembly diagram and wait for the progress information to signal completion of the build. Drag MyProcess from MyModule > Business Logic > Processes and drop it into the assembly diagram. Note that it now contains a small icon 1:1 on the right hand side that represents its partner link to CMServices.
  16. Drag CMServicesInterface from CMBPCIntegrationLibrary > Interfaces and drop it into the assembly editor right of MyProcess. Select Import with no binding on the Component Creation dialogue.
  17. Click the new component and replace its default name Import1 in the Description tab of the Properties view with CMServicesImport.
  18. Right-click CMServicesImport and select Generate Binding > SCA Binding.
  19. Select the Binding tab in the Properties view and click Browse. Select CMServicesExport on the SCA Export Selection dialogue and click OK.
  20. In the assembly editor right-click MyProcess and select Wire to existing. Note that this connects the process component MyModule with its referenced partner CMServicesImport.
  21. Press CTRL-S to save the changes to the assembly diagram. It should now look as shown below:



  22. Switch to the business process editor, click the background of the process definition and select the Java Imports tab in the Properties view. Add import com.ibm.bpe.cm.CMBPCConstants; to the (so far empty) list of Java imports.
  23. Drag the symbol of a Java Snippet from the graphical menu on the left and drop it right below the CreateItemRef Invoke activity.
  24. In the Description tab of the Properties view replace the default name Snippet with Initialize and switch to the Details tab.
  25. Select Java. On the confirmation dialogue click Yes and paste the following code fragment into the source code editor area of the Details view.

    ItemPid = ItemRef.getString(CMBPCConstants.BOATT_ITEM_REF_PIDSTRING);
setProcessCustomProperty(CMBPCConstants.PROCESS_PROPERTY_ITEMPID, ItemPid);
setProcessCustomProperty(CMBPCConstants.PROCESS_PROPERTY_ITEMID, ItemId);
setProcessCustomProperty(CMBPCConstants.PROCESS_PROPERTY_COMPONENTID, ComponentId);
setProcessCustomProperty(CMBPCConstants.PROCESS_PROPERTY_VERSIONNUMBER, VersionNo.toString());
  26. Press CTRL-S to store the updated process definition.
  27. Add further activities to the process as needed and proceed as described in 6.6 to deploy and run your new process.
  28. It is recommended to have a scope at the top level of the process so dedicated treatment can be established for errors that may show up during the process. The Claims Handling sample process shows an example how this can be done.

The CreateItemRef activity invokes the createItemRef operation of the CMServices component. Its implementation creates a DKItemPid object from the supplied ItemId, ComponentId, and VersionNo parameters and runs a Content Manager query that returns the missing information such as the server name and item type from the Content Manager Library server.

The Java snippet Initialize copies the values of the four variables ItemId, ComponentId, VersionNo, and the ItemPid stored in the variable ItemRef into custom properties of the process where it can be used by Integration Toolkit functionality such as Combined Queries or Collection Points.

The following sections describe the individual building blocks for content-centric processes that are provided by the Integration Toolkit in more detail.

4.4 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 DB2 Content Manager 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 process ClaimsHandlingProcess is started by submitting the item's itemId, componentId, versionNumber as input message to the process which needs to implement the appropriate interface of type CMProcessInterface. 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 process ClaimsHandlingProcess that carry this item.

With this synchronization mechanism, 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 in synch.

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 utility class CMBPCIntegration\com\ibm\bpe\cm\util\ContentEventHandling is called regularly from the asynchronous bean (CMBPCIntegration\com\ibm\bpe\cm\util\AsyncBeanWork) to see if a new process instance should be created or if process instances should be deleted. It scans the BPECONTENTEVENTS table 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 by the startup bean (CMBPCIntegrationBeans\com\ibm\bpe\cm\util\CMBPCIntegrationStartupBean) 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 or deleted. Rows are written to the BPECONTENTEVENTS table using database triggers. These triggers are automatically created by the Asynchronous Bean for DB2 Content Manager item types that contain the custom attributes WF_OnCreate or WF_OnDelete. The trigger is created on the underlying DB2 Content Manager Component Table (a table of the form ICMUTnnnnnsss where nnnnn and sss are sequences of numbers representing the component type ID and the segment ID respectively) by the startup bean. The startup bean deletes all existing triggers and replaces them with triggers that correspond to the current state of the library server database. Note that when adding or removing WF_OnCreate or WF_OnDelete attributes to/from item types, the server needs to be re-started (or the CMBPCIntegrationApp re-deployed) to ensure the Content Event Handling mechanism can pick up the change.

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 DB2 Content Manager transaction from the subsequent Check Content Event transaction so that the performance impact to the DB2 Content Manager transaction is minimal. The BPECONTENTEVENTS table is created by the startup bean if it does not yet exist.

In addition to this 'standard usage', 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:

4.5 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 an invoke activity that invokes the collectionPoint operation on the CMServices component.

To add a collection point service invocation to a content-centric process proceed as follows:
  1. In the Variables section to the right of the business process editor create three variables with the data types shown below:
    Variable name Data Type
    CollectionPointCondition CollectionPointCondition
    TimeoutSeconds int
    CollectionPointResult int
  2. Drag CollectionPointService from CMBPCIntegrationLibrary > Interfaces and drop it into the Reference Partners section at the right-hand side of the business process editor.
  3. Drag the symbol of an Assign activity from the graphical menu of the business process editor and drop it to the position where the collection point service should be inserted.
  4. Click the new Assign activity. In the Description tab of the Properties view replace the default name Assign with InitCollectionPointCondition and in the Details tab add three assignments to this activity as shown below (for illustration purposes we are using fixed values based on the sample data. Note that requiredItems is an array. To assign a value to elements of this array select Variable in the target section and click CollectionPointCondition... > requiredItems... > itemType. Note that this only displays the scalar variant of the query: /requiredItems/itemType. You need to manually enter the index value of the array into the query field so that it displays /requiredItems[1]/itemType. Note that array positions start with 1.







  5. Press CTRL-S to store the project definition.
  6. Drag the symbol of an Invoke activity from the graphical menu of the business process editor and drop it right below the Assign activity InitCollectionPointCondition.
  7. Click the new Invoke activity. In the Description tab of the Properties view replace the default name Invoke with CollectionPointService and in the Details tab click Browse and select the CollectionPointService partner. The operation is set to collectionPoint since this is the only operation available at this interface.
  8. Assign the input variables (ItemRef, CollectionPointCondition, TimeoutSeconds) to the corresponding input parameters and the output variable (CollectionPointResult) to the output parameter.



  9. Press CTRL-S to store the project definition.
  10. Switch to the assembly editor. Note that the referenced partners have now changed so the assembly diagram needs to be updated. Right-click MyProcess and select Delete. Press CTRL-S to update the assembly diagram and wait for the progress information to signal completion of the build. Drag MyProcess from MyModule > Business Logic > Processes and drop it into the assembly diagram. Note that it now contains a small icon 1:1 on the right hand side that represents its partner link to CMServices.
  11. Drag CollectionPointService from CMBPCIntegrationLibrary > Interfaces and drop it into the assembly editor right of MyProcess. Select Import with no binding on the Component Creation dialogue.
  12. Click the new component and replace its default name Import1 in the Description tab of the Properties view with CollectionPointServiceImport.
  13. Right-click CollectionPointServiceImport and select Generate Binding > SCA Binding.
  14. Right-click MyProcess and select Wire to existing. Note that this connects the process component MyModule with its referenced partner CMServicesImport.
  15. Press CTRL-S to save the changes to the assembly diagram.



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. The timeout value is typically used to trigger a reminder or corrective action to ensure the process instance does not wait forever.

The CollectionPointResult parameter returns a numeric status value that represents one of the following situations:

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

The Assign activity instantiates the input parameters of the collection point service. It submits the reference to the folder (ItemRef), and defines the collection point condition and timeout value as shown above. The case statements inside the Choice activity evaluate 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. Invoking the collection point service and evaluating its results is typically done inside a loop so the collection point service can be re-entered in case of a timeout as shown by the Claims Handling sample process. If the initialization also happens within the loop, collection point conditions and timeout values can be modified dynamically with each iteration to, for example, loosen the conditions in case of a timeout.

How the Collection Point Service is Implemented

Since the class implementing the collection point SCA component (CMBPCIntegration\com\ibm\bpe\cm\sca\CollectionPointServiceImpl) instantiates the ServiceImplAsync interface, the SCA infrastructure redirects calls to any of its operations (there only is one: collectionPoint) to the method invokeAsynch which has a caller ticket and service callback as parameters. invokeAsynch calls the collectionPoint method in CMBPCIntegration\com\ibm\bpe\cm\api\CMBPCIntegration where in- and output parameter mapping takes place. Then the condition is registered by the addCollectionPointRequest method in CMBPCIntegration\com\ibm\bpe\cm\util\CollectionPoint that writes it to a table BPECOLLECTIONPOINTITEMTYPES in the DB2 Content Manager library server.

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

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

SEQID           INTEGER NOT NULL PRIMARY KEY
CREATETS        TIMESTAMP NOT NULL DEFAULT CURRENT TIMESTAMP
CORRELATION     BLOB(1M) NOT NULL
ITEMID          VARCHAR(26) NOT NULL
TIMEOUT         BIGINT NOT NULL

The SEQID column contains a unique sequence ID serving as foreign key for the BPECOLLECTIONPOINTITEMTYPES table. The CREATETS column contains 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 CORRELATION column keeps a serialized instance of the CollectionPointCallbackInfo class that stores the serviceCallback and Ticket which the invokeAsynch method has obtained from the SCA infrastructure. The process engine uses this information to correlate the response message with the request message so it knows which process instance should be notified if the collection point condition evaluates to true. The ITEMID column is the Item ID of the folder to be checked. TIMEOUT stores the time in milliseconds at which the collection point condition times out

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

SEQID             INTEGER NOT NULL
ITEMTYPENAME      VARCHAR(254)
ITEMTYPEQUANTITY  INTEGER

The SEQID references a sequence ID of BPECOLLECTIONPOINTS (foreign key). 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.

There is a one-to-many relationship between BPECOLLECTIONPOINTS and BPECOLLECTIONPOINTITEMTYPES, based on the SEQID key. Any of these tables is created by the CMBPCIntegrationStartupBean if it does not already exist.

The method checkCollectionPoint() that is called by the asynch bean performs a (JDBC-based) 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() effectively joins these tables with the DB2 Content Manager Links, Items and NLS Keywords tables to identify all satisfied collection points within two requests 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 DB2 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 DB2 Content Manager item type names to numeric Item Type IDs 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).

4.6 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 CMServices component of the Integration Toolkit offers the following operations to extract attribute values from items or to evaluate conditions over attributes:

Each of these operations takes an item PID (ItemRef) as input parameter and either a single attribute specification in the form <itemTypeName>/<attributePath> or an AttributeSpecs data object that carries a list of individual attribute specifications.

<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 are the 'single specification, single value' variants of the attribute lookup. They return a single value based on a single attribute specification and should not be used for looking up attributes of item types where more than one instance may be stored in a folder. In this case the 'multiple specification, multiple values' variants getContentAttributes and getFolderContentAttributes should be preferred. They return arrays of values where each array corresponds to an item in the folder. Note that these variants can also be used to look up multiple attribute values within a single request to the library server.

The two variants getContentAttribute(s) and getFolderContentAttribute(s) differ in that the former looks up attributes of the folder while the latter looks up attributes belonging to items within the folder. Note that only a single level of embedding is supported by the Integration Toolkit. The table below summarizes the available variants:

attribute of folder attribute of item in folder
single spec, single value getContentAttribute getFolderContentAttribute
multiple spec, multiple value getContentAttributes getFolderContentAttributes

The following figure shows the typical use of a multiple attribute value lookup that consists of a preparational step that initializes the attribute specifications, the lookup service invocation, and an evaluation step that (in this example) prints the attribute values to the server's console.

The PrepareAttributeLookup activity assigns the two attribute specification XYZ_AdjReport/XYZ_LicPlate and XYZ_AdjReport/XYZ_ClaimAmount (not shown) to the variable AttributeSpecs that serves as input parameter to the 'multiple spec, multiple values' operation getFolderContentAttributes that looks up attribute values on items that reside in the folder.

The result of the getFolderContentAttributes operation is a data object of type AttributeValues that contains a list of attribute values.

The Java snippet DisplayAttributeValues retrieves the result list and prints their attribute values to the server log. Note that type conversion takes place while looking up values from the data object. It is important to understand that though an AttributeValue contains an element of type anySimpleType that corresponds to the class Object, it can not simply be retrieved as follows:

BigDecimal ca = (BigDecimal)claimAmount.get("value");

This leads to a class cast exception as claimAmount.get("value") returns a string value. Instead the following format needs to be used as in the example shown above:

BigDecimal ca = claimAmount.getBigDecimal("value");

Instead of printing the values to the server log, a typical use of attribute values is in conditional processing where 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. Since the values returned from an attribute lookup are mapped to Java classes they can be used in Java expressions that form case statements or link conditions. In the example above different paths of a process can be taken by comparing the claim amount value with a predefined threshold.

Alternatively, the boolean result of the operation evaluateCondition can be used in conditional processing to base a decision on a content query. evaluateCondition takes a Content Manager XPath expression as input parameter and returns true if the result of the query is non empty. The following substitutable parameters 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 DB2 Content Manager item routed through the process. 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 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 Content Manager Item ID associated with the process. This Item ID qualifies the search so that it only applies to the Content Manager item associated with the current process. In this example, the item type is Mortgage and the name of the Content Manager 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.7 Additional content services

The Integration Toolkit provides some additional content services that operate on the folder which is routed through the process

Folder Services

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.

setACL

The setACL service sets the ACL of an item to a new value. If this item is a folder, it recursively changes the ACLs of all items in the folder to match this new ACL. Note that only a single level of folder-containment is supported.

The input parameters of the setACL service are the ItemRef of the item to be re-indexed (usually the item routed through the folder) and the name of the new ACL.

reindex

The reindex service assigns a new item type to an item. Note that if this service is invoked on the item that is routed through the folder, the activity that invokes it needs to be followed by createItemRef and Initialize activities as done at the beginning of a content-centric process to ensure the information about this item is consistent. For details on createItemRef and Initialize see section 4.3.

The input parameters of the reindex service are the ItemRef of the item to be re-indexed and the name of the target item type. The source and target item type need to be compatible for the reindex operation to suceed as specified in the DB2 Content Manager documentation. This operation has no output parameter.

4.8 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 DB2 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 available on the session bean 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 List of result rows. Each result row is a List of columns that contains the values in the order in which they are specified by the select clauses of the query (first the process properties, then the item attributes). For details on how this can be used to implement the concept of a worklist see QuickStartClient\WebContent\listWorkItems.jsp.

4.9 The DB2 Content Manager-based user registry

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 (task), the process management system must decide which users should have access to the item. This is referred to as staff resolution. WebSphere Process Server 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 Server 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. WebSphere Process Server utilizes a pluggable interface to the underlying staff repository, and comes preconfigured with interfaces for LDAP, the WebSphere User Repository and a System directory.

One of the building blocks offered by the Integration Toolkit is the Content Manager-based user registry which uses the DB2 Content Manager user and group definitions to support group membership. This means that users only need to be defined once, using the DB2 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.

Note: Using a custom WebSphere User Registry affects all application running on the WebSphere Application Server such as the Administrative Console. With a dedicated WebSphere Application Server installation for DB2 Content Manager and Business 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 considered.

quickStartSampleRev2wps.zip contains a JAR file icmuserregistry.jar with the CM-based user registry that is ready to be used. To install it on a WebSphere Application Server proceed as follows:

Important: When using the integrated test environment with the BPE and HTM administrator roles mapped to AdminsGroup a corresponding group definition needs to be created in DB2 Content Manager using the Content Manager system administration client.

If the server log periodically shows the following sequence of messages: 

>> CM WAS User Registry - getUniqueUserId [...]
>> CM WAS User Registry - getUniqueGroupIds, user=ICMADMIN
>> CM WAS User Registry - check password for user icmadmin
Cleaning up CM connection...>> successful.

perform the steps described in section 6.11 to re-enable credential caching as described.

Section 6.8 describes how the user registry library can be exported from a Quick Start workspace. This may be important, e.g. if you want to replace the simple algorithm used to encrypt the password in bpecm.properties with a more sophisticated one. Note that the 'ROT13 encryption' only prevents the password from being obvious. This may be OK if proper file access rights are in place for the Application Server's install folders. For a real production use this method may need to be replaced with a more sophisticated encryption.

4.10 Customizing the Quick Start Client

The Quick Start Client is a generic Web-based client that does not cover the full range of capabilities offered by DB2 Content Manager and WebSphere Process Server but it provides what can be thought of as a reasonable set of typically used functions and illustrates the use of the Integration Toolkit. Since it is available as source code it can be extended and adjusted to fit the specific needs of a certain solution.

All process-specific information can be found in QuickStartClient\JavaSource\com\ibm\bpe\cm\util\ProcessData.java. This class needs to be modified when using the client with different roles and data. The following settings are typically subject to modification:

Global constants

Worklist definitions

A worklist defines certain aspects of the client's look and feel. listWorkItems.jsp lists the available work items based on a work list ID and showWorkItems.jsp displays the available actions based on this work list ID. When a user logs on to the system with a specific role, a work list ID must be provided as parameter to listWorkItems.jsp which it passes along to showWorkItems.jsp. The example customization of the Quick Start client has an initial page index.jsp from which users can log on to different roles of the sample process. When clicking on the map, a corresponding work list ID (WLID) is assigned so that each user sees the appropriate list of work items.

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

static public final int ROLE1_WLID   = 0;
static public final int ROLE2_WLID   = 1;
static public final int NUM_OF_WLIDS = 2;
static public final int DEFAULT_WLID = ROLE1_WLID;

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

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

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

...means that a user with WLID ROLE1_WLID may add instances of the item types djReport, FraudReport, and 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 .

Staff conventions

In- and output messages of participating tasks are implemented based on input and output data objects assigned to the staff operation in a WSDL file. We recommend a naming convention such as: <TaskName>TaskInterface.wsdl for the WSDL and <TaskName>Request.xsd for the input data object and <TaskName>Response.xsd for the output data object. The name of the input parameter in the WSDL should be request, the name of the output parameter response. JavaSource\com\ibm\bpe\cm\CompleteWorkServlet.java relies on this naming convention. If all properties of the output data object are of type String, this servlet automatically maps parameters of the HTML form to the corresponding properties of the output data object if the parameter name is identical with the name of the property. The WSDL and XSD files are stored in QuickStartClient\WebContent\WEB-INF\lib so they are in the runtime classpath of the Web application.

The method staffActions(String activityName, DataObject inDO) 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 properties of the output data object (<TaskName>Response.xsd) are of type String, no custom logic needs to be added to JavaSource\com\ibm\bpe\cm\CompleteWorkServlet.java as it automatically maps form values to output properties with the same name. If non-string-typed variables are involved, an additional conversion step is required in the process or custom logic needs to be added to this servlet.

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

static public String staffActions(String activityName, DataObject inDO) {

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

     if (activityName.equals("Review")) {
	   String textToBeReviewed = inDO.getString("TextToBeReviewed");
	   result = "<TD colspan=\"2\">\n" +
			    "Text to be reviewed:" + textToBeReviewed +
                "</TD>" +
				"<TD colspan=\"2\">\n" +
                "<SELECT name=\"msgpart.rating\">" +
				"<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;
}

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 .

Limitations of the QuickStartClient

Since the QuickStartClient is a sample, it is not considered a complete Content Manager or Process Choreographer client. However, as the this section should have demonstrated, it is not specific to the sample process but can be easily modified to support other content and process models. Individual functions can be added by extending the available source code. Here is a list of some of the client's limitations.

4.11 Considerations for production use

Chapter 2 explained the steps required to set up a test environment. This section briefly covers some aspects that are important when planning to move to a production environment.

Globalization and Accessibility

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 or ConnectionException.

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

Scalability and Performance

For long-running processes in a production environment we recommend to consider replacing the use of Cloudscape as platform for the BPE database with an enterprise-level database such as DB2 UDB. See the WebSphere Process Server documentation for details on how this is done.

To avoid the server termination problem apply the steps in 6.4. Disabling the just in time compiler is not an option in a production environment.

Security and User Management

For evaluation purposes the development environment set up in chapter 2 used a file based custom registry. However, in a production environment this is not recommended as it relies on a file that contains passwords in readable format. For use in a production environment we recommend to use either the Content Manager-based user registry or an LDAP directory server. The steps required to use the Content Manager-based user registry are described in section 4.9 and 6.8. Details on using an LDAP server can be found in the product documentation referenced at the end of this document.

It may be advisable to consider implementing a 'real' encryption method for the password stored in bpecm.properties. The sample offers a simple encryption method referred to as ROT13 which prevents the password from being obvious but this does not offer a real protection in cases where access to the Process Server's lib directory is not (or can not be) properly protected. CMConnectionManagement\com\ibm\bpe\cm\conmgmt\Environment.java supports the extension with stronger encryption mechanisms based on the configuration property ContentManagerAuthenticationPwdEncryption.

4.12 The project structure of a custom integration solution

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

The folder QuickStartClient\WebContent\WEB-INF\lib that is in the runtime classpath of the Quick Start Client needs to include the following resources: copies of bpe137650.jar, task137650.jar from <WPS_ROOT>\ProcessChoreographer\client, bpecmutil.jar from the same directory of the Integration Quick Start, and CMProcessInterface.wsdl from CMBPCIntegrationLibrary\com\ibm\bpe\cm\. Furthermore the WSDL and XSD files for the task interfaces are to be placed into this directory.

Create a process as described in section 4.3 adding functionality of the Integration Toolkit as described in the respective sections of this chapter. As tasks are added, adjust the definitions in QuickStartClient\JavaSource\com\ibm\bpe\cm\utils\ProcessData.java accordingly. For testing purposes it may be useful to create a modified QuickStartClient\WebContent\index.jsp that allows logging on to the process with different roles or starting the process either explicitly (using a query) or implicitly (using Content Event Handling).

It may be useful to disable the feature Automatically delete the process after completion during testing as this simplifies investigating error conditions since failed work items remain the process database and can be retrieved using the BPC Explorer. Note that if the process contains a collection point or one or more human tasks it needs to be defined as long running. Both settings, Process is long-running and Automatically delete... can be made on the Details tab of the process properties view. To switch to this view click the white background of the process definition in the BPEL editor and click the Properties tab. Click Details to switch to the details view. This displays two check boxes with which these properties can be dis- or enabled.

5. Invoking DB2 Content Manager Web Services from within a process

Service invocation is one of the key integration patterns in service orientation architectures (SOA). DB2 Content Manager V8.3 offers a powerful web service interface and thereby adds a standards-based access to the content repository which can be invoked from any service consumer. WebSphere Process Server V6 comes with a BPEL compliant business process engine (Business Process Choreographer) that allows orchestrating and choreographing (web) service calls. This chapter explains the steps needed to invoke DB2 Content Manager web services from a BPEL process and how to build an integrated solution based on web service technology.

Here is an outline of the scenario used in this chapter:

Important: If you want to use both the Content Manager Web Services and the Integration Toolkit you need to perform the steps in 6.10 to avoid a conflict with libraries in the classpath.

5.1 Setting up and configuring the system environment

This chapter assumes the following system configuration:

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

Details on how to install the DB2 Content Manager web service support can be found in the product documentation (see Further Reading). The Content Manager web services support installs an additional server cmwebsvc on the WebSphere Application Server. To perform the scenario described in this chapter the DB2 Content Manager web service server must be properly installed and running. To verify this point your browser to the URL shown below. Note that you may need to replace localhost with the name of the repository server and and you may need to add a port number.

To use the DB2 Content Manager web services in a Process Server environment, the following step needs to be performed to ensure proper treatment of namespaces.

Make sure you have installed WebSphere Integration Developer 6.0.1 with the WebSphere Test Environment (WTE) or an additional standalone WebSphere Process Server 6.0.1. No additional setup or configuration steps are required to work with the DB2 Content Manager web services.

5.2 Exporting the web service and data definition

In order to invoke a DB2 Content Manager web service, you need to export a WSDL package from the System Administration Client that contains WSDL and XSD files with information about...

Item type and attribute definitions are important ingredients of a DB2 Content Manager data model. When exporting the data model or parts of it to a WSDL package, the data definitions are translated to XSD definitions and thereby made available at the web service interface. If you plan to access your item type definition in a business process, make sure you defined them in DB2 Content Manager prior to exporting the web service definition. To export a complete data model into a WSDL package log on to the System Administration Client, select Data Modeling - Item Types and then right-click to bring up the pop-up menu. Select Export All to WSDL file. You can also export item types individually or subsets of item types by clicking them and selecting Export to WSDL file.

Specify a location for the resulting zip file. Then, extract the zip file to a location in your file system. As a result, you get the following four files:

Important: ensure that the port number and host namematches your settings of the cmwebsvc service. This information can be found near to the end of CMWebService.wsdl:

        <wsdl:port binding="tns:CMWebServiceBinding" name="CMWebServicePort">
            <soap:address
                location="http://localhost:9081/CMBSpecificWebService/services/CMWebService"/> 
        </wsdl:port>

5.3 Creating a new Project in WebSphere Integration Developer

Start WebSphere Integration Developer 6.0.1 (WID), point the workbench to a new empty workspace, and proceed as follows:

  1. Right-click in the Business Integration view and select New > Module. This opens the New Module window.
  2. Enter the module name QueryCM_Module and click Finish.
  3. Expand Business Logic, right-click Processes and select New > Business Process. The New Business Process window opens.
  4. Enter QueryCM_Process into the name field and click Finish. This creates the artifacts for a new business process based on a simple interface with a single input variable Input1 of type String. This variable will be used later to specify a DB2 Content Manager XPath query string.

When the process generation step is completed the WID screen look as follows:


5.4 Importing Web Service and Data Definition

In order to work with the DB2 Content Manager web services, you need to import both the web service definition and the data definitions (based on the item types) to WebSphere Integration Developer.

Note: You might have to disable XML schema validation before importing the Content Manager WSDL and XSD files. Select Window > Preferences > Validation and disable the XML Schema Validator checkbox.

  1. Right-click in the Business Integration view and select the Import … command from the pop-up menu.
  2. On the Import window select File system and specify the file system location where you previously stored the WSDL and XSD files that you have exported from the DB2 Content Manager System Administration Client.
  3. Click Select all and Finish.

Explore the imported definitions in the Data Object, Interface and Web Service Ports sections of the Business Integration view.

5.5 Modeling the BPEL process to invoke the DB2 Content Manager Web Services

In order to run our scenario, we need input and output messages for the RunQuery web service call. For result processing in a loop, we also need a counter and a variable to store an item from the result set.

  1. Define process variables based on the table below
    Variable name Data Type
    QueryRequest RunQueryRequest (CM definition)
    QueryReply RunQueryReply (CM definition)
    Item Item (CM definition)
    ResultCount int
    FirstName string
    LastName string


  2. Define a new partner for the BPEL process

  3. Define the BPEL Process

    Model the BPEL process according to the following layout by selecting activity types from the menu on the left of the BPEL editor and dropping them onto the appropriate location of the business process. While the activity stays selected, click the Description tab of the Properties view to enter the activity name.

    Note that this is an example of a non-interruptible process (micro flow) since it does not involve human activities (tasks) and potentially long-running services such as a collection point. Non-interruptible processes do not need to store information about intermediate process states in the process engine's database and run in a single transaction. If a process does not qualify as non-interruptable, this needs to be explicitly set by right-clicking the background of the BPEL editor and selecting Process is long-running in the Details pane.

  4. Further specify the activities as follows:

  5. Press Ctrl-S in the BPEL editor to store the process definition. Note that this builds the workspace in the background.

5.6 Assembling the module and testing the sample process

The QueryCM_Module will now be completed by connecting the sample process with the required partner. Then we describe how the business process can be tested using the BPC Explorer.

  1. Double click QueryCM_Module right above the Business Logic in the Business Integration view to open the assembly editor.
  2. Drag and drop the BPEL process QueryCM_Process you just modeled into the editor view.


  3. Drag CMWebServicePortType from the Business Integration view and drop it into the assembly area. The Component Creation window opens.
  4. Select Import with Web Service Binding and click OK. This creates a new import element with the appropriate interface and binding.
  5. With the new import element selected click the Description tab in the Properties view and enter CMWebService into the name field.
  6. Right-click any of the two elements and select Wire to existing to wire the process with its referenced partner.


Now that the module creation has been completed the new application is ready to be deployed and tested. Create a new server configuration pointing to a WebSphere Process Server installation and add your module to the server (right-click the server configuration, select Add and remove projects, and add QueryCM_ModuleApp to the list of configured projects). Start the server and use the BPC explorer to submit a new request to your business process (right-click the server configuration and select Launch > BPC Explorer). In the BPC Explorer start a new Process (click on My Process Templates, select QueryCM_Process and click on Start Instance). To test your business process, add /XYZ_AdjReport as the input string for the input message. This will return all adjuster report data stored with the DB2 Content Manager first steps sample data.


The console output created by the BPEL process looks as follows:


Please note that for simplicity of this description, no error handling has been implemented. In particular, the business process logic assumes that the Content Manager query returns solely items of type XYZ_AdjReport. If you specify an XPath query that results in a set of items of a different type, the business process will fail with an exception.

Extending and Aggregating the Service

With this business process, you have built a new service which implements a certain interface and performs a certain task. In the SOA programming model, it is straightforward to reuse this new service and aggregate it to create new services based on the existing ones. The SCA programming model in WebSphere Integration Developer allows you to export the new service in several different ways (e.g. as SCA service, web service or JMS service) and to use it within other modules.

6. Hints and Troubleshooting

6.1 Considerations when working with the sample

6.2 Starting the server and launching the administrative console

Option A: from within WebSphere Integration Developer
  1. In the Servers view of WebSphere Integration Developer right-click the name of your server profile and select start. This switches to the console view that displays the output messages of the server startup.
  2. Wait until the message Server server1 open for e-business shows up in the console view. Note that other messages may follow so it may not be the last one that shows up during the startup procedure.
  3. Switch to the Servers view, right-click the name of your server profile and select Run administrative console.
  4. If security is enabled you may see a security alert. Click OK to open the logon page with your browser. If your workspace preferences have Internet > Web Browser set to Internal Web Browser, the browser window opens in a view of your WebSphere Integration Developer. We recommend using an external browser which that uses a separate independent window.
  5. To stop the server log out from the administrative console and ensure that no changes are pending by saving or discarding uncommitted changes, right-click the server profile in the Servers view and select Stop. The message Server server1 is stopped. signals successful completion of the step.
Option B: from the command line
  1. Optionally clean up the server logs by deleting all files in the folder <WPS_PROFILE_HOME>\logs\server1.
  2. Start the process server by running the command script <WPS_PROFILE_HOME>\bin\startServer.bat (hint:you may want to create a script that cleans up the logs and then starts a process to automatize the cleanup).
  3. The startup is completed as soon as the message Server server1 open for e-business shows up. Note that other messages may follow so it may not be the last one that shows up during the startup procedure.
  4. Open <WPS_PROFILE_HOME>\logs\server1\SystemOut.log with an editor and search for a line that says Web Module adminconsole has been bound to admin_host[*:9060,*:9043]. The first number shown between the square brackets is the <ADMINPORT> and the second one is the <SECURED_ADMINPORT> that needs to be used if security is enabled.
  5. To start the administrative console, point your browser to <http://<HOSTNAME>:<ADMINPORT>/ibm/console (if security is not enabled) or <https://<HOSTNAME>:<SECURED_ADMINPORT>/ibm/console (if security is enabled).
  6. To stop the server log out from the administrative console and ensure that no changes are pending by saving or discarding uncommitted changes, run <WPS_PROFILE_HOME>\bin\stopServer.bat and wait for the message Server server1 is stopped. which signals successful completion of the step.

6.3 Clean up the process environment

  1. Stop the test server.
  2. Run the following advanced query in the DB2 Content Manager Client for Windows: /*[<Claim Number (Content Manager V8.1 Sample Attribute)> LIKE "3-%"] to identify all items created when running the Quick Start Client.
  3. Delete all items of the result list.
  4. Connect to icmnlsdb as icmadmin and drop the three tables bpecontentevents, bpecollectionpoints, bpecollectionpointitemtypes.
  5. Restart the test server. This re-creates the three tables.

6.4 Install JRE update on WebSphere Process Server

With the just in time compiler enabled the server may terminate due to a mismatch between the Java Runtime Environment and the legacy DB2 JDBC driver. Disabling the just in time compiler is a quick but undesirable fix with significant performance impact. It is recommended to update the Java Runtime Environment to the latest interim fix or fixpack to get rid of this problem. By the time this documentation is published, this is Service Release 4 that can be downloaded from this support page. The required files and instructions are on the support site. Here are some hints that help to install the update:

  1. Download the ZIP file of the update installer into a temporary folder and unzip it into the <WPS_HOME> folder.
  2. Download the interim fix into <WPS_HOME>\updateinstaller\maintenance.
  3. Run <WPS_HOME>\updateinstaller\update.exe.
  4. Verify the information on the update installer pages. The default settings should be OK. Click Next to proceed through the pages and Relaunch to re-start the update installer with the updated JRE. When the update has been completed successfully, click Finish to close the update installer.
  5. The Java Runtime Environment of the WebSphere Process Server has now been updated to the required fix level so the Just in Time Compiler can be re-enabled as follows:

6.5 Recreating the content viewer applet

The Quick Start Client uses a modified version of the DB2 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 DB2 Content Manager install directory and (re-)creates the JAR file for the modified viewer applet. This step should be performed whenever the code in TViewerApplet.java has been changed.
  1. Switch to the Physical Resources view of the business integration perspective.
  2. Expand QuickStartClient > WebContent.
  3. Perform the following steps to import cmbview81.jar into this folder.
    1. From the workspace menu select File > Import. The 'Import' window opens.
    2. Select File system and click Next >.
    3. Click the Browse button to the right of the From directory: field, locate the folder <IBMCMROOT>\lib, and click OK.
    4. In the field to the right select cmbview81.jar.
    5. Enter QuickStartClient/WebContent/appletViewer in the Into folder: field.
    6. Click Finish.
  4. Right-click QuickStartClient/WebContent/appletViewer/cmbview81.jar and select Refresh.
  5. Switch to the 'Package Explorer' view and perform the following steps to create the JAR file for the viewer applet. You need to re-run these steps if you have modified the source code of the viewer applet:
  6. In the 'Package Explorer' view right-click QuickStartClient/WebContent/appletViewer/appletViewer.jar and select Refresh.

6.6 (Re-)deploying the applications on the test environment

This section explains the steps required to optionally clean up the work space and (re-)deploy the three applications on the test environment.
  1. If any of the three applications CMBPCIntegrationApp, QuickStartClientApp, or ClaimsHandlingApp is currently deployed on the server, perform the following steps to undeploy them:
    1. right-click the server configuration in the Servers view, select Add and remove projects
    2. Click Select All, and click Finish to remove them.
    3. Wait for the progress indicator to signal completion of this step.
  2. Optional: from time to time it might be useful to clean up the workspace to ensure all data in and across projects is consistent. To clean up the workspace proceed as follows:
    1. On the main menu select Project > Clean. Ensure Clean all projects is selected and click OK. Wait until the progress information signals completion of the step.
    2. Click the Problems tab to check for potential problems.
    3. If the Problems view displays an error The project cannot be built until its prerequisite XXX is built. Cleaning and building all projects is recommended (where XXX is a project name such as CMBPCIntegration) you can get rid of this error with the following trick: on the main menu select Project > Build Automatically which switches off the automatic build mode. Do the same again to switch the automatic build mode back on again. This re-builds the projects and removes the error message. Wait for the progress information that says Building workspace to complete.
  3. Make sure no errors show up in the Problems view (warnings may be ignored).
  4. Switch to the Servers view, right-click the server configuration, select Add and remove projects, click Select All, and click Finish.


     
  5. Wait for the progress information to signal successful deployment of all three applications.
  6. Inspect the console output (or <WPS_PROFILE_HOME<\logs\server1\SystemOut.log and <WPS_PROFILE_HOME<\logs\server1\SystemErr.log) for potential problems.
  7. Optionally investigate the lines that start with >>. These contain output from the Integration Toolkit. The startup sequence should, for example, list the message >> CMBPCIntegration services started that signals successful initialization of the asynchronous bean. If Content Event Handling is used (based on attributes WF_OnCreate or WF_OnDelete, you may see messages of the type >> Dropping trigger WP... or >> Adding trigger ... to column ... of table .... If Content Event Handling or the Collection Point mechanism is used the first time, the startup sequence will contain messages that indicate the creation of the corresponding tables (BPECONTENTEVENTS, BPECOLLECTIONPOINTS, and/or BPECOLLECTIONPOINTITEMTYPES. Potential warnings may savely be ignored.

6.7 Manually Starting and Stopping ClaimsHandlingApp

The enterprise application ClaimsHandlingApp can be started as follows:

  1. In the WebSphere administrative console follow the links to Applications > Enterprise Applications > ClaimsHandlingApp.
  2. Check the box left of the ClaimsHandlingApp application. Click the Start button. Wait until the status column displays a green arrow.
  3. Follow the links to Applications > Enterprise Applications > ClaimsHandlingApp > EJB Modules > ClaimsHandlingProcessEJB.jar > Business Processes. Check if the ClaimsHandlingProcess template has been started. If not, click the Start button and wait until the progress information disappears.

To stop an enterprise application ClaimsHandlingApp perform the following steps:

  1. Right-click the server configuration and select Launch > BPC Explorer
  2. Log on as WebSphere administrator (e.g. wasadmin or icmadmin) and select Process Instances > Administered by me.
  3. Select all available process instances and click terminate.
  4. If any process instances are left: select them and click Delete.
  5. Log off from the BPC Explorer.
  6. Start the WebSphere administrative console and log in as administrator.
  7. Follow the links to Applications > Enterprise Applications > ClaimsHandlingApp > EJB Modules > ClaimsHandlingProcessEJB.jar > Business Processes, select the ClaimsHandlingProcess template and click the Stop button. Wait until the progress information disappears.
  8. Follow the links to Applications > Enterprise Applications > ClaimsHandlingApp.
  9. Check the box left of the ClaimsHandlingProcess application. Click the Stop button. Wait until the status column displays a red cross.

6.8 (Re-) generating a JAR file for the DB2 Content Manager-based user registry

Perform the following steps to generate a (new) icmuserregistry.jar from your workspace:

  1. In WebSphere Integration Developer select File > Export from the menu and select JAR file.
  2. On the JAR Package Specification window select CMConnectionManagement
  3. Enter <WPS_HOME>\lib\icmuserregistry.jar into the Select the export destination field.
  4. The message JAR export finished with warnings. See details for additional information may show up where the details say /CMConnectionManagement/META-INF/MANIFEST.MF was replaced by the generated MANIFEST.MF and is no longer in the JAR.. This message can safely be ignored. Click OK to close the message window.

6.9 Re-activating the console output in WebSphere Integration Developer

With global security enabled, the console view of WebSphere Integration Developer may refuse to display log files. A solution for this problem is described in this Technote.

6.10 Avoiding conflicts when invoking CM WebServices from a process that also uses the Integration Toolkit

The XSD specification allows different data types to have the same QName. cmbwebservices.jar in <IBMCMROOT>\lib contains an instance of cmbmessages.xsd which shares QNames with definitions in cmbmessages_modified.xsd that has been imported from the Content Manager administration client. To ensure definitions with the same QName occur only once on the classpath, perform the following steps when using the Web Services in combination with the Integration Toolkit:

  1. Start the administrative console and log on as icmadmin
  2. In the navigation pane select Servers > Application Servers > server1
  3. Locate the section Server Infrastructure to the right, expand Java and Process Management, and select Process Definition. In the Additional Properties section click Java Virtual Machine.
  4. Click Custom Properties in the Additional Properties section to open the custom properties of the JVM.
  5. Click ws.ext.dirs and replace ${IBMCMROOT}/lib; with ${IBMCMROOT}/lib/cmbsdk81.jar;${IBMCMROOT}/lib/cmb81.jar;${IBMCMROOT}/lib/log4j-1.2.8.jar;.
  6. Click OK to update the property.
  7. Click Save on top of the window to open the Save to Master Configuration window. Click Save to make the changes permanent.
  8. Log out from the administrative console and re-start the server.

The following steps are only needed if you plan to use the Quick Start Client:

  1. In WebSphere Integration Developer open the deployment descriptor of the Quick Start Client as follows:
  2. Switch to the Deployment tab and scroll down until the Shared Library section appears at the lower right corner.
  3. Expand the section and click Add to add a new library.
  4. Enter ICMLIB into the Name: field.
  5. Optional but recommended: enter DB2 Content Manager libraries for use with the CM/WPS Integration Quick Start into the Description: field.
  6. Enter the following libraries into the Class path: field by clicking Add, entering the path, and clicking OK:
  7. Click OK to store the definition.
  8. Press CTRL-S to store the updated deployment descriptor and close the editor.

6.11 Re-enable credential caching for the Content Manager-based user registry

If the following sequence of messages shows up test server console periodically (approx. every second) this means that credential caching is disabled and the server has to go to DB2 Content Manager each time it needs to authenticate the user icmadmin. Perform the steps listed below to re-enable credential caching.

>> CM WAS User Registry - getUniqueUserId [...]
>> CM WAS User Registry - getUniqueGroupIds, user=ICMADMIN
>> CM WAS User Registry - check password for user icmadmin
Cleaning up CM connection...>> successful.

  1. Launch the administrative console of the test server and log on as icmadmin.
  2. In the navigation panel select Security > Global Security.
  3. In the General Properties section set the Active authentication mechanism to Simple WebSphere Authentication Mechanism (SWAM) and click OK.
  4. Click Save on top of the window to open the Save to Master Configuration window. Click Save to make the changes permanent.
  5. Re-start the server.
  6. Repeat the above listed steps to set the Active authentication mechanism back to Lightweight Third Party Authentication.

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.