Develop P8 4.0 BPM custom components using Eclipse

Prerequisites

It is assumed that you are knowledgeable with the different components of the IBM FileNet P8 platform, such as Application Engine (AE), Content Engine (CE), and Process Engine (PE). A working P8 environment with the latest P8 4.0 fix packs applied is assumed, and a minimum P8PE4.0.2-001 is required. In addition, familiarity with Eclipse Integrated development environment (IDE) is preferred. However, step-by-step explanations are presented.

Introduction

Custom actions in a workflow are operations of a component queue. For example, provided in the standard installation of the P8 BPM server is the CE_Operations component queue. This queue provides operations such as file, unfile, getStringProperty, setStringProperty. A Java component queue has the operations defined from the public methods of the Java class.

Figure 1 illustrates the following development process for a custom component:

1. Identify the business need for the component
2. Implement the custom component
3. Iterative test and debug the custom component in a P8 BPM development system
4. Deploy the component to the P8 BPM production system

Being able to develop and debug the custom component in the BPM development environment in Eclipse is important to guarantee the correctness of the component and expedite the production deployment of the component.

This article shows you the following:

• How to set up Eclipse to be a P8 development environment using the pre-installed components for P8 BPM.
• Steps for develop, deploy, and debug a simple Hello World component without leaving the Eclipse IDE. Tips and tools are also described to help simplify the test-debug iteration process. This includes:
  • The HelloWorld class
  • The shortcut to configure the Java class to be a BPM Java component queue in Eclipse, instead of through the Process Configuration Console application.
  • The shortcut to start the P8 BPM Component Manager in Eclipse, and thus enable the debugging of the Java component.

Back to top

P8 development environment

A P8 application uses the Content Engine (CE) API and the Process Engine (PE) API through the following libraries:

• The CE API: Jace.jar and the transport protocol for the API. For a stand-alone application, the recommended transport protocol is the CE API through the Web services interface. The library can be found on the PE server, \fnsw\CE_API directory and its subdirectories.
• The PE API: pe.jar, pe3pt.jar, peResources.jar –- These files can be found on the PE server, in the \fnsw\bin directory.

Set up Eclipse

See the Resources section for downloading Eclipse 3.3 or later. In this article, an Eclipse project is created, containing references to the CE and PE API libraries. Follow these steps to create the user libraries in Eclipse:

1. Create a directory for the Eclipse workspace, for example, c:\SampleWS.
2. Create directories for the P8 CE and PE libraries under this workspace directory, for example:
   • C:\SampleWS\P8Libraries\CE_API
   • C:\SampleWS\P8Libraries\PE_API
3. Copy the entire directory tree content from the PE server \fnsw\CE_API to C:\SampleWS\P8Libraries\CE_API.
4. Copy the pe.jar, pe3pt.jar, and peResources from the PE server \fnsw\bin directory to the corresponding PE_API, c:\SampleWS\P8Libraries\PE_API.
5. Open Eclipse, and select the C:\SampleWS directory for the Workspace directory.
6. Create PE_API and CE_API user libraries for use in the Eclipse workspace by selecting the Window > Preferences menu option in Eclipse.

• PE_API user library contains

C:\SampleWS \P8Libraries\PE_API \pe.jar
C:\SampleWS \P8Libraries\PE_API\ pe3pt.jar
C:\SampleWS \P8Libraries\PE_API\peResources.jar 
        

• CE_APIuser library contains

C:\SampleWS\P8Libraries\CE_API\lib\Jace.jar,
C:\SampleWS\P8Libraries\CE_API\lib\log4j.jar, 
C:\SampleWS\P8Libraries\CE_API\wsi\lib\wasp.jar

These libraries can then be added to the Java projects created in the workspace to access the PE and CE APIs.

Command line arguments for P8 applications

The command line to start a Java application using the P8 4.0 PE API needs to have the following classpath and JVM parameters:

• classpath pe.jar;wasp.jar;Jace.jar;pe3pt.jar;peResources.jar
• Djava.security.auth.login.config=[CE_API]\config\jaas.conf.WSI
• Dwasp.location=[CE_API]\wsi
• Dfilenet.pe.bootstrap.ceuri=[CE URI for WSI]

In this article, the different applications share similar JVM configurations. After one configuration is set up, it can be duplicated and revised for other classes.

Back to top

A Hello World Java component

A Hello World component queue will be developed to be used in a workflow. Associated with this component queue is the HelloWorld Java class. The class contains one method, sayHello, with the following method signature

	public String sayHello(String customer);

While this seems to be a simple method, the objective of this section is to show shortcuts enabling the component development entirely in Eclipse. Therefore, simplifying the iterative process of developing, testing, and debugging custom components for P8 BPM.

This section describes:

• The HelloWorld class
• How to configure the Java class to be a BPM Java component queue in Eclipse, instead of through the Process Configuration Console application.
• How to run the P8 BPM Component Manager in Eclipse. Thus, enabling the debugging of the Java component.

Develop the component

To develop the component, perform the following steps:

1. Create a Java project named PEComponents.
2. Add the user libraries CE_API and PE_API to the project.
3. Create a new package, com.filenet.pe.components.
4. Create a new class for the package HelloWorld.
5. Edit the class to implement the sayHello method as follows:

   package com.filenet.pe.components; publicclass HelloWorld { public String sayHello (String customer) { return "HELLO "+customer+". How was your day on "+ new java.util.Date().toString(); } }

   
   
6. Build the project.

Configure the component queue in Eclipse

Normally, the class needs to be packaged into a JAR file to be referenced by the Process Configuration Console applet when the component queue is created. This manual step can be time consuming and error-prone. This section shows how to deploy the component directly within Eclipse.

To run a P8 BPM application, the following information should be gathered:

• The CE server URI
• The PE user and password
• The PE connection point

To configure a component queue, the following information should be gathered:

• The component queue name
• The name of the Java Authentication and Authorization Service (JAAS) context for use by the component queue
• The user and password to be used in the JAAS context for the component
• The name of the Java class
• The methods to be used as operations for the queue

Starting in P8PE4.0.2-001, the programmatic creation of the component queue is possible with the tool filenet.vw.integrator.base.PEComponentQueueHelper. Table 1 lists the parameters for the tool.

Set up Eclipse to run filenet.vw.integrator.base.PEComponentQueueHelper

To set up Eclipse to run filenet.vw.integrator.base.PEComponentQueueHelper, perform the following steps:

• Create a Run Configuration for filenet.vw.integrator.base.PEComponentQueueHelper. Select the Run/Open Run Dialog… menu option.
• Double-click on the Java application to create a new configuration.
• Enter PEComponentQueueHelper for Name and filenet.vw.integrator.base.PEComponentQueueHelper for the Main class.
• On the Arguments tab, set the following values using the information in Table 2. Replace the parameter values with that of your environment. For an example, see Figure 2.

After running the PEComponentQueueHelper, use the Process Configuration Console to verify that the component queue has been created with the specified queue name, JAAS information, and operations.

Use the Process Designer applet to create and launch a workflow with a step using the component queue. See Figure 3 for an example.

Run Component Manager in Eclipse

Component Manager runs as an independent Java application on the application engine. It is a PE API application polling component queue for work. It can be set up to just process specific queues instead of all component queues. At initialization, Component Manager instantiates an object of the class for the custom component and sets up the necessary JAAS framework that fit the component needs for accessing its own resources (such as a JDBC connection).

When a work object arrives in the queue, the Component Manager invokes the corresponding method of the class on the class object. Multi-threaded custom components run in multiple threads, where each thread has its own class object. Debugging a custom component really means debugging Component Manager.

This section discusses how to set up Eclipse to run Component Manager, which allows for an easy way to debug the component.

Component Manager JVM options and parameters explained

A sample of the command line to execute an instance of Component Manager is given below:

"C:/Program Files/FileNet/AE/Router/JRE/bin\java"
 -Dfilenet.pe.bootstrap.ceuri=http://hqamber:9080/wsi/FNCEWS40DIME/ 
"-Dwasp.location=C:/Program Files/FileNet/AE/Router/../CE_API/wsi" 
"-Djava.security.auth.login.config=
   C:/Program Files/FileNet/AE/Router/taskman.login.config”
"-Djava.security.policy=C:/Program Files/FileNet/AE/Router/taskman.policy" 
-Dfilenet.PE.NOWS=true –Xrs
 -cp "C:\Program Files\FileNet\AE\Router\lib\pe.jar;C:\Program Files\FileNet\AE\Router\
lib\peResources.jar;C:\Program Files\FileNet\AE\Router\lib\xml-apis.jar;C:\Program Files\
FileNet\AE\Router\lib\xercesImpl.jar;C:\Program Files\FileNet\AE\CE_API\lib\Jace.jar;
C:\Program Files\FileNet\AE\Router\lib\saaj.jar;C:\Program Files\FileNet\AE\Router\lib\
wsdl4j.jar;C:\Program Files\FileNet\AE\CE_API\wsi\lib\wasp.jar;C:\Program Files\FileNet\
AE\Router\lib\mailapi.jar;C:\Program Files\FileNet\AE\Router\lib\axis.jar;
C:\Program Files\FileNet\AE\Router\lib\axis-schema.jar;C:\Program Files\FileNet\AE\
Router\lib\commons-logging.jar;C:\Program Files\FileNet\AE\Router\lib\
commons-discovery.jar;C:\Program Files\FileNet\AE\Router\lib\jaxrpc.jar;C:\Program Files\
FileNet\AE\Router\lib\juddi.jar;C:\Program Files\FileNet\AE\Router\lib\addressing.jar;
C:\Program Files\FileNet\AE\Router\lib\Sandesha.jar;C:\Program Files\FileNet\AE\
Workplace\WEB-INF\lib\p8ciops.jar;C:\Program Files\FileNet\AE\Workplace\WEB-INF\
lib\javaapi.jar;C:\Program Files\FileNet\AE\Workplace\WEB-INF\lib\p8toolkit.jar;
C:\Program Files\FileNet\AE\Workplace\WEB-INF\lib\p8workplace.jar;
C:\Program Files\FileNet\AE\Router\lib;C:\Program Files\FileNet\AE\Workplace\WEB-INF"
 filenet.vw.integrator.base.VWComponentManager 
/named
/routerURL hqruby_600
/userName=-1 
/password ahuFjQT6oj5HekeMmh1zsB1Uddf= 
/registryPort 32771 
/eventPort 32773 
/registryName FileNet.VW.VWComponentManager.hqruby_600.CE_Operations
/queues=CE_Operations

While there are the typical parameter, such as classpath and the PE API required properties (wasp.location and filenet.pe.bootstrap.ceuri), the following are worth a closer look:

• JAAS configuration file specified through –Djava.security.auth.login.config, for example:

"-Djava.security.auth.login.config=
  C:/Program Files/FileNet/AE/Router/taskman.login.config"

By default, it is taskman.login.config. However, it can be any JAAS configuration file with the following requirement:

FileNetP8 stanza must be present containing the appropriate login module to connect to the CE depending on the CE transport protocol.

By default, when running outside of an application server, the Web Server Interface (WSI) transport protocol is recommended. Therefore, the taskman.login.config has the following:

		FileNetP8
		{
		   com.filenet.api.util.WSILoginModule required debug=false;
		};

In addition, the JAAS configuration file needs to contain the JAAS configuration context for the component queue. The JAAS context should have this line:

		    	filenet.vw.server.VWLoginModule required;
		
		For example:
		Sample
		{
		    filenet.vw.server.VWLoginModule required;	
		    sample.module.SampleLoginModule required debug=true;
		};

This explains the CE_Operations component queue that has CELogin as the JAAS configuration context. Therefore, the out-of-the-box (OOTB) taskman.login.config has:

   CELogin
   {
   filenet.vw.server.VWLoginModule required routerurl="hqruby_600";	
   com.filenet.wcm.toolkit.server.operations.util.CELoginModule required credTag=Clear;
    

Note that routerurl is no longer required for the VWLoginModule.

Following is a sample taskman.login.config file:

CELogin
{
  filenet.vw.server.VWLoginModule required routerurl="xx";
  com.filenet.wcm.toolkit.server.operations.util.CELoginModule required credTag=Clear;
};

HelloWorldLogin
{
    filenet.vw.server.VWLoginModule required;
};

FileNetP8
{
    com.filenet.api.util.WSILoginModule required debug=false;
};
            

• Component Manager parameters are explained in Table 3.

It is recommended that a command line to stop Component Manger should be used instead of the merciless terminate or kill. An instance of Component Manager can be stopped by re-issuing the same command line for starting with the additional /unbind option.

Set up Eclipse to run Component Manager

As explained above, a JAAS configuration file is needed. Use the sidebar above as an example for the file, or copy the taskman.login.config located in the router directory and add the HelloWorldLogin JAAS context stanza:

	HelloWorldLogin
{
 filenet.vw.server.VWLoginModule required;
};
    

Put this file to a directory, for example: C:\SampleWS\config.

Duplicate the PEComponentQueueHelper configuration in the Run Dialog, and set:

• Component Manager for Name
• filenet.vw.integrator.base.VWComponentManager for Main Class

On the Arguments tab, set the parameters according to Table 4. See Figure 4 for examples.

-Djava.security.auth.login.config=${workspace_loc}/config/taskman.login.config
-Dwasp.location=${workspace_loc}/P8Libraries/CE_API/wsi
-Dfilenet.pe.bootstrap.ceuri=http://CEServer:CEPort/wsi/FNCEWS40DIME/

Create a run configuration to stop Component Manager by duplicating the “Component Manager” run configuration, and name it Component Manager STOP.

Add /unbind to the program arguments. See Figure 5.

Before debugging the Component Manager, make sure that you add a breakpoint in the sayHello method and make sure that all other Component Manager instances for the same PE connection point have been stopped. Otherwise, work in the queue is picked up and processed by those instances.

As the Component Manager processes the work items in the HelloWorldQ and invokes the sayHello method for the step, you can then examine the values of the parameters or single step through the instructions in the method easily.

Run the Component Manager STOP configuration to stop the running Component Manager instance.

Back to top

Conclusion

This article shows tips and shortcuts in the development process of a custom component for the IBM FileNet BPM. With this knowledge, tracing is not the only choice for debugging the component while it is in development, thus shortening the time to production. In addition, the sample steps show in details how other P8 applications can be set up for debugging in Eclipse with the P8 PE Component Manager as an example. Users of other Java IDEs could use this information to set up their development environment for debugging P8 applications as well.

Resources

Learn

• FileNet Business Process Manager page: Find more information about the IBM FileNet Business Process Manager.
  
  
• Java Authentication and Authorization Service (JAAS) Reference Guide: Discover information regarding the JAAS framework.
  
  
• developerWorks Information Management zone: Learn more about Information Management. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• developerWorks Architecture zone: Get the resources you need to advance your skills in the architecture arena.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

Get products and technologies

• Eclipse can be downloaded at the Eclipse home page.
  
  
• Download IBM product evaluation versions and get your hands on application development tools and middleware products from IBM Information Management, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Dao-Quynh is a senior software developer for P8 BPM. She is the architect for the P8 BPM Integration tier including Web services, process orchestration, the Web services API, and the Component Integrator.

Indrajit Poddar (IP) is a member of the Strategy, Technology, Architecture, and Incubation team at IBM Software Group Strategy, where he leads several integration PoCs for building composite business services.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Develop P8 4.0 BPM custom components using Eclipse
• P8 development environment
• A Hello World Java component
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Information Management on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers