Create a business process portlet application with WebSphere Process Server V6 using Business Process Choreographer APIs

Document options Document options requiring JavaScript are not displayed Discuss Sample code My developerWorks needs you! Connect to your technical community Rate this page Help us improve this content

Level: Intermediate

Sean (Chunhong) Gu (guc@us.ibm.com), Enterprise Application Architect , IBM

21 Jun 2006

This article shows you how to integrate a portal application with IBM WebSphere Process Server V6 using WebSphere Business Process Choreographer APIs. It's intended for portlet developers, business process and portal integration specialists, and architects. Downloadable sample code includes the functionalities used most to help get you started. You should have a basic understanding of Business Process Execution Language, WebSphere Business Process Choreographer, WebSphere Portal, and Rational Application Developer. Additionally, you should have basic knowledge of Lightweight Directory Access Protocol (LDAP) and Java 2 Platform Enterprise Edition (J2EE) security when you use role-based staffing in the sample implementation.

Introduction

Today, portal integration becomes an integral part in many service-oriented architecture (SOA) applications. An engaging graphical user interface (GUI) presence, plus the inherent portal features, add significant value to a business process application, especially the long-running process application that requires human interactions. This article walks you through a process portlet application using the APIs that are based on the Business Process Choreographer (BPC) programming model, which is part of IBM® WebSphere® Process Server V6.

It shows you how to configure and integrate portal components (including security) with the business process engine. The sample portlets and configuration help you develop a complete process portal application. The programmatic integration between portal and process server using BPC API enables you to build a highly flexible and efficient process portal solution with fully customizable options.

Sample scenario

A sample scenario (Figure 1) is created to help you integrate the process portlet application with ease. A simple business process with a human task activity is used to illustrate the human interaction between portal and process server. A simple order business process, SimpleOrderProcess (2) and a customer service human task, CustomerService (3) are represented as the two types of SCA components that BPC supports. The process starter initiates the business process from the Order Initiator Portlet (1), and the human task is handled via the Customer Service Portlet (5). When the security is enabled, the proper role will be assigned from the Staff Plugin (4) depending on the Human Task settings.

In our scenario, the human task portlet accesses a Participating Human Task, which is a Standalone Task (human task component). However, the code sample applies to Inline Task (defined within a business process) as well. Generally, the Standalone Task, packaged as a service component, will be chosen when it's reused in different situations, while the Inline Task will be used when a business process is part of the task context.

The process integration used in this scenario is loosely-coupled between the portal and the process server.

Environment requirement

The sample scenario is created and tested with WebSphere Process Server Version 6, using WebSphere Portal V5.1.0. It's recommended that you use the supported WebSphere Portal V5.1.0.3 on top of WebSphere Process Server V6.0.1.

The following environment setup is required with WebSphere Process Server V6:

Important: Make sure you include the task137650.jar and bpe137650.jar in the process server's WPSlib, as the 137650 jar files contain the Enterprise JavaBean (EJB) stubs required for remote EJB access.

1. Go to the WebSphere Process Server Admin Console and choose Environment => Shared Libraries.
2. Click the WPSlib link.
3. Include both jar paths in the Classpath, and then click OK.
4. Restart the server.

Developing process portlets using BPC APIs

This section introduces BPC APIs and shows you two portlets that interact with business process and human task using Business Flow Manager API and Human Task Manager API respectively.

BPC API overview

WebSphere Process Server V6 provides multiple interfaces to business processes and human tasks. It includes the Service Component Architecture (SCA) programming model, the WebSphere administration model, and the Java™ 2 Enterprise Edition (J2EE) and Java programming model. For an external client access, the SCA Interfaces or the BPC interfaces can be used. In the SCA programming model, the client uses the SCA service manager to locate a service, creates data objects exchanged with the service, invokes methods on the service, and finally processes output or exceptions returned from the service (BPC Programming Model).

This article uses the generic BPC EJB APIs to interact with business processes and human tasks. There are actually two respective sets of APIs: Business Flow Manager and Human Task Manager.

The Business Flow Manager EJB API can be accessed either via remote or local EJB interface:

• BusinessFlowManager provides a remote Enterprise JavaBeans (EJB) interface.
• LocalBusinessFlowManager provides a local EJB interface.

The Human Task Manager API is also implemented as an enterprise bean, with the following interfaces that conceptually provide the same API functionality:

• HumanTaskManager provides a remote EJB interface.
• LocalHumanTaskManager provides a local EJB interface.
• HumanTaskManagerDelegate provides an interface for clients that abstracts from the use of local or remote interface use (BPC Programming Model).

The sample implementation in this article uses the remote EJB interface for both business flows and human tasks, because the portal client and process server sit in a different JVM space.

Creating a simple business process

We create a very simple business process with a standalone human task using an interface that includes a complex data type object Customer, as seen in Figure 2.

The business process is developed using the current version of WebSphere Integration Developer (WID) V6.0.1. The project interchange file from the WID is included in the Downloads section for your reference.

Setting up Rational® Application Developer

In our sample application, we develop a JSR 168 portlet application using Rational Application Developer (RAD) Version 6.0.1, which requires the following environment setup:

• Include the WebSphere Process Server V6.0 runtime.
1. In the portlet application, right-click Properties and highlight the Java Build Path.
2. In the Libraries tab, click the Add Library button, highlight the WPS Server Target, click Next and then click the Configure wps server classpath checkbox to finish the classpath inclusion.
   
   Alternatively, you can include the required jar files in your project environment.
• Include the Business Process Application jar File.
1. In the WebContent/WEB-INF/lib directory, add the CustomerService.jar contained in the CustomerServiceApp.ear (see the Downloads section).

Creating a business flow portlet

The Order Initiator Portlet included in the sample primarily uses the Business Flow Manager API to initiate and view the business processes. It’s a dedicated portlet for the Simple Order Process.

Initiate a process

Define the variables in the portlet scope:

public static final String PROCESS_NAME = "SimpleOrderProcess";
private static final String HOST_NAME = "localhost";
private static final String PORT = "2809";
private BusinessFlowManagerHome _bfmh = null;

Tip: The host name and port number must match the target process server. For example, the port number in the code must match the port 2809 specified as the bootstrap address in the process server.

To start a process, the Business Flow Manager EJB must first be accessed. This code is included in the init method of the sample portlet (see Listing 1).

public void init(PortletConfig config) throws PortletException {

        ……

	Hashtable env = new Hashtable();
	Context ctx = null;
	Object obj = null;

	// Define the URL string
	String strUrl = "iiop://" + HOST_NAME + ":" + PORT;
	env.put(Context.PROVIDER_URL, strUrl);

	// Look up the context
	try {
		ctx = new InitialContext(env);
		obj = ctx.lookup("com/ibm/bpe/api/BusinessFlowManagerHome");
	} catch (NamingException e) {
		e.printStackTrace();
	}

	// Access BFM home
	try {
	         _bfmh = (BusinessFlowManagerHome) 
	               PortableRemoteObject.narrow(obj,
	               com.ibm.bpe.api.BusinessFlowManagerHome.class);
	} catch (Exception e) {
		e.printStackTrace();
	}
}

The process will be initiated (Listing 2) from the processAction method of the portlet.

public void processAction(ActionRequest request, ActionResponse response) throws 
    PortletException, java.io.IOException {

	……			
	// Action on the Start Instance button
	if (request.getParameter(FORM_START) != null) {

		// Get the GUI Input Message
		Hashtable input = getFormParameters(request);

		// Initiate process
		String strPIID = initiateProcess(input);
		……
	}
	……
}

Listing 3 is the initiateProcess function. The code assumes that the process has a single initiating receive activity at the beginning, which is the case for a large amount of processes.

private String initiateProcess(Hashtable input) {

	String strPIID = null;
	BusinessFlowManager bfm = null;
	String strInputTypeName = null;
	String strProcessID = null;
		
	// Create the process in the local scope
	try {
		bfm = _bfmh.create();
	} catch (CreateException e) {
		e.printStackTrace();
	} catch (RemoteException e) {
		e.printStackTrace();
	}

	try {
		// Get process template
		ProcessTemplateData templateData = bfm
			.getProcessTemplate(PROCESS_NAME);

		// Get input message type name
		strInputTypeName = templateData.getInputMessageTypeName();

		// Print process ID
		strProcessID = templateData.getID().toString();

		// Create message
		ClientObjectWrapper cow = bfm.createMessage(
			templateData.getID(), strInputTypeName);

		// Set input message
		if (cow.getObject() != null
			&& (cow.getObject() instanceof DataObject)) {
			DataObject bdo = (DataObject) cow.getObject();
			setInputDataObject(bdo, input);
		} 

		// Initiate process
		PIID objPIID = 
		            bfm.initiate(templateData.getName(), 
		            PROCESS_NAME + "-" + 
		            System.currentTimeMillis(), cow);

		// Set return value
		strPIID = objPIID.toString();
	} catch (Exception e) {
		e.printStackTrace();
	}
	return strPIID;
}

Other implementations

Included in the sample portlet is also a function that gets currently running processes. For other business process manipulation functions, please refer to the Business Flow Manager API at:
http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.wsps.javadoc.doc/doc/com/ibm/bpe/api/package-summary.html

Creating a human task portlet

Now let us see how to execute a task using the Human Task Manager API. In a human interaction process portlet, the common use is to claim and complete a task, so the sample Customer Service Portlet incorporates this action.

Claim and complete a task

Define variables in the portlet scope:

private static final String HOST_NAME = "localhost"; 			
private static final String PORT = "2809"; 					
private static final String TASK_NAME = "CustomerService"; 		
private static final String NAME_SPACE = "http://CustomerService/com/ibm/sample"; 
private HumanTaskManagerHome _htmh =  null;

Tip: The task name and namespace come from the Customer Service task in the Simple Order Process.

Listing 4 shows how the Human Task Manager EJB Home is accessed.

public void init(PortletConfig config) throws PortletException {
		
	……

	Hashtable env = new Hashtable();
	Context ctx = null;
		
	// Define the URL string
	String strUrl = "iiop://" + HOST_NAME + ":" + PORT;
	env.put(Context.PROVIDER_URL, strUrl);
		
	// Look up the context and access HTM Home
	try {
		ctx = new InitialContext(env);
		_htmh = (HumanTaskManagerHome) ctx
			.lookup("com/ibm/task/api/HumanTaskManagerHome");
	} catch (Exception e) {
		e.printStackTrace();
	}
}

The task will be claimed and completed from the processAction method (Listing 5) of the portlet when either the Approve or Reject button is clicked. Listing 6 shows the claimAndComplete function for a task that is in the ready state.

public void processAction(ActionRequest request, ActionResponse response)
throws PortletException, java.io.IOException {

	String strTaskOption = null;
	Hashtable input =  null;
	Hashtable output =  null;
	
	......	
	// Action on the Approve or Reject button
	if (request.getParameter(DETAIL_APPROVE) != null
		|| request.getParameter(DETAIL_REJECT) != null) {
			
		boolean blnApproval = false;

		if (request.getParameter(DETAIL_APPROVE) != null) {
			blnApproval = true;
		}
			
		// Get Output Message object values
		output = new Hashtable(); 
		output.put("ApprovedAmount",   
                             request.getParameter(FORM_AMOUNT));
		output.put("Approval", String.valueOf(blnApproval));

		String strTaskID = request.getParameter(TASK_ID).toString();
			
		// Claim and complete the task
		claimAndComplete(strTaskID, output);
	}
}

private void claimAndComplete(String strTaskID, Hashtable output) {

	HumanTaskManager htm = null;
		
	try {	
		// Create human task manager
		htm = _htmh.create();
			
		// Claim the task
		htm.claim(strTaskID);
			
		// Get the output message object
		ClientObjectWrapper cow = 
                             htm.createOutputMessage(strTaskID);

		DataObject dbo = (DataObject) cow.getObject();

		// Set the output data object
		setOutputDataObject(dbo, output);

		// Set the output message
		htm.setOutputMessage(strTaskID, cow);

		// Complete the task
		htm.complete(strTaskID);

	} catch (Exception e) {
		e.printStackTrace();
	}
}

If you want to pass some of the input message to the output message when claiming a task, you can get the input message and do the mapping as shown in the Listing 7.

......
	try
	{
		// Get the input message wrapper
		// strTaskID as input Task ID
	    	ClientObjectWrapper cow = htm.getInputMessage(strTaskID);

   		 // Get the top level input data object
    		DataObject bdo = (DataObject) cow.getObject();
    
    		if(bdo != null)
   		 {
        			// Map the output with input 
        			mapOutputToInput(bdo, output);

    		} // if   
        
	} catch (Exception e) {
		e.printStackTrace();
	}

Other implementations

In addition to the methods to claim (or un-claim) tasks and to complete (or fail) tasks, as shown in the preceding code example, the sample human task portlet functions to get task list and task detail (code is not listed but output display is shown in the following section).

In general, the Human Task Manager API allows performing a rich set of functionality, based on the BPC Programming Model to:

• Create and start tasks, and to perform ad-hoc queries for tasks and other related objects.
• Get the input message, output message, and fault messages of a task, and to set the output or fault messages.
• Retrieve a task’s custom properties, and to get information about who acts in a certain role on a particular task.
• Suspend, resume, restart, terminate, and delete tasks (for administration purposes), and to dynamically change the assignment of tasks to people.

Here is the Human Task Manager API document link:
http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.wsps.javadoc.doc/doc/com/ibm/task/api/package-summary.html

Deploying the portlets

Use these steps to deploy and test the portlets.

1. Install the sample business process
2. Install the portlet application
3. Create a testing portal page
4. Add the portlets for testing

Install the sample business process

1. Go to the WebSphere Process Server admin console. Choose Applications => Enterprise Applications, and click Install.
2. Browse the CustomerServiceApp.ear file, and click Next.
3. Click the Generate Default Bindings checkbox, and finish the install using all default settings.
4. Save your changes to the Master Configuration.
5. Make sure to start the Application CustomerServiceApp as shown in Figure 3:

Install the portlet application

1. Go to WebSphere Portal and choose Administration => Portlet Management => Web Modules, and click Install.
2. Browse to the SampleProcessAPIPortletApp.war file, and finish the install.

Create a testing portal page

1. Choose Portal User Interface => Manage Pages.
2. Click the My Portal link, and then click New page to create a testing page.
3. Specify a title name: Simple Order Process, and then click OK to finish the page creation.

Add the portlets for testing

Install the portlets onto the testing page:

1. Go to My Portal, and click the Simple Order Process page tab.
2. Click the Edit Page link.
3. Add the Order Initiator Portlet and Customer Service Portlet onto the page.

Order Initiator Portlet

The Order Initiator Portlet using Business Flow Manager API primarily functions to start a process instance, as shown in the example entry in Figure 4. Once the process starts, the human task associated with the process will become available in the Customer Service Portlet. Optionally, you can view the currently running instances.

Customer Service Portlet

The Customer Service Portlet using the Human Task Manager API primarily functions to claim and complete a task, which is the most common action to execute in a business process portal application. The list view of the portlet in Figure 5 shows the running Customer Service task instances that are in the ready state to be worked on.

The task list GUI in the Customer Service Portlet is customized for the Simple Order Process. In other words, it’s a dedicated portlet. However, a generic portlet can be created for multiple business processes with human tasks or a process with multiple task activities. In that case, the generic task attributes (task description, task state, and so forth) can be displayed instead. Figure 6 shows the detail view of the portlet that provides actions to approve or reject an activity.

Back to top

Security role enablement

The sample portlets run in the portal server without security enablement. However, in that case, the role-based staffing functionalities do not really take effect. Viewed from the BPC explorer, the originator or task owner will be UNAUTHENTICATED.

To activate the role-based human task actions, one of the security options (LDAP, Local OS, or Custom) needs to be enabled. This section briefly lists the basic steps that are necessary for role-based staffing to function properly, using the commonly used LDAP security enablement.

1. From the portal server, use either the wizard or wpsconfig enable-security-ldap, to enable portal security.
2. From the process server admin console:
1. Map all J2C authentication aliases to existing users in the LDAP registry. For example, use the User ID wpsbind for the SCA_Auth_Alias.
2. Make sure the staff plug-in are configured correctly in the process server, with a matching JNDI specified in the JNDI name of staff plugiin configuration of the human task(s). For example, the bpe/staff/userregistryconfiguration specified in the Human Task CustomerService.tel file in our sample application.
3. Optionally, you can assign users the BPESystemAdministrator role with the Business Process Container. For example, when the role is NOT assigned, the portal user will only see the running instances that he or she originated.
3. From the WebSphere Integration Developer, specify the desired Verb in the Staff settings of each human task. For example, use "Group Search" in the field, Verb, that assigns members of groups that match listed attributes, as shown in the Figure 7 where the SalesReps group is specified as a potential owner for the human task: CustomerService. In our scenario, the human task’s primary role is a potential owner; however, other roles can be specified accordingly.
   
   Figure 7. Potential Owner Specification
   
   
   
4. Add the user or group (if not existed) specified in the Staffing settings, either from portal or LDAP server.
5. From the portal, assign proper security settings for the portal page(s) and portlets associated with a particular user or group.

Once the security is configured and the role is properly assigned, the task will be associated with its owner. Now, you can allow only a potential user to view, or claim and complete an assigned task from the Customer Service portlet. In that case, the portlet prints out the potential owner id in the system log, as shown in Figure 8:

Back to top

Process API alternatives

Though the process portlet using APIs has the greatest flexibility and the least amount of overhead, there are other alternatives to execute business process and human task from a portlet, for example, the known Process Portal using dynamic UI (see Integrating business processes in the WebSphere Portal InfoCenter), and the Pageflow using User Interface generator for Business Process Execution Language (BPEL) processes with Eclipse wizard. If you opt for a JSF-based process portlet application, you can use or customize BPC JSF components/modules. You can also integrate business process web client using BPC Explorer APIs for a quick portal solution. Finally, the Rational Application Developer and WebSphere Integration Developer tools provide the Helper modules to facilitate portlet integration with business processes.

Back to top

A simple comparison

As WebSphere Portal V5 comes with process portal capability, you may want to use the Task List portlet out of the box. The Task List is, however, not available by default, even with the Version 5.1.0.3, you need to install and configure it properly prior to its use. The process portal generates dynamic task pages based on the page definition specified in the human task client settings.

As a comparison, the following lists the features of the commonly used portalized process integration approach: the Process Portal (dynamic UI), along with the BPC API Portlets (dedicated) this article focuses on.

Process Portal (Dynamic UI)

• It is more applicable to multi-tasking handling, with its dynamic UI framework.
• Its Task List portlet comes with the portal, generic in nature.
• Its mediating framework is well tested and less error prone.
• It allows a customized look and feel for the task detail page.

BPC API Portlets (Dedicated)

• It is fully customizable (task list and detail GUI, and process/task handling) and the most flexible solution.
• It is efficient when used properly.
• It is less dependent on the portal environment or human task client setting.
• It allows the associated portal page/portlet(s) state to be persistent.

Back to top

Conclusion

This article has shown you a complete portlet application that connects to a business process with a human task. The sample portlets contain commonly used function calls using both Business Flow Manager API and Human Task Manager API. This article has also shown you configuration walk-through including environment setup and security enablement for process integration. As stated earlier, the process portlet using APIs offers the greatest flexibility and customization, with easier setup and less overhead. Now, you can easily tailor and expand the sample portlet application, base on your requirements, to build an SOA solution with fully customized process portal integration.

Back to top

Acknowledgements

The author wishes to thank Frank Neumann, Development Architect, Business Process Choreographer, for his invaluable comments.

Back to top

Downloads

	Information about download methods

Resources

• WebSphere Portal Information Center: Integrating business processes
  
  
• WebSphere Application Server Enterprise Process Choreographer: Work items and the query() API call
  
  
• Connecting to a business process engine using a portlet
  
  
• WebSphere Process Server: IBM's new foundation for SOA
  
  
• Architecting on demand solutions, Part 18: Use IBM WebSphere Integration Developer to assemble components
  
  
• Developing a custom Web client for Business Process Choreographer with WebSphere Studio Integration Edition
  
  
• WebSphere Business Integration zone
  
  
• New to WebSphere Business Integration
  
  
• WebSphere Education
  
  
• WebSphere Technical Podcast series
  
  
• developerWorks WebSphere Process Server and WebSphere Integration Developer resource page
  
  
• developerWorks technical events and webcasts
  
  

• Participate in the discussion forum.
  
  
• Participate in developerWorks blogs and get involved in the developerWorks community.

About the author

		Sean Gu is an Enterprise Application Architect at IBM Business Partner Technical Enablement. His areas of expertise include ERP (PeopleSoft, Siebel, and Lawson), WebSphere Portal, OO Technologies, Business Process Integration and SOA Composite Applications.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top