Introduction

IBM® WebSphere® Portal V5.1 introduced the integration of business process capabilities into a portal deployment. This support provides enterprises with new options for using WebSphere Business Integration Server Foundation (WBISF) Process Choreography components with WebSphere Portal (WP) process management interfaces.

For example, Process Choreographer provides a default Web client that you can use to interact with tasks created for a interruptible or non-interruptible business process. A user can list process templates, enter input data, instantiate a process, and work with user work items created as Staff and Receive activities. While this client interface is good for testing during the development of business activities, it is not the kind of interface you want to provide to your end users.

You need to develop your own custom user interface for your users, either in the form of a Web application or a portlet running in WebSphere Portal. Most likely you would use the open Java™ API provided by Process Choreographer, referred to in this article as the BPE API, to interact with the process engine.

This article describes how a to create a portlet to invoke a business process using the Business Process Engine (BPE) API. To get the most out of this article you need to know about Process Choreographer, Web Services, Business Process Engine and WebSphere Portal.

Back to top

Understanding the types of processes

Before we plunge into the actual details of writing a portlet, let’s first look at the two basic types of processes:

• Interruptible processes are long-running and are composed of business services. An example is the process for approving a loan application.
• Non-interruptible processes are short-lived operations, combined to form a single business operation; for example, validating credit card.

Interruptible process

A business process is interruptible if each step of the process runs in its own physical transaction. Interruptible processes are generally long-running processes. Business processes need to be interruptible if they wait for external stimuli, or if they involve human interaction. Examples of external stimuli are:

• Events sent by another business process in a business-to-business interaction
• Responses to asynchronous invocations
• Completion of a staff activity

An interruptible process has the following characteristics:

• Runs as several transactions
• Consists of synchronous and asynchronous services
• Is started by the initiate method, or the sendMessage method because the output message cannot be retrieved synchronously
• Normally runs a long time
• Stores run-time values persistently

Non-interruptible process

A non-interruptible business process runs in one process thread from start to finish without interruption. Non-interruptible business processes are also known as microflows. These processes can have different transactional capabilities. They can run within a distributed transaction, as part of an activity session, or with a local transaction.

A non-interruptible business process has the following characteristics:

• Runs as one transaction.
• Consists of only synchronous services and non-interruptible subprocesses. This means that a non-interruptible process cannot contain:
  • Staff or wait activities
  • An asynchronous invoke
  • Multiple receive activities
  • Interruptible sub-processes
• Is started using the call method so that an output message is returned when the process completes.
• Normally runs for a short time.
• Does not store run-time values in the database.
• Contains no interruptible processes.

Back to top

Introducing the scenario

The scenario in this article involves creating a simple portlet which calls a process to return the value of a stock. The process defined for the stock quote is a simple non-interruptible process. You see the steps needed to invoke that process using a portlet.

Sample code

The code to support this scenario is provided in a download.

Software requirements

To play through the scenario, you need to have one of these environments:

• IBM WebSphere Portal V5.0.2.2 under IBM WebSphere Business Integration Server Foundation 5.1.x (hereafter called Server Foundation)
• IBM WebSphere Portal V5.1 under Server Foundation

You will also need IBM WebSphere Studio Application Developer Integration Edition 5.1.x (hereafter called Application Developer) with the WebSphere Portal Toolkit configured.

Back to top

Communication mechanisms from a portlet

There are options for the communications between a portlet and a process.

Using the BPE APIs

The BPE API provides the following renderings for developing applications for processes based on Business Process Execution Language (BPEL):

• An Enterprise JavaBean (EJB) rendering that enables the API to be called locally or remotely. A stateless session bean for each type of call (LocalBusinessProcess interface and BusinessProcess interface) exposes the functions that an application program can call. The BusinessProcessService interface provides a common interface for these session beans.
• A Java Message Service (JMS) rendering that enables a subset of the API functions to be called remotely using JMS.

Using the Web service client

Alternatively you could expose the process as a Web service. Then, you can generate Java proxies for the Web service and instantiate a process using the proxy.

In this article we will discuss the process invocation using the BPE APIs, using the EJB.

Back to top

Getting ready for process portlet development

In order to develop a process portlet, you need to create a project in Application Developer and make the required libraries available.

Creating a portlet project

First, to create a portlet project:

1. In Application Developer, select File => New => Portlet Application Project.

   Tip: If you don’t see Portlet Application Project under New, click Other and select Portlet Development => Portlet Application Project.

2. Name the project ProcessStarter, and select Basic Portlet, as shown in Figure 1.
   Figure 1. Creating a portlet project
   
   
3. Click Next.
4. Click and accept the defaults on the screens following the initial screen until you reach the Event Handling screen.
5. De-select the Add Action Listener, and then click Finish.
   Figure 2. Finishing the creation of the portlet project
   
   

   You see a new skeleton portlet project created in Application Developer.

Getting access to the required libraries

Now that you have a portlet project created, you need to make the library JAR files required to invoke the business process API available to Application Developer. You do this by copying the following jars from Server Foundation, where the process engine is running, into the WEB-INF\lib folder of the portlet, as shown in Figure 3 below, where <WAS_51_ROOT> is the location where Server Foundation is installed.

• <WAS_51_ROOT>\ProcessChoreographer\client\bpe137650.jar
• <WAS_51_ROOT>\ProcessChoreographer\client\bpeapi.jar
• <WAS_51_ROOT>\ProcessChoreographer\client\processportal.jar
• <WAS_51_ROOT>\lib\wsif.jar

To copy the libraries:

1. Open Windows Explorer, and select these jar files.
2. Right-click and select Copy (or press CTRL-C).
3. In Application Developer, expand and select the WEB-INF\lib of the Portlet Project folder.
4. Right-click and select Paste.

You will also need to add the following JAR files to the Java Build Path of the portlet project.

• WAS_50_PLUGINDIR/lib/qname.jar
• WAS_50_PLUGINDIR/lib/wsdl4j.jar

To add the JAR files, in Application Developer:

1. Select the portlet project in the Navigator view.
2. Right-click and select Properties.
3. Select Java Build Path.
4. On the Libraries tab, click Add Variable.
5. Add wsdl4j.jar and qname.jar.
6. Click OK and exit out of the Properties window.

You have now completed the procedure for setting up the portlet project so that you can develop process portal portlets.

Back to top

Developing the portlet

Unzip the download file and extract its contents into a directory of your choosing.

Copy the contents of the ProcessStarterPortlet.java file that you extracted from the zip file and paste into the ProccessStarterPortlet in the Application Developer editor.

Examining the provided code

Next, look at some of the key parts of the code to gain an understanding of how the portlet uses the BPE API.

Getting to the business process engine EJB

The portlet can communicate with the process engine using a stateless session bean that is running on the process server. To get access to this EJB, the codes does a JNDI lookup for com/ibm/bpe/api/BusinessProcessHome on the process machine to get the home object and to use it to create a business process EJB object. This code is in the init() method of the portlet. The code snippet in Listing 1 shows how to get access to the EJB.

java.util.Hashtable env = new java.util.Hashtable();
String corbaloc = "corbaloc:iiop:localhost:2809";

env.put(javax.naming.Context.INITIAL_CONTEXT_FACTORY, 
"com.ibm.websphere.naming.WsnInitialContextFactory");
env.put(javax.naming.Context.PROVIDER_URL, corbaloc);

javax.naming.Context choreographyContext = 
		new javax.naming.InitialContext (env);			

Object o = choreographyContext.lookup 
		("com/ibm/bpe/api/BusinessProcessHome");
           
com.ibm.bpe.api.BusinessProcessHome bph = 
		(com.ibm.bpe.api.BusinessProcessHome) 
javax.rmi.PortableRemoteObject.narrow 
		(o, com.ibm.bpe.api.BusinessProcessHome.class);
businessProcess = bph.create ();

Calling the process API’s

Now, let’s look at several of the key API’s.

A process template is a versioned, deployed, and installed process model that contains the specification of a business process. You can query the process template data using the ProcessTemplateData, which returns information such as whether the process is a long running process, the list of input messages it takes, and the list of output messages. The code snippet in Listing 2 shows how you can get access to the ProcessTemplateData object and query the type of input message it is expecting.

ProcessTemplateData templateData = 
BusinessProcess.getProcessTemplate(templateName);

String inputTypeName = 
	templateData.getInputMessageTypeName();

You use the ClientObjectWrapper to wrap messages and variables passed between the caller and the process engine.

When the process engine is accessed through its EJB interface:

• Invocation parameters are automatically deserialized by the application server.
• Messages and variables are deserialized.

The ClientObjectWrapper class defers deserialization until the wrapped message or variable is accessed so that the process engine can set the appropriate class loader.

If you have a message that includes a complex data type, you need to get the client jar file that contains the classes from the process and copy it into WEB-INF/lib of the portlet. The code included in the download demonstrates how to get the data type. The type you get are types defined in your XSD; they are not Java types. Therefore, you can’t call instanceof to check the data type.

The wrapper contains the WSIFMessage, which is a container for a set of named parts. Listing 3 shows how you can iterate to get the parts within a WSIFMessage.

ClientObjectWrapper replyWrapper = ...
WSIFMessage wsifMessage = (WSIFMessage) 
	replyWrapper.getObject();
Iterator partNames = wsifMessage.getPartNames();
while (partNames.hasNext()) {
     String partName = (String) partNames.next();
    Object partValue = wsifMessage.getObjectPart(partName);
}

Listing 4 shows how to get the underlying WSDL model for the message, such as when you get the list of inputs to present.

WSIFMessage inputMessage = … ;
Map inputParts = 
		inputMessage.getMessageDefinition().getParts();
Iterator partNames = inputParts.keySet().iterator();
while (partNames.hasNext()) {
		String partName = (String) partNames.next();
}

Create the input JSP

Now you are ready to create the JSP used for inputs.

Copy the contents of ProcessStarterPortletView.jsp code from the download zip file into the ProcessStarterPortletView.jsp in the jsp/html directory of your portlet project.

The ProcessStarterPortletView JSP accepts a stock symbol as input and sends it to the portlet for processing, as shown in Figure 6.

Create the output JSP

Next you add a JSP to display the results of the stock lookup.

1. Select the html folder.
2. Right-click and select New => JSP File.
3. Name it ProcessStarterOutput.jsp as shown in the Figure 4.
   Figure 4. Creating the output JSP
   
   
4. Copy the code for ProcessStarterOutput.jsp from the zip file and paste it into the JSP file you just created.

Display the PIID of the process

When the code instantiates an interruptible process, it gets a Process Instance Identifier (PIID), in response. To display the PIID, you need to create a JSP.

1. Follow the steps in the previous section to create another JSP file called ProcessStarterOutputWSIF.jsp.
2. Copy the contents of ProcessStarterOutputWSIF.jsp in the zip file and paste it into the JSP you just created.

Back to top

Testing the portlet

Included in the download is another EAR file, StockProcessSample.ear, which contains the application that runs the process.

To test the portlet:

1. Using the WebSphere Application Server, install the StockProcessSample.ear file just as you would install a standalone enterprise application into the WebSphere Portal application server.
2. Next, export the portlet project as a WAR file from Application Developer, by right-clicking the project and select export.
3. On the export screen select Export as a war file and give it a name.
4. Install the exported portlet using the WebSphere Portal’s admin portlets, and then add it to a page.
5. Navigate to the page which has the portlet. You should see the portlet similar to what you see in Figure 5.
   Figure 5. Testing the portlet
   
   
6. Enter a symbol (such as IBM) and click Submit. The results of the process display as shown in the Figure 6.
   Figure 6. Viewing the results of the process
   
   

Back to top

Configuring the process template

This portlet lets you configure the process template name. After you install the portlet you can use the Manage Portlets in WebSphere Portal to change the Portlet Setting to point to any template you want to use. This portlet supports templates that accept simple data types for input and return simple data types for the output message. For complex data types you need to modify the code a little bit.

Back to top

Viewing the BPE API Javadoc

You can find the Javadoc for the BPE API in you Server Foundation directory tree:

<WAS>\web\apidocs\index.html, package com.ibm.bpe.api

Back to top

Conclusion

In this article you saw how to create a portlet to interact with a business process. You used the business process Java API provided by Process Choreographer to access a session bean.

You looked at the list of inputs for a given process template and saw how to instantiate a business process using the APIs with the given inputs. For simplicity the example here supports simple data type. Now you can modify the portlet to support a complex data type.

Back to top

Download

Name	Size	Download method
0502_gadepalli-PortetProcessCode.zip	2467 KB	FTP|HTTP

Information about download methods

Resources

• WebSphere Portal product documentation
  
  
• WebSphere Application Server Enterprise Process Choreographer Programming Model
  
  
• WebSphere Portal zone
  
  
• This JavaDoc shows the different APIs available to work with the Business Process Engine.
  
  
• It is also installed with WBI-SF Install at the following location: <WAS>\web\apidocs\index.html, package com.ibm.bpe.api
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Browse for books on these and other technical topics.
  
  

About the authors

Varadarajan Ramamoorthy is a senior consultant for IBM Software Services for Lotus at the IBM Research Triangle Park Lab in Raleigh, North Carolina. He has over five years of experience working with WebSphere Portal. He has been working with customers in building solutions that involve WebSphere Portal.

Vishy Gadepalli is a member of the WebSphere Enablement Team based in Raleigh. He has more than seven years of experience in the IT field and has been involved in customer engagements involving WebSphere Portal Server for the last three years. He has authored numerous papers, which have been published both internally and externally inside IBM. He has also spoken at many conferences on topics involving WebSphere Portal Server and how it integrates with other backends. Vishy also co-authored the first edition of WebSphere Portal Primer.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Understanding the types of processes
• Introducing the scenario
• Communication mechanisms from a portlet
• Getting ready for process portlet development
• Developing the portlet
• Testing the portlet
• Configuring the process template
• Viewing the BPE API Javadoc
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers