Introduction

Companies need to model and manage their business processes to integrate systems and people throughout the enterprise, as well as connect with customers and partners. The IBM® WebSphere® product family delivers those key capabilities to help companies respond with speed to any customer demand, market opportunity, or external threat.

As the foundation of the WebSphere software platform, WebSphere Application Server provides a rich e-business application deployment environment and offers full J2EE™ 1.3 specification support. The WebSphere Application Server Enterprise Edition Process Choreographer can be used to design all kinds of business processes. The types of business processes can vary greatly, ranging from Web services navigation to business transaction support. Business processes are automatic and recoverable. The product can also have human interactions.

WebSphere Studio Application Developer Integration Edition provides an integrated development environment for building, testing, integrating, and deploying J2EE applications, business processes, and Web services. With this tool, developers can model business processes from the Process Editor and test the implementations in the WebSphere Test Environment.

WebSphere Portal Server allows users to interact in a personalized way with the on demand world. It acts as a simple, unified access point to Web applications, permits personalization of Web-based content, and makes it accessible to any device.

After a business process is deployed, you can use the built-in Business Process Web Client to create a business process instance and manage your personal worklist items. However, the Business Process Web Client is merely a test client. If you want to add new functionality to the Web client or to adapt it to your company's look and feel, you can use the Business Process Engine (BPE) API.

In this article, we will demonstrate how you can easily build, deploy, unit-test, and manage a product description approval process, and build a Web application that acts as a business process Web client that could further be integrated with your company portal.

This article is organized as follows: Section 2 describes a business scenario that requires a business process with Human Task component. Section 3 walks through building the business process with WebSphere Studio Integration Edition, and unit testing the business process from the built-in Business Process Web Client. Section 4 provides an overview of the API of the Business Process Engine that can be used to write a custom Business Process Web Client. Section 5 gives a sample implementation. Section 6 concludes the article.

This article uses WebSphere Studio Application Developer Integration Edition (hereafter called WebSphere Studio) Version 5.1.1 as the authoring tool of the business processes and custom Web client. This article assumes you have the basic knowledge on how to create a BPEL business process in WebSphere Studio. You can refer to this article for more information on how to create a BPEL business process.

Back to top

Business scenario

Global data synchronization is one of the many challenges for an enterprise, especially when the enterprise has many Enterprise Information Systems (EIS) serving different business functions, such as manufacturing and sales. For example, if a new product has been produced by the manufacturing department, it is critical to have the product information available to the sales department in order to quickly introduce the product. A typical scenario is as follows:

Manufacturing created a new product description in its own EIS. Once this description has been entered into the EIS, a business process is initiated notifying management to validate and approve the product information. Once approved, the product description is sent to the sales department's EIS.

The business process can be created in WebSphere Studio v5.1.1. The business process can be easily integrated with the Manufacturing EIS and the Sales EIS. The simplified version of the business process is illustrated as in Figure 1. We will discuss and run DescriptionApprovel business process in the next section.

Back to top

Develop, deploy and unit test the business process

The BPEL business process in this scenario is long running because it contains a Staff activity. The DescriptionApproval process implements the following activities:

1. Receive a product description.
2. Display the product description, i.e. for monitoring purposes.
3. The manager approves the product description.
4. Display the updated product description.

The Web Service Description Language (WSDL) file for the business process is shown below. It has an input message which is of type DescriptionApprovalRequest. The port type is called DescriptionApprovalPT and the operation is approve.

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="DescriptionApprovalClient"
    targetNamespace="http://exchange.ibm.com/DescriptionApprovalClient"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://exchange.ibm.com/DescriptionApprovalClient"       
		xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <message name="DescriptionApprovalRequest">
    	<part name="id" type="xsd:string"></part>
    	<part name="description" type="xsd:string"></part>
    </message>
    <portType name="DescriptionApprovalPT">
    	<operation name="approve">
      	    <input message="tns:DescriptionApprovalRequest"></input>
    	</operation>
    </portType>
</definitions>

The WSDL file of the staff activity (ManagerApproval) is shown below. The WSDL file defines the port type, operations, input and output messages for the ManagerApproval staff activity.

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="ManagerApproval"
    targetNamespace="http://exchange.ibm.com/ManagerApproval"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://exchange.ibm.com/ManagerApproval"     
		xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <message name="ManagerApprovalRequest">
    	<part name="id" type="xsd:string"></part>
    	<part name="description" type="xsd:string"></part>
    </message>
    <message name="ManagerApprovalResponse">
    	<part name="result" type="xsd:string"></part>
    	<part name="description" type="xsd:string"></part>
    </message>
    <portType name="ManagerApprovalPT">
    	<operation name="approve">
    		<input message="tns:ManagerApprovalRequest"></input>
    		<output message="tns:ManagerApprovalResponse"></output>
    	</operation>
    </portType>
</definitions>

Roles are being defined in the properties page of the staff activity. For simple demo purpose, the Potential Owner of this activity is Everybody as shown in Figure 3. In a real case, the owner should be some specific groups or users.

Import the sample BPEL application

1. Download the sample file here.
2. Unzip the PrivateExchange.zip into your workspace.
3. From the workbench, create a Service Project named PrivateExchange. This will pick up the existing files from the folder in the workspace.

The next step is to deploy the business process. Right-click on DescriptionApproval.bpel => Enterprise Services => Generate Deploy Code. Because we are going to instantiate the business process with the BPE API, we don’t need any interface binding other than JMS binding as shown in Figure 4. This step will create an EAR, EJB and Web projects.

After we deploy the process, we can create a server instance and configuration and add the deployed projects into the server configuration. This process is a long running flow, we need to right click on the server to create tables and data sources. After the server is started, launch the business process Web client.

The Web client provides three major business functions -- starting a business process instance, worklist items, and administration. End users other than the administrators will probably only interested in the first two functions.

Running a description approval business process

1. Select Process Template List => My Templates from the navigation tree.
2. Select the DescriptionApproval template, and then Start Instance.
3. Fill in the input message e.g. ThinkPad T21 as the description and TP-T21 as the id. You can leave the Process Instance Name empty because one will be generated by the server.
4. Click the Start Instance button to create a new instance of the BPEL process.

The browser will switch to the My To Dos page automatically after the business process instance is started.

Look at the Console view, and you will find the system output from the DisplayProductDescription Java snippet.

========= Approval Required ==========
id:TP-T21
description:ThinkPad T21
======================================

Claim and complete the ManagerApproval work item

After the business process is started, you should see a new work item in the My To Dos page. If you haven’t seen the work item yet, click My To Dos on the navigation bar again to refresh the page.

Select the ManagerApproval activity, and press the Claim button from the Available Actions list. The state of the ManagerAppoval work item changes to Claimed.

Select the ManagerApproval activity again, and select Complete from the available Action list. The activity input and output messages are displayed as shown in Figure 7. These messages are from the ManagerApproval.wsdl. If the manager disapproves the product description, he/she can update the description in the description field.

Select Complete from the Available Actions list to complete the work item.

You should see the following output in the console. The manager could modify or keep the product description.

========= Manager Approval ==========
Result:Approve
Updated Description: ThinkPad T21
======================================

In the next section, we will create a custom Web client that could create a new instance for this BPEL process and as well to provide an custom interface to manage the work items.

Back to top

Create custom Web client for business processes

The business requirements of a custom Web client for this business scenario include:

1. Start a process
2. Retrieve personal work list
3. Display the input of a work item
4. Claim a work item
5. Complete a work item

In this section we will look at the Business Process API and discuss the steps to create the Web client.

BusinessProcessService API

The BusinessProcessService API is a set of methods available through a SessionBean facade of the Process Choreographer component, which allow you to interact with the Process Choreographer component programmatically such as starting a process, retrieving a work list, claiming/completing a work item. The built-in Business Process Web Client is implemented with this API. In this article, you will use this API to create your own custom Web client.

Registering the session bean as a reference

The Web client is implemented using Servlet and JSP, which need to invoke the corresponding BPE APIs. The BusinessProcessService session bean provided by the BPE APIs is used to access and manipulate BPEL processes. It must be made available to the application by registering the Enterprise JavaBeans (EJB) reference in the Web Deployment Descriptor (web.xml).

You can create the Web client by following the article or downloading a code.

Import the code for the custom Web client

1. Download the sample file here.
2. From the workbench, File => Import => WAR file. Press Next. Select PrivateExchangeWeb.war as the file name and select PrivateExchangeWeb as the Project name. Press Finish. Press Yes when asked to overwrite existing files.

In order to use the BusinessProcessService session bean, two jar files are imported into the lib folder of the PrivateExchangeWeb project - bpeapi.jar and bpe137650.jar. You can find these two jars from \runtimes\ee_v5_stub\lib.

Next, open the Web Deployment Descriptor of the Web application. In this case, that's the web.xml of the PrivateExchangeWeb project. Go to the Reference tab and add a new entry to the EJB References with the information shown in Figure 8.

The following code snippet of StartProcessServlet in the sample demonstrates how to start a business process instance.

String template = "DescriptionApproval";
String id = req.getParameter("id");
String description = req.getParameter("description");
BusinessProcessHome processHome;
BusinessProcess process;
String instance = template + (new java.util.Date()).toString();

javax.naming.InitialContext context = new javax.naming.InitialContext();

// Lookup the home interface of the BusinessProcess bean
Object result = context.lookup("java:comp/env/ejb/BusinessProcess");
// Convert the lookup result to the proper type
processHome = (BusinessProcessHome) javax.rmi.PortableRemoteObject.narrow(
			result,
			BusinessProcessHome.class);

process = processHome.create();
// construct the input message for the process.
ProcessTemplateData processTemplate = process.getProcessTemplate(template);
ClientObjectWrapper inputMsg = process.createMessage(
	processTemplate.getID(),
	processTemplate.getInputMessageTypeName());

WSIFDefaultMessage input = (WSIFDefaultMessage) inputMsg.getObject();
input.setObjectPart("id", id);
input.setObjectPart("description", description);

process.initiate(template, instance, inputMsg);

Thread.sleep(2000);
getServletContext().getRequestDispatcher("RetrieveWorkListServlet").forward(req,resp);

The following code snippet of RetrieveWorkListServlet in our sample demonstrates how to retrieve a personal work list.

Vector worklist = new Vector();
BusinessProcessHome processHome;
BusinessProcess process;

String wlname = "MyActivities";

javax.naming.InitialContext context = new javax.naming.InitialContext();

//	Lookup the home interface of the BusinessProcess bean
Object obj = context.lookup("java:comp/env/ejb/BusinessProcess");
//	Convert the lookup result to the proper type
processHome = (BusinessProcessHome) javax.rmi.PortableRemoteObject.narrow(
		obj, BusinessProcessHome.class);

process = processHome.create();

String s =
"DISTINCT ACTIVITY.AIID, ACTIVITY.TEMPLATE_NAME, ACTIVITY.STATE, 
ACTIVITY.OWNER, WORK_ITEM.REASON, ACTIVITY.ACTIVATED, PROCESS_INSTANCE.NAME, 
PROCESS_INSTANCE.TEMPLATE_NAME, PROCESS_INSTANCE.PIID";
String s1 =
"ACTIVITY.STATE IN (2, 8) AND WORK_ITEM.REASON IN (1, 4, 2, 3) AND 
PROCESS_INSTANCE.STATE = 2";

QueryResultSet result = process.query(s, s1, null, null, null);

//	store the results
if (result.size() != 0) {
	result.first();
	for (int counter = 0; counter < result.size(); counter++) {
		WorkListResult entry = new WorkListResult();
		entry.setAiid(result.getOID(1).toString());
		entry.setTemplateName(result.getString(2));
		entry.setState(result.getInteger(3).toString());
		entry.setInstanceName(result.getString(8));

		worklist.add(entry);

		System.out.println(entry);
		result.next();
	}
}

req.getSession().setAttribute("worklist", worklist);
getServletContext().getRequestDispatcher("MyWorkList.jsp").forward(req,resp);

The following code snippet of GetWorkItemServlet in the sample demonstrates how to display the input message of a work item.

BusinessProcessHome processHome;
BusinessProcess process;

javax.naming.InitialContext context = new javax.naming.InitialContext();

//Lookup the home interface of the BusinessProcess bean
Object obj = context.lookup("java:comp/env/ejb/BusinessProcess");
//Convert the lookup result to the proper type
processHome =	(BusinessProcessHome) javax.rmi.PortableRemoteObject.narrow(
		obj,
		BusinessProcessHome.class);

process = processHome.create();
String aiid = req.getParameter("aiid");
ClientObjectWrapper input = process.getInputMessage(aiid);
WSIFDefaultMessage inputMsg =(WSIFDefaultMessage) input.getObject();
req.setAttribute("id",(String) inputMsg.getObjectPart("id"));
req.setAttribute("description", (String) inputMsg.getObjectPart("description"));
getServletContext().getRequestDispatcher("ShowWorkItem.jsp").forward(req,resp);

The following code snippet of ExecuteActivityServlet in our sample demonstrates how to claim and complete a work item.

BusinessProcessHome processHome;
BusinessProcess process;

javax.naming.InitialContext context = new javax.naming.InitialContext();

//Lookup the home interface of the BusinessProcess bean
Object obj = context.lookup("java:comp/env/ejb/BusinessProcess");

//Convert the lookup result to the proper type
processHome =(BusinessProcessHome) javax.rmi.PortableRemoteObject.narrow(
		obj, BusinessProcessHome.class);

process = processHome.create();
String aiid = req.getParameter("aiid");
process.claim(aiid);

WSIFDefaultMessage outputMsg = (WSIFDefaultMessage)process.createMessage(
	process.getActivityInstance(aiid).getProcessTemplateID(),
	process.getActivityInstance(aiid).getOutputMessageTypeName()).getObject();

outputMsg.setObjectPart("result", req.getParameter("result"));
outputMsg.setObjectPart("description", req.getParameter("updatedDesc"));

process.setOutputMessage(aiid, new ClientObjectWrapper(outputMsg));
process.complete (aiid);
getServletContext().getRequestDispatcher("RetrieveWorkListServlet").forward(req,resp);

Security Consideration

The Web client needs to execute under a certain security principle in order to retrieve the personal work list and complete the work item. As a result, authentication and authorization is required for the Web project. Follow these steps to change the security roles.

1. Open the Web Deployment Descriptor.
2. Select Security tag at the bottom of the editor. You will see the Security Roles tag on the top of the editor first. Create a security role named BPEUser.
3. Click on the Security Constraints tag at the top of the editor. Create a Web Resource Collection named everything with URL Patterns /*. This means all the Servlet and JSPs in the Web project will be secured.
4. After the Web Resource Collection is created, select BPEUser as the authorized role.
5. Save the Web Deployment Descriptor.
6. Open the Application Deployment Descriptor. In this case, that is application.xml in the PrivateExchangeEAR project.
7. Select the Security tag at the bottom of the editor.
8. Click the Gather... button to collect all the security roles defined in all the Web and EJB modules. In this case, the BPEUser will appear on the list.
9. Select BPEUser from the list, and select All authenticated users as the bindings.
10. Save the Application Deployment Descriptor.

Running the sample application

1. Stop the server if it's running.
2. Open the Server Configuration in an editor. Select the Security tag, and enable security for the server.
3. Enter your user id in the Server ID field and enter your password in the Server password field. If you are running the server in localhost on a Windows machine, you can use the Windows login id and password.

1. Start the server.
2. Right-click on the main.html under PrivateExchagneWeb project, and select Run on Server.
3. Type in your username and password and you will be presented with the main page of the application.

Enter the input message as we did in the built-in Business Process Web Client, e.g. TP-T21 as the Id, and Thinkpad T21 as the Description, and click Submit.

Look at the server console, and you will find a message like this:

========= Approval Required ==========
id:TP-T21
description:ThinkPad T21
======================================

The My To Dos page will display after you start the business process instance. This page shows the work item that is created by the DescriptionApproval business process.

Select the link ManagerApproval, and you will see the input message of this activity which is the id and the description. In addition, the updated description is also populated with the original description. You can update the description in the Update Description textbox. Enter some output messages, and select Submit.

From the console, you will see a message similar to this:

========= Manager Approval ==========
Result:Approved
Updated Description: ThinkPad T21 (SALE)
======================================

Back to top

Conclusion

WebSphere Studio Application Developer Integration Edition has a built-in Business Process Web Client for users to manage the business processes and complete work items. In some cases, a custom Web Client is needed, e.g. adding themes, narrowing the Web Client to a particular business process or creating portlet and deploying it to the company portal. Developers can always use the BusinessProcessService API to develop their own applications similar to the sample application coming with this article.

Back to top

Download

Name	Size	Download method
PrivateExchange.zip	12 KB	FTP|HTTP

Information about download methods

Resources

• Business Process Service
  
  
• To learn more about WebSphere Application Server, visit the developerWorks WebSphere Application Server zone. You'll find technical documentation, how-to articles, education, downloads, product information, technical support resources, and more.
  
  
• Get involved in the developerWorks community, participate in developerWorks blogs.
  
  
• Browse for books on these and other technical topics.
  
  

About the authors

Jane Fung is a software engineer at IBM Toronto Lab. She works on the Debug toolings in WebSphere Studio Application Developer Integration Edition. Her expertise includes BPEL and business rules. She is Java 2 certified and has an Electrical Engineering degree from the University of Waterloo. You can reach Jane at jcyfung@ca.ibm.com.

Colin Yu is a technical designer at IBM Toronto Lab. He helps define integration requirements for IBM Software Group products through the use of Business Scenarios. He received a Bachelor of Engineering degree in 1995 and a Master of Applied Science degree from the University of Waterloo, Ontario in 2000. Colin is an IBM Certified Enterprise Developer and System Expert on WebSphere Application Server. You can reach Colin at coliny@ca.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Business scenario
• Develop, deploy and unit test the business process
• Create custom Web client for business processes
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers