Setting custom properties for new query requirements in WebSphere Process Server

When developing a business process client program, you often need to query process instances, activities, and tasks within a certain process instance by certain business data criteria. This article shows you how to set the custom properties for the process instance to meet new query requirements by a dynamic method in WebSphere® Process Server.

Xiang Cheng (xcheng@cn.ibm.com), Software Engineer, IBM

Photo of Xiang ChengXiang Cheng is a Software Engineer at the IBM China Development Lab. He has a Master's degree in Computer Science and Technology from Tongji University, China. He has 4 years of development experience.


developerWorks Contributing author
        level

Zhu Liang, Software Engineer, IBM

Photo of Zhu LiangZhu Liang is a Software Engineer at the IBM China Global Delivery Center. He has a Bachelor's degree in Computer Science and Technology from Shanghai University of Finance and Economics, China. He has 2 years of development experience.



Pei Jian Dong (dongpj@cn.ibm.com), Software Engineer, IBM

Photo of Pei Jian DongPei Jian Dong is a Software Engineer at the IBM China Development Lab. He has a Master's degree in Computer Science and Technology from Shanghai Jiao Tong University, China. He has 3 years of development experience.



02 June 2010

Also available in Chinese Russian

Introduction

When you develop a business process client program, you often need to query process instances, activities, and tasks within a certain process instance by certain business data criteria. For example, you may want to find all the tasks in process instances concerning a customer with a given customer ID.

You can implement this requirement by setting custom properties for the human task when you design the process in WebSphere Integration Developer (hereafter called Integration Developer). However, this does not help when the new custom properties are required for new query requirements after the processes are put in use. You can certainly add the new custom properties in a new version of the business process with the process version technique offered by WebSphere Process Server (hereafter called Process Server). However, the existing instances of the old version of the process cannot be queried by the new custom properties.

This article will help the business process designer and programmer who are familiar with the business process development. It assumes that you are familiar with Process Server and developing business process applications with Integration Developer. We suggest that you go through the Business Process Management samples & tutorials - Version 6.1 if you have no experience.

This article assumes that Integration Developer V6.1.2 has been installed properly. You can also find more information in the Resources section of this article.

This article introduces a dynamic method with the Business Process Choreographer (BPC) EJB API to set the custom properties for the running process instances to resolve this type of problem.

We will employ a simple order audit process to illustrate this solution. The work flow of the sample process includes the following typical steps:

  • The customer submits an order request, which contains the information about the customer, auditor, and so on.
  • The auditor approves or rejects the request.
  • Lastly, the system gives the customer a response after the auditor approves or rejects the request.

The sample and the modules will be illustrated in the following sections.


Prepare the sample process project

Import the project interchange file with the prepared business process as follows:

  1. Download the provided OrderDemo.zip file and save it to a temporary directory.
  2. In WebSphere Integration Developer, click File -> Import. The Import dialog opens.
  3. Select Project Interchange.
  4. Click Next. The Import Project Interchange Contents window opens (Figure 1).
    Figure 1. Import dialog
    Import dialog
  5. Click Browse next to “From zip file”.
  6. Browse to the temporary directory and select the zip file you downloaded in Step 1.
  7. Click Open.
  8. Select your workspace directory as your Project location root.
  9. Click Select All.
  10. Click Finish.

You need to import the provided OrderDemoLib.zip, which includes the data types of the process into the workspace using the similar steps above. You will get the project structure as shown Figure 2. The detailed explanations will be given in the following sections.

Figure 2. Process project structure
Process project structure

Business object and BPEL process

There are two business objects (BO) needed for the order audit process: OrderRequest and PersonInfo (Figure 3). OrderRequest holds the order information that includes customer, auditor, status, and goodsNo. PersonInfo contains personal information such as ID, name, and address.

Figure 3. Business object
Business object

Figure 4 shows the BPEL process designed in Integration Developer:

  1. The Receive activity is the starting point of the process. The process receives a message (OrderRequest) from the client, which starts the process. The data from that message is stored in a process variable (request).
  2. The Assign activity performs the data mapping required for the process.
  3. The Order Info snippet prints the order information.
  4. ApproveOrderRequest is a human task for the auditor to approve or reject the request.
  5. The Approve choice determines the next step according to the auditor’s decision. The system will print the response accordingly, using the Approve Response and Reject Response snippets.
    Figure 4. Process
    Process

Run the sample using BPC Explorer

Run the sample with the Business Process Choreographer (BPC) Explorer using the following steps after you have deployed the OrderDemoApp on the test server embedded in Integration Developer.

  1. Select OrderProcess on the “My Process Templates” page (Figure 5) and click Start Instance.
    Figure 5. Process template
    Process template
  2. Fill in the Process Input Message section and click Submit (Figure 6).
    Figure 6. Process Input Message
    Process Input Message
  3. Work on the ApproveOrderRequest human task on the My To-dos page (Figure 7).
    Figure 7. My To-dos
    My To-dos
  4. Input the Task Output Message (entering true to approve or false to reject). Click Complete (Figure 8).
    Figure 8. Work on the Task Message
    Work on the Task Message
  5. You may see the test result (the log printed in the Java™ snippet) in the console (Figure 9).
    Figure 9. Console
    Console

Why you need to set the custom property

Generally, you need to develop a client application to initiate and complete process instances instead of using the BPC Explorer. WebSphere Process Server V6 provides the BPC EJB API to access and handle business processes and human tasks. There are actually two respective sets of APIs: Business Flow Manager API and Human Task Manager API.

When building the process client application, it is often desirable to locate a specific process instance or human task, whose business data fulfills certain criteria. For example, it may be necessary to find the process instance by the specific order number.

This section illustrates why you need to set custom property for query requirements. Before you query out the tasks, you need to start the process instances.

You can import the provided OrderProcessExport.zip into your work space following the similar steps to import the process project as well. All of the code snippets in the following sections are found in this project.

Listing 1 shows the code snippet to initiate one "OrderProcess" instance with an input message using the Business Flow Manager API.

Listing 1. Initiating process with BPC EJB API
// Create the input ClientObjectWrapper
com.ibm.bpe.api.ClientObjectWrapper cow = flows.createMessage(
		processTemplate.getID(), processTemplate.getInputMessageTypeName());
// Get the Input DataObject from the ClientObjectWrapper
DataObject dataObject = (DataObject) cow.getObject();
	
dataObject.setDataObject("request", OrderRequest);
//Initiate process instance
com.ibm.bpe.api.PIID piid = flows.initiate("OrderProcess", cow);

After the process instance is initiated, the human task named "ApproveOrderRequest" will be started and will be waiting for the auditor to complete. Before you can complete the task, you need to query out it by the order number. Listing 2 shows the code snippet to filter the task by the order number using the Human Task Manager.

Listing 2. Get specific to-do task by order number
QueryResultSet instances = htms.query("DISTINCT TASK.TKIID", 				
 "TASK.NAME='OrderProcess$ApproveOrderRequestTask' AND 
TASK.STATE=TASK.STATE.STATE_READY", null, null, null, null);

while (instances != null && instances.next()) {
	TKIID tkiid = (TKIID) instances.getOID(1);

	ClientObjectWrapper cow = htms.getInputMessage(tkiid.toString());
	DataObject input = (DataObject) cow.getObject();

	if (orderNo.equals(input.getString("orderNo"))) {
		System.out.println("find!!!");
	}
}

You can make the SQL query on the predefined BPC database view. However, the business data, like the order number you defined in the input message (business object), cannot be queried in the database view. You have to filter it by the input message of the process from all of the to-do tasks. This method will result in performance issues if there are many to-do tasks for the auditor. You also need to improve the query method and custom property to meet your requirement. You can specify the custom properties for a business process and all of its basic activities. A custom property has a name and an optional (string) value. The BPC database offers a PROCESS_ATTRIBUTE view with which you can query processes human tasks by defining the order number as the process custom property.

Except for performance concerns, there is another important reason: if the query criteria is not contained in the input message of the process, you cannot filter the instances with the input message. However, you can set the criteria as custom properties with the BPC EJB API to meet this kind of requirement.

Before you can query by custom property, you need to set the custom property for the process instance.


How to set the custom property

You can set the custom property either using a Java snippet in the BPEL process or using the BPC EJB API when initiating the process instance. We will illustrate these two methods in the following sections.

Set the custom property using a Java snippet in Integration Developer

You can add a Java snippet at the beginning of the process. Input the following set sentence as shown in Figure 10:

setProcessCustomProperty(“orderNo”, orderNo);
Figure 10. Set process custom property using Java snippet
Set process custom property using Java snippet

Set the custom property with BPC EJB API

You can also set the order number as the custom property using the BPC EJB API after the process instance is initiated, as shown in Listing 3.

Listing 3. Set custom property with BPC EJB API
String orderNo = request.getString("orderNo");
if (orderNo != null && !"".equals(orderNo)) {
	bfms.setCustomProperty(piid, "orderNo", orderNo);
}

You can view the custom property after the process is initiated in the BPC Explorer as shown in Figure 11.

Figure 11. Examining the property of an existing process instance
Examining the property of an existing process instance

Query the to-do task by the predefined custom property

You can query the custom property using the predefined BPC database view PROCESS_ATTRIBUTE as shown in Table 1.

Table 1. PROCESS_ATTRIBUTE view
Column name Type Comments
PIID ID The ID of the process instance that has a custom property.
NAME String The name of the custom property.
VALUE String The value of the custom property.

Listing 4 shows how to query the to-do tasks by the custom property.

Listing 4. Query to-do task by the predefined custom property
QueryResultSet instances = htms.query("DISTINCT TASK.TKIID", 
 "WORK_ITEM.OBJECT_ID = TASK.TKIID AND WORK_ITEM.ASSOC_OID = PROCESS_ATTRIBUTE.PIID AND  
 PROCESS_ATTRIBUTE.NAME= 'orderNo' AND PROCESS_ATTRIBUTE.VALUE ='" + orderNo + "' AND 
 (TASK.STATE = TASK.STATE.STATE_READY OR TASK.STATE = TASK.STATE.STATE_CLAIMED ) AND 
 TASK.SUSPENDED = FALSE AND WORK_ITEM.REASON=1 AND WORK_ITEM.OBJECT_TYPE=5 ", 
 null, null, null, null);
			 
if (instances.size() > 0) {
	instances.first();
	TKIID tkiid = (TKIID) instances.getOID(1);
	ClientObjectWrapper cow = htms.getInputMessage(tkiid.toString());
	DataObject input = (DataObject) cow.getObject();
	
}

You can get the task ID for the order number directly using the query by the custom property. This can result in better performance.


How to meet new query requirements

What can you do when a new query requirement comes after the business process has been in production? For example, you want to query the process instance by customerId instead of orderNo. You need to add a new custom property called “customerId” to support the new query requirement. As you know, the sample process is a long-run process, which means there may be many instances running on the production server. That means you need to add the new custom property, not only for the new initiated process instances, but also for the existing instances on the server.

Set the new custom property for the new initiated process instance

There are two methods to implement this requirement. You can implement a new version of your business process to add the new custom property in the Java snippet. For the versioning technique, refer to Versioning business processes and human tasks in WebSphere Process Server. Another way is to add the new custom property, customerId, for the new initiated process instance. With the second method, you do not need to version the process.

From this perspective, it is better to set the custom properties with the BPC EBJ API than to set the custom properties in the BPEL process. With the API, you can add a new customer property dynamic according to the requirement change and you do not need to version the BPEL process. Listing 5 shows how to set a new custom property by using the BPC EJB API.

Listing 5. Set custom property for the new initiated instance
//Initiate the process instance as usual
com.ibm.bpe.api.PIID piid = flows.initiate("orderProcess", cow);
//Set custom property after process instance is initiated.
flows.setCustomProperty(piid, "orderNo",“000001”);
flows.setCustomProperty(piid, "customerId",“C00001”);

Now you can query the to-do task by the the new custom property, customerId, to meet the new requirement.

Set the new custom property for the running process instances

By using the BPC EJB API, you can search the running process instances and add a new custom property for them. Listing 6 shows how to add a new custom property for the running process.

Listing 6. Set custom property for the running instances
QueryResultSet instances = flows.query("DISTINCT PROCESS_INSTANCE.PIID", 
 "PROCESS_INSTANCE.STATE = 2  AND PROCESS_INSTANCE.TEMPLATE_NAME
  ='OrderProcess' ", "", null, null);

while (instances .next())
{
	PIID piid = (PIID) result.getOID(1);
	flows.setCustomProperty(piid, "customerId", customerIdValue);
		 
}

Query the to-do task by the new custom property

Just like the method for querying the to-do task by orderNo, now you can query by customerId (Listing 7).

Listing 7. Query the to-do task by the new custom property
QueryResultSet instances = htms.query("DISTINCT TASK.TKIID", "WORK_ITEM.OBJECT_ID 
 = TASK.TKIID AND WORK_ITEM.ASSOC_OID = PROCESS_ATTRIBUTE.PIID AND 
 PROCESS_ATTRIBUTE.NAME= 'customerId' AND PROCESS_ATTRIBUTE.VALUE ='" + customerId 
 + "' AND (TASK.STATE = TASK.STATE.STATE_READY OR TASK.STATE = TASK.STATE.STATE_CLAIMED ) 
 AND TASK.SUSPENDED = FALSE AND WORK_ITEM.REASON=1 AND WORK_ITEM.OBJECT_TYPE=5 ", null, 
 null, null, null);
if (instances.size() > 0) {
	instances.first();
	TKIID tkiid = (TKIID) instances.getOID(1);
	ClientObjectWrapper cow = htms.getInputMessage(tkiid.toString());
	DataObject input = (DataObject) cow.getObject();
	System.out.println("find customerId:" + customerId	+ " orderNo: 
     " + input.getString("orderNo"));
}

Test the client application in Integration Developer

You can test the OrderProcessExport project, which is a Java client application with all the implementing initiate and query process instances. You can use the test module in Integration Developer to test the function after deploying the two modules, OrderDemo and OrderProcessExport, to the test server in Integration Developer.

Figure 12. Test the client application in Integration Developer
Test the client application in Integration Developer

You can refer to the function description (Table 2) to perform the test.

Table 2. PROCESS_ATTRIBUTE view
Method Name Function
initProcess Initiate a new process instance.
initProcessWithOrderNo Initiate a new process instance and set the custom property, orderNo, for the initiated instance.
initProcessWithCustomerId Initiate a new process instance and set the custom properties, customerId, for the initiated instance.
queryTodoTaskByOrderNo Query the specific to-do task by orderNo of the request.
queryTodoTaskByCustom
PropertyWithOrderNo
Query the specific to-do task by the custom property, orderNo.
queryTodoTaskByCustom
PropertyWithCustomerId
Query the specific to-do task the by custom property, cusomerId.
addCustomPropertyFor
RunningProcess
Add a new custom property for the running process instance.

Conclusion

Business process-based applications can include long-running instances, which can run for weeks, months, or even years. Business requirements evolve over time. WebSphere Process Server V6.1 provides a technology called “process versioning” to help upgrade business-process-based applications to new environments and business needs. However, you also need to modify the existed instances to meet new query requirements. This article introduced a dynamic method using the Business Process Choreographer EJB API to set the custom properties for, not only the new process instance, but also the running instances to meet new query requirements. With this method, you do not need to upgrade the process to add a new custom property.


Downloads

DescriptionNameSize
Sample scriptsOrderDemo.zip11KB
Sample scriptsOrderDemoLib.zip5KB
Sample scriptsOrderProcessExport.zip2,012KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=493753
ArticleTitle=Setting custom properties for new query requirements in WebSphere Process Server
publish-date=06022010