Introduction

In IBM Business Process Manager (BPM), you define and implement the activities, such as steps, that must be carried out to complete a business process. This article discusses integrating activities with an external system using the REST API. With the release of Business Process Manager V7.5.1, you can now use all of the functionality that was provided by the unsupported REST API for WebSphere Lombardi Edition V7.2. For more information about the REST API for Lombardi Edition V7.2, see Common business process modeling situations in WebSphere Lombardi Edition V7.2, Part 2: Integrating a business process application with an external system using the REST API.

Assumptions

A deep and thorough understanding of IBM Business Process Manager V7.5.1 is not required to understand the topics discussed in this article. However, you should be familiar with the product's basic function and with general concepts of business process management. Also, knowledge of Java™, JEE, HTML, JavaScript, Dojo, WebSphere Application Server, Web application security, single sign-on, representational state transfer (REST) architecture, integrated development environments (such as Eclipse), and programming languages in general are assumed.

Back to top

Integrating a business process with an external user interface

It is common to integrate a business process with an external user interface. For instance, a team has invested significant time and effort developing a Web interface that uses Java Server Faces (JSF). After most of this user interface has been implemented, the team decides to use IBM BPM to implement the business workflow instead of hardcoding this logic using the Java programming language. Though the management team is completely on board with using IBM BPM to implement the business process, they prefer to keep the new JSF user interface instead of re-creating the interface pages using IBM BPM coaches. In such a case, the steps to collect data from users are implemented as external activities instead of implementing them as human services using coaches.

A basic sample business process with external activities is used throughout this article to show how integration with an external system is achieved. This business process is included in the Download section of this article so you can import it into IBM BPM. We will start by describing this sample business process and then discuss how to use a Java application to execute it. Figure 1 shows the implementation diagram for the business process, Process With External Steps, and Figure 2 shows the variables that are used in it.

Looking at Figure 1, you can see that the business process contains two steps that are implemented as external implementations: External Activity 1 and External Activity 2. Also, looking at Figure 2, you can see that this process has an input value named priority of the string data type, which is passed in as an argument to kick off the process.

Figure 3 shows the implementation for External Activity 1 is an External Activity 1 Impl of the User Task implementation type. By opening External Activity 1 Impl, you can see the inputs and outputs that have been specified for this step (see Figure 4). The inputs are the values that are passed from the process implemented in IBM BPM to the external system, and the outputs are the values to be sent from the external system to the process in IBM BPM.

For External Activity 1, you see one input parameter specified: priority. This is the string value that kicks off the process. The output for this same activity consists of one variable of the User data type. Figure 5 shows the definition of the User data type. You can see that this data type is made up of simple and primitive data types.

Inputs and outputs for an external implementation are mapped to variables defined at the process level as shown in Figure 6.

Figure 7 shows the implementation for External Activity 2. For this step, the inputs consist of a rating value and a quote value. These are values that the system computes (in System Step 1) based on the values collected during the execution of External Activity 1. The output is a Boolean value that specifies whether or not the user accepts the generated quote and rating values from the system.

Figure 8 shows the data mapping for the input and output variables of External Activity 2. As it was the case with External Activity 1, these variables are also mapped to variables defined at the business process level.

When a step, which is implemented as an external implementation, is reached during the execution of a business process, the execution stops and IBM BPM waits for an external system to complete the activity. To move the business process forward, an external system programmatically connects to IBM BPM and completes the activity. The next section discusses how to integrate the Process With External Steps business process with an external system using the REST API.

Note that external activities appear in a user's inbox in Process Portal, but there is no option to execute such activities from the Portal interface, as shown in Figure 9. For activities implemented as human services using coaches, Portal provides an option to execute them.

Back to top

Using the REST API

The REST API makes integration with an external system quite simple. In WebSphere Lombardi Edition V7.2, the REST API was an optional (not official) package. In IBM BPM V7.5.1, the REST API is part of the core product and installed by default.

Using the REST API, you can execute and complete external activities programmatically. You can implement, for instance, a Java Swing or an SWT user interface for users to enter the required data to complete a step in a process. The Java application sends, via the REST API, the values needed to move forward to the next step in a business process. Not only can you execute an external implementation with the REST API, but you can also execute a service or start a business process, among other functions.

Note that you can write a REST client in the language of your choice to access the IBM BPM server via the REST API.

Back to top

REST API clients

JavaScript

A Web client tool is installed on each Process Center and Process Server node as part of the IBM BPM installation. This client tool is useful for learning and getting familiar with the capabilities and functions provided by the REST API. For instance, you can learn about the actual HTTP calls that are made, which is useful for writing your own REST client implementation in the language of your choice. To access this Web client, you can direct your Web browser to the following URL:

http://host_name:port_number/bpmrest-ui

Where:

• host_name is the network name for the host of the process server (or Process Center).
• port_number is the HTTP port number used by the REST API Web client tool. The port number depends on your system configuration (the default port number is 9080).

For example, if your IBM BPM server, such as "server1", uses port 9080 as the HTTP server port, you would open the http://server1:9080/bpmrest-ui URL in your browser to access the Web client. For further details about using the Web client, see the Information Center.

This browser-based client tool for the REST API makes AJAX calls to connect to the IBM BPM server. However, if you are thinking that you can implement a JavaScript client for your own Web application to invoke the REST API, there is a limitation. If you were to make AJAX calls to invoke the REST API from your Web application, it does not work unless your Web application is served from the same server (same hostname and port number) that also hosts the IBM BPM business process. Note that this happens to be case for the Web client tool that is shipped with the product. The browser is only allowed to establish new network connections back to the machine, which initially served up the request (see the same-origin policy documentation on Wikipedia and on W3C).

There are options to work around the limitations imposed by the same-origin policy. For instance, from a browser's perspective, your Web application and IBM BPM need to appear to be on the same server to overcome these restrictions. You can achieve this by using proxy gateways. However, depending on the network infrastructure where your Web application and IBM BPM will be deployed, or the cost to add such components to the network, this may not be a feasible solution. A more feasible and common solution is to use JSONP, which allows a page to request data from a server in a different domain. If you are familiar with HTML, you probably know that the <script> element is not constrained by the rules imposed by the same-origin policies. JSONP simply exploits the open policy for <script> elements, allowing a page to collect data from a different domain.

To use JSONP, the server you are connecting to must support it. IBM BPM V7.5.1 supports JSONP (though not enabled by default), and hence, you can write JavaScript that makes use of this technology. To enable JSONP on your IBM BPM installation, you need to update the 100Custom.xml file to include the configuration as shown in Listing 1.

<properties>
 <common merge="mergeChildren">
 <jsonp-enabled merge="replace">true</jsonp-enabled>
 </common>
</properties>

The 100Custom.xml file is found in the following folder:

<BPM installation-folder>/profiles/<profile-root>/config/cells/<cellname>/
 nodes/<nodename>/servers/<servername>/<server type>/config/

Once support for JSONP is enabled on your IBM BPM server, you can write the code to invoke the REST API similar to the one shown in Listing 2.

<html>
…
<head>
…
<script type="text/javascript">
 dojo.require("dojo.io.script");
</script>
…
</head>
<body>
 <script type="text/javascript">
 dojo.require("dojo.io.script");
 dojo.io.script.get(
 {
 callbackParamName : "callback",
 url : "http://localhost:9080/rest/bpm/wle/v1/exposed/process" +
 "?accept=application/x-javascript",
 load : function(data) {
 dojo.byId("results").innerHTML = "<pre>Data: " +
 dojo.toJson(data, true) + "</pre>";
 },
 error : function(error) {
 dojo.byId("results").innerHTML = "<pre>Error: " +
 dojo.toJson(error, true) + "</pre>";
 }
 });
 </script>
 <b>REST API method invocation for exposed processes (in JSON):</b>
 <div id="results" style="height: 200px;"></div>
</body>
</html>

The code snippet shown in Listing 2 uses the Dojo framework to execute a JSONP call that gets a list of the business processes that users can start in Process Portal. For further information about JSONP and the REST URLs provided by IBM BPM, see the Content types supported by the IBM BPM REST APIs and the REST Interface for BPD-related Resources topics in the Information Center. Writing a JavaScript client that uses JSONP to invoke the REST API is beyond the scope of this article. The details described above will help you get you started if you intend to write a JavaScript client for your project.

Java

There may be several reasons why you may need to implement a non-browser based client to invoke the REST API:

• An organization or department has a set of self-imposed rules or policies that do not allow JSONP to be enabled on the IBM BPM server.
• Technical requirements, that require a design where the REST API, are not called from the browser. They are called from the application server that hosts the Web application.
• A standalone Java application that uses Swing is being developed as the frontend for the external activities steps in a business process.

In other words, there may be strong technical reasons, depending on the requirements for the solution, for not invoking the REST API directly from the browser.

A sample Java client

A reusable REST client written in Java is provided with this article. This client allows you to perform the following basic tasks in IBM BPM:

• Start a business process.
• Run a service.
• Finish a task.
• Get task details.
• Reassign a task to a specific user.
• Reassign a task to the user submitting the REST call.
• Basic searching.

The above methods are enough to integrate an external system with a business process in IBM BPM. However, depending on the specific needs of a project, additional methods and functions may be needed. Note that this sample client is provided "as is", but you can change or improve the code in any way you would like.

A sample Java standalone application that uses the reusable Java REST client to execute the Process With External Steps business process diagram (introduced earlier) is also provided with this article.

To use the sample Java REST client in a Java standalone application, first create an instance of the BPMClientImpl class, as shown in Listing 3.

// Hostname of the IBM Business Process Manager server
String hostname ="localhost";
// IBM Business Process Manager server port number
int port = 9080; 
// The userid to connect to Lombardi Edition, such as tw_admin
String userid = "userid";
// The password that corresponds to the specified userid
String password = "password";
// Create WASAuthenticationTokenHandler instance
AuthenticationTokenHandler handler =
 new WASAuthenticationTokenHandler(userid, password); 
// Create REST client
BPMClient client = new BPMClientImpl(hostname, port, handler);

REST method calls made through the BPMClientImpl instance are all executed under the context of the same user's account. The user's account is identified by the credentials used to create an instance of the WASAuthenticationTokenHandler class (see Listing 3).

REST client running on WebSphere Application Server: If instead of developing a Java standalone program, you were developing a Web application to be deployed on WebSphere Application Server (hereafter called Application Server) and single sign-on was set up for Application Server and the IBM BPM server, use the no-argument constructor of the WASAuthenticationTokenHandler class. In such cases, the REST method invocations are automatically made under the identity of the authenticated user who is accessing the Web application. If single sign-on is not set between Application Server that is hosting the Web application and IBM BPM, then the constructor of the WASAuthenticationTokenHandler class shown in Listing 3 is used. For further details, see the Javadoc comments in the code.

Once an instance of the BPMClientImpl class is created, you can start making REST invocations. The pseudocode in Listing 4 shows how the sample Java application uses the Java REST API client to execute the Process With External Steps business process.

JSONObject results; 

// Create input argument to start the business process
JSONObject bpdArgs = new JSONObject();
bpdArgs.put("priority", "high");

// Start the business process (Process With External Steps)
results = client.runBPD(BPD_ID, PROCESS_APP_ID, bpdArgs);
int processID = results.getJSONObject("data").getInt("piid");

// Retrieve the inbox (list of user tasks) for the user
results = client.getInbox();

// Find reference to first external task in process in user's inbox
JSONObject externalTask_1 = . . .
int externalTaskID_1 = externalTask_1.getInt("taskId");

// Get details for external task/activity
results = client.getTaskDetails(externalTaskID_1);
parseVariables(results);

// Get model for external task/activity
String externalActivityID_1 = results.getJSONObject("data")
 .getString("externalActivityID");
results = client.getExternalActivityModel(externalActivityID_1); 
parseActivityModel(results); 

// Claim External Activity 1
results = client.reassignTask(externalTaskID_1); 

// Complete External Activity 1
JSONObject outputTask_1 = new JSONObject();
JSONObject user = new JSONObject();
user.put("name", "John");
user.put("age", "25");
user.put("numberOfClaims", "10");
user.put("zipCode", "78758");
outputTask_1.put("user", user); 
results = client.finishTask(externalTaskID_1, outputTask_1); 

// Retrieve the inbox (list of user tasks) for the user
results = client.getInbox();

// Get reference to second external task in process
JSONObject externalTask_2 = . . . 
int externalTaskID_2 = externalTask_2.getInt("taskId");

// Get details for external task/activity
results = client.getTaskDetails(externalTaskID_2); 
parseVariables(results); 

// Process input values (here we'd process quote and rating input values) 
// ... 

// Get model for external task/activity
String externalActivityID_2 = results.getJSONObject("data").
 getString("externalActivityID");
results = client.getExternalActivityModel(externalActivityID_2); 
parseActivityModel(results); 

// Claim External Activity 2
results = client.reassignTask(externalTaskID_2); 

// Complete External Activity 2
JSONObject outputTask_2 = new JSONObject();
outputTask_2.put("accepted", true); 
results = client.finishTask(externalTaskID_2, outputTask_2); 

// Run a service
JSONObject servArgs = new JSONObject();
servArgs.put("orderNumber", 1234); 
results = client.runService(ACRONYM + "@Sample Service", servArgs); 
//Process data returned from service invocation
...

The pseudocode in Listing 4 starts by kicking off the business process in IBM BPM using the runBPD() method. Note that to identify the business process to start, the business process ID for the Process With External Steps business process and the corresponding process application ID must be provided as input arguments. You can query the IBM BPM database to obtain the values for these two IDs, or you can use the out-of-the-box Web client tool. From the client tool's main page, expand the Process API node, select the Exposed Processes option, and then click the Execute Call button. You then see on the right side of the window a list of all the processes that users can start in Process Portal. Among the data returned for each one of these processes, there are the business process ID (the itemID) and the process application ID (the processAppID), as shown in Figure 10.

Once the business process is started in IBM BPM, the sample application retrieves the inbox (list of tasks) for the user by invoking the getInbox() method. The items in the inbox are then parsed on the client side to obtain a reference to the first external implementation (External Activity 1) in the business process. Once a reference to this activity is obtained, its details such as the values for the input variables and the due date of the task, are obtained by invoking the getTaskDetails() method. Looking at the data returned from this method, you find the priority value that was passed as an input parameter to the business process is passed in as an input variable to this task. The getExternalActivityModel() method is then called to obtain the data types for the inputs and outputs. The sample code then claims and executes the first external implementation by invoking the reassignTask() and finishTask() methods, respectively.

To execute the first external implementation, a JSON object that matches the structure of the User data type (see Figure 5) is created. As you may recall from Figure 6, an object of the User data type is the output for External Activity 1. Hence, this JSON object is sent to the IBM BPM server as part of the response data from the Java application.

After executing the first external implementation, the sample code then also searches, claims, and completes the second external implementation. As shown earlier in Figure 7, External Activity 2 has two input and one output variables. To obtain the input values (quote and rating), the task details returned from the IBM BPM server are queried. Looking at the code in Listing 4, you can see that the Java REST client always returns a JSON object. Therefore, to query the returned data is simply a matter of calling the getter methods available on the JSON object. Listing 5 shows the code for two methods in the sample Java application that use the getter methods on the JSON object to read the data returned from the IBM BPM server.

private void parseVariables(JSONObject taskDetails) throws JSONException {
 JSONObject variables = taskDetails.getJSONObject("data")
 .getJSONObject("data").getJSONObject("variables");
 @SuppressWarnings("rawtypes")
 Iterator keys = variables.keys();
 System.out.println("-------- Variable values (start) -------- ");
 while (keys.hasNext()) {
 String variableName = (String) keys.next();
 Object value = variables.get(variableName);
 System.out.println(variableName + " : " + value); 
 }
 System.out.println("-------- Variable values (end) -------- ");
}

private void parseActivityModel(JSONObject activityModel) throws JSONException {
 String types[] = { "inputs", "outputs" };
 JSONObject model = activityModel.getJSONObject("data");
 for (String type : types) {
 JSONObject ios = model.getJSONObject(type); 
 @SuppressWarnings("rawtypes")
 Iterator params = ios.keys();
 System.out.println("-------- " + type + " (start) -------- ");
 while (params.hasNext()) {
 String variableName = (String) params.next();
 JSONObject param = ios.getJSONObject(variableName); 
 System.out.println(variableName + " : " + param); 
 }
 System.out.println("-------- " + type + " (end) -------- ");
 }
}

The first method, parseVariables(), reads the names and values assigned to the inputs and outputs of an external implementation. Note that when this method is called, the output values are null since these are the values to be sent back to the server once the external task is completed.

The second method, parseActivityModel(), obtains the data types for the inputs and outputs of an external implementation. The outputs that result from executing these two methods for External Activity 2 are shown in Listing 6 and Listing 7.

-------- inputs (start) --------
quote : {"isList":false,"type":"Integer"}
rating : {"isList":false,"type":"Integer"}
-------- inputs (end) --------
-------- outputs (start) --------
accepted : {"isList":false,"type":"Boolean"}
-------- outputs (end) --------

-------- Variable values (start) --------
accepted : null
quote : 678
rating : 4
-------- Variable values (end) --------

As expected, Listing 6 shows that there are two input variables for External Activity 2, quote, and rating, and that the data type for both of these variables is an integer. You can also see that there is only one output variable for this external implementation, accepted, which is of a Boolean type.

In Listing 7, you can see the values assigned to the input values (quote and rating). Since this is a sample client application, no business logic was built around the quote and rating values retuned from the IBM BPM server to compute the value for the accepted output variable. Instead, the value for the accepted Boolean output variable was hardcoded to true (as shown in Listing 4). Also, note that once the sample client application completes External Activity 2, System Step 2 is executed and the business process ends.

Finally, the last section of the pseudocode in Listing 4 shows how to invoke a service implemented in IBM BPM named Sample Service. This service receives one argument, an order number, and returns one value (a customer number) as shown in Figure 11.

The implementation for Sample Service generates a random number and multiplies it by the input number that was provided as an argument as shown in Figure 12. To read the returned value from the service is a matter of querying the JSON object that was returned from the service invocation.

Companion files

The complete source code for the sample Java application that executes the Process With External Steps business process is provided with this article:

• The sample application (source and binary) is contained in the bpm-rest-client-demo-app.jar file. This JAR file contains only one Java class named demo.SampleBPMClientApp, which corresponds to the code described earlier in Listing 3 and Listing 4.
• The reusable Java REST client code is packaged in the bpm-rest-client.jar file.

Note that before running the demo.SampleBPMClientApp program, you need to import the External_Interfaces_App - EI_12412_1020_AM.twx file. This TWX file is also included with this article. It contains the Process with External Steps business process diagram.

The Java REST client code is dependent on open source libraries that are also included with this article:

• Restlet JARs:
  • org.restlet.ext.json.jar (V2.0.7)
  • org.restlet (V2.0.7)
• JSON classes:
  • org.json.jar
• Spring core JAR:
  • org.springframework.core-3.0.5.RELEASE.jar

Make sure all the JAR files provided with this article are included in the classpath of the JVM when running the demo.SampleBPMClientApp program. Otherwise, you get ClassNotFoundException errors.

The demo.SampleBPMClientApp program receives, as input run time arguments, the values in the order specified below:

• Hostname: The hostname of the IBM BPM server that hosts the Process With External Steps business process.
• Port number:The HTTP port number of the IBM BPM server that hosts the Process With External Steps business process. The default port is 9080.
• Userid: The user ID for connecting to the IBM BPM server.
• Password: The password of the user ID for connecting to the IBM BPM server.

Runtime environment

The sample Java REST client was successfully tested in a JEE application running on WebSphere Application Server V7 and also in a Java standalone program. For both scenarios, IBM BPM V7.5.1 was used. Also, a single sign-on was set up for WebSphere Application Server hosting the JEE application and the IBM BPM server.

Back to top

Seeing the REST API in action

The best way to see in action how the sample Java application moves the Process With External Steps business process forward is to run the Java code in an integrated development environment, such as Eclipse or Rational® Application Developer. Using an integrated development environment allows you to set breakpoints in the code. For instance, you can set a breakpoint right at the beginning of the code, and then execute the code step-by-step. You can then see in the Inspector perspective of Process Designer how the business process moves forward as the Java code executes. Figure 10 shows the Inspector perspective for the Process With External Steps business process while the sample Java code is running.

Back to top

Conclusion

This article showed how you can easily integrate the REST API with an external system with IBM Business Process Manager. By using the REST API, an external application can, among other functions, start a business process, complete an activity or step in a business process, get details about an activity (for example, inputs and outputs), and execute a service. If you have to integrate an external application, such as a Java standalone program or a JEE application with a business process implemented in IBM BPM, consider using the REST API.

Back to top

Download

Information about download methods

Resources

• See Content types supported by the IBM BPM REST APIs for more information about JSONP and IBM Business Process Manager.
  
  
• See REST Interface for BPD-related Resources for complete documentation on the different HTTP REST API calls available in IBM Business Process Manager.
  
  
• See the same-origin policy documentation on Wikipedia and on W3C.
  
  
• Download the latest and stable Restlet implementation.
  
  
• Download the classes for supporting JSON in Java.
  
  
• See the IBM Business Process Manager V7.5.1 Information Center for information about using Business Process Manager and its features.
  
  
• See the IBM Business Process Management zone on developerWorks for technical resources on business process management, including the latest how-to articles and tutorials.
  
  

About the author

Ricardo Olivieri is a Software Engineer in IBM Software Services for WebSphere. His areas of expertise include architecting, designing, and developing software applications (mainly web and database centric applications), administrating and configuring WebSphere Application Server, and distributed software architectures. Ricardo has several years of experience in Java development as well as in Groovy, Perl, and Python development, with a strong background in backend development (server side, business logic, databases, SQL) and frontend development. Ricardo has recently added to his bag of tricks BPM development using WebSphere Lombardi Edition. Through his years at IBM, Ricardo has learned and used many open source frameworks, libraries, and projects such as Drools, Spring, Struts, Restlet, Hibernate, Dojo, and JasperReports. He has a B.S. degree in Computer Engineering from the University of Puerto Rico, Mayagüez Campus.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Integrating a business process with an external user interface
• Using the REST API
• REST API clients
• Seeing the REST API in action
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: IBM Business Process Manager
• Demo: IBM Business Process Manager demos
• Buy: IBM Business Process Manager

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers