Leveraging business data attributes in IBM Business Process Manager V7.5 and V8

Personalizing your BPM applications

In most cases, you'll want business data contained in active business processes to be exposed so that you can customize your Process Portal inbox or so the data can be extracted from an active process via the REST API so that it can be used in a custom user interface. In this article, you will learn how to expose data to do both. This content is part of the IBM Business Process Management Journal.

Share:

Owen Cline (owenc@us.ibm.com), Lead BPM Architect, IBM Software Services for WebSphere , IBM

Owen Cline photoOwen Cline is the Lead BPM Architect for the IBM account and ISSW Latin America, He is based in San Diego, CA. Owen earned a BS in Computer Science from the University of Pittsburgh and an MS from San Diego State University. He has over 20 years of experience in the software development field. He holds four software patents, has written IBM Redbooks, and has presented at multiple technical conferences. For the past five years, Owen has specialized in BPM, SOA and J2EE architecture, application development, and deployment, with a special emphasis on the WebSphere platform. In addition, he has also worked on many high-profile web sites over the past few years.



26 September 2012

Introduction

When developing a business process flow in IBM Business Process Manager (IBM BPM), it's important to be able to easily identify multiple process instances. If your business process flow includes process-level variables (for example customer data) that uniquely identify one process instance as distinct from another, you'll want to expose those process-level variables throughout the BPM infrastructure. The key to doing this is to leverage business data with saved search queries. In this article, you'll learn how to achieve this in both IBM BPM V7.5 and IBM BPM V8.


A simple business process definition

Figure 1 illustrates a simple business process definition (BPD). The first human task (EnterCustomerData) allows you to enter in the customer record data (Name, Address and Phone Number). The second human task is there to block the process instance from automatically completing once the EnterCustomerData human task completes.

Figure 1. A simple BPD
A simple BPD

In addition, one business object named Customer is passed through all the activities of the BPD. As shown in Figure 2, Customer has the complex type CustomerRecord, which has three string attributes: Name, Address and PhoneNumber.

Figure 2. Customer business object definition
Customer business object definition

Expose business data in your process in IBM Business Process Manager V8

First you need to mark any attributes that you want to expose as business data. This is simple to do in Process Designer.

Go to the Variables editor and select the attribute that you want to include as business data. Check Available in Search under Business Data Search (top right in the Variables editor pane). By default the Search Alias is set to the attribute name. You can leave the default value (unless you have a strong preference for another alias).

Figure 3. Make the Name attribute usable as business data
Make the Name attribute usable as business data

Repeat this process to mark the Address and PhoneNumber attributes as business data.

Verify that the business data is visible in the Process Portal

To verify that the attributes are functioning correctly as business data, start a process instance for the newly modified process application. Then log into the Process Portal (http://localhost:9080/portal). Note: Throughout this article, all URLs are displayed with the host name set to localhost and the port set to 9080. Make sure to substitute the appropriate values for your environment.

Now, find the process instance for which you expect to have business data available. In the My Tasks pane, click the row that contains the task you're interested in. Note that if you click on the task itself [instead of the row], the BPM portal will open the task. You should now see your business data displayed, as shown in Figure 4.

Figure 4. Close-up view of business data in Process Portal My Tasks pane
Close-up view of business data in Process Portal My Tasks pane

If you see the message "No Details Found," the process instance doesn't have any business data defined.

You can also define and save your own search queries and use them to display the business data that you have decided to expose. To do this, start the Process Admin Console by pointing your browser to: http://localhost:9080/ProcessAdmin.

Expand Saved Search Admin in the left navigation pane and click Saved Search Admin, as shown in Figure 5.

Figure 5. Select Saved Search Admin in the Process Admin Console
Select Saved Search Admin in the Process Admin Console

(See a larger version of Figure 5.)

Select Define New Search in the BPM Search Criteria Editor, as shown in Figure 6. Note that if you need to edit an already defined search, you can choose the search to edit from the Select Search.

Figure 6. Define a new search
Define a new search

Specify a meaningful name for the search, as shown in Figure 7.

Figure 7. Name the search
Name the search

Now you need to define the columns of data that will be displayed when your saved search runs. You can select Process, Process Instance, Task, and Business Data, as shown in Figure 8. In our case, we'll just use Business Data.

Figure 8. Select Business Data search column
Select Business Data search column

(See a larger version of Figure 8.)

Next you need to define the three columns: Name, Address, and PhoneNumber (each of the business data attributes we exposed), as shown in Figure 9.

Figure 9. Select Address as the first column
Select Address as the first column

(See a larger version of Figure 9.)

Repeat this step to define the Name and PhoneNumber columns.

Next define a search condition using one of your business data columns, but leave the Value field empty to indicate that it matches anything, as shown in Figure 10.

Figure 10. Define a search condition
Define a search condition

(See a larger version of Figure 10.)

If you don't have a search condition, the search will match instances that don't even have the business data defined, as shown in Figure 11. Therefore, you should always define a search condition that takes into account the business data columns that are part of the saved search definition.

Figure 11. Search results if no search condition is defined
Search results if no search condition is defined

Now select Process Instance in the Search Organized By menu, as shown in Figure 12. This filters the search results to show only those process instances that have the business data defined (rather than every task instance in the process instance).

Figure 12. Organize the search by process instance
Organize the search by process instance

(See a larger version of Figure 12.)

You're now ready to test the search definition in the Process Admin Console before you save it, by clickng Search as shown in Figure 13.

Figure 13. Test the new search in the Process Admin Console
Test the new search in the Process Admin Console

(See a larger version of Figure 13.)

To test the saved search in the Process Portal, do the following:

  1. Open the Process Portal at: http://localhost:9080/portal. You may need to refresh your browser window if you don't see the Saved Searches link displayed next to My Tasks.
  2. Select a saved search to run, as shown in Figure 14.
    Figure 14. Pick a saved search to run
    Pick a saved search to run

    (See a larger version of Figure 14.)

    You should see the same search results that you saw when you tested the search in the Process Administration Console, as shown in Figure 15.

    Figure 15. Saved search results
    Saved search results

    (See a larger version of Figure 15.)

There are a number of useful REST APIs you can use with saved search queries. You can leverage these REST APIs if you want to use an external user interface to display business data from the BPM runtime engine.

You can open the REST API Tester at: http://localhost:9080/bpmrest-ui/

Process Queries API

You can use the Process Queries API call to return a list of all defined saved search queries. Once the REST client page is loaded, expand the WLE REST APIs => Process API => Process Queries.

You'll see some predefined saved search queries such as:

  • portal.savedsearch.help_reqs
  • IBM.PI_PROCESSLIST_ALL
  • portal.savedsearch.history
  • portal.savedsearch.inbox
  • IBM.DEFAULTALLPROCESSLIST_75

These predefined saved search queries are used by the Process Portal to populate the various lists that it displays, such as My Tasks.

After clicking Process Queries, you can click on Execute Call(without specifying any input parameters) to perform the REST API call and get back a list of saved searches, as shown in Figure 16.

Figure 16. Saved searches
Saved searches

(See a larger version of Figure 16.)

This API is at: http://localhost:9080/rest/bpm/wle/v1/processes/queries

Get the saved search query attribute metadata

Invoke the Process Query Attributes REST API for your saved search query to get a description of all of the attribute data returned in the query row set, as shown in Figure 17.

Figure 17. Run the Process Query Attributes API for your saved search query
Run the Process Query Attributes API for your saved search query

(See a larger version of Figure 17.)

Process Query Entity List Count API

The Process Query Entity List Count REST API, shown in Figure 18, is useful for returning a count of the result set for the specified saved search query.

This API is at: http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch/count

Figure 18. Process Query Entity List Count
Process Query Entity List Count

(See a larger version of Figure 18.)

As a test, try running this REST API with any of the predefined saved search queries by pointing your browser to:
http://localhost:9080/rest/bpm/wle/v1/processes/query/IBM.DEFAULTALLPROCESSLIST_75/count.
In my case, the results are shown in Figure 19.

Figure 19. Search count results
Search count results

This API is at: http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch/count

Process Query Entity List

The Process Query Entity List REST API is useful for returning a complete result set from the saved search query, as shown in Figure 20. The result set is divided into two main sections: attributeInfo and items. The attributeInfo section lists all of the metadata about the business data columns defined in the saved search query. The items section displays the result data for each matched process instance.

Figure 20. Process Query Entity List
Process Query Entity List

(See a larger version of Figure 20.)

This API is at: http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch/count

Process Query Entity List with offset

This REST API is useful for returning a portion of the saved search query result set offset by an integer that you specify, as shown in Figure 21. It can be used to implement a pagination pattern in an external user interface.

Figure 21. Process Query Entity List with offset
Process Query Entity List with offset

(See a larger version of Figure 21.)

This API is at: http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch?offset=1

Process Entity List with size

This REST API is useful for returning a portion of the saved search query result set, as shown in Figure 22. It can be used to implement a pagination pattern in an external user interface.

Figure 22. Process Query Entity List with size
Process Query Entity List with size

(See a larger version of Figure 22.)

This API is at: http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch?size=2

Process Entity List with query filter

This REST API is useful for returning a filtered result set from the saved search query. You can filter on any of the business data attributes (or metadata attributes). You can also employ Boolean logic like AND and OR.

This REST API filters by BD_NAME. Enter the following string for the query filter:

BD_NAME='Acme Tree Service'

The following REST API call is issued:

http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch?queryFilter=BD_NAME='Acme%20Tree%20Service

The REST API can filter by AND'ing BD_NAME and BD_ADDRESS. Enter this string for the query filter:

BD_NAME='Acme Tree Service' AND BD_ADDRESS='121 Main Street'

The following REST API call is issued:

http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch?queryFilter=BD_NAME='Acme%20Tree%20Service'%20AND%20BD_ADDRESS='121%20Main%20Street

This REST API can also filter by OR'ing BD_NAME and BD_ADDRESS. Enter the following string for the query filter:

BD_NAME='Acme Tree Service' OR BD_ADDRESS='1221 Main Street'

The following REST API call is issued:

http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch?queryFilter=BD_NAME='Acme%20Tree%20Service'%20OR%20BD_ADDRESS='1221%20Main%20Street

Figure 23. Query filter using BD_NAME
Query filter using BD_NAME

(See a larger version of Figure 23.)

Process Query Entity List with selected attributes

This REST API call is useful for reducing the saved search query to a subset of the business data attributes. Below only the BD_NAME and BD_ADDRESS business data attributes are requested (the BD_PHONE_NUMBER business data attribute is excluded).

Figure 24. BD_NAME and BD_ADDRESS selected attributes
BD_NAME and BD_ADDRESS selected attributes

(See a larger version of Figure 24.)

This API is at:
http://localhost:9080/rest/bpm/wle/v1/processes/query/CustomerSearch?selectedAttributes=BD_NAME,BD_ADDRESS


Expose business data in your process in IBM Business Process Manager V7.5

In BPM V7.5, you expose variables in your process from within Process Designer. To do this, check Available in Search and enter a Search Alias. Figure 25 shows a primitive data type being enabled for a business search.

Figure 25. Enable data type for search
Enable primitive data type for search

(See a larger version of Figure 25.)

Figure 26 shows a primitive data type inside a complex type being enabled for a business search.

Figure 26. Enable primitive data type for search
Enable primitive data type for search

(See a larger version of Figure 26.)

Create a saved query in Process Portal

The steps for creating a saved search are described in the Information Center topic Creating a saved search in Process Portal. Figure 27 shows the search definition for the BusinessData search. To be clear, BusinessData is a custom saved search, not an out-of-the-box search option.

Notice that there are a number of attributes available to choose from that are prefixed as business data variables.

Figure 27. Business data search definition
Business data search definition

(See a larger version of Figure 27.)

In Figure 28, shows the results of the saved query called BusinessData in the Process Portal. Notice the three columns that are exposed business data variables:

  • SecondApprovalUserOrGroupName
  • FurtherApprovalRequired
  • FurtherApprovalForGroup
Figure 28. Business data query results
Business data query results

(See a larger version of Figure 28.)

Note: In BPM V7.5.1, defining a saved search does not make it available to all users but only to the user who defined it. In BPM V7.5.1, if you want to create a saved search that will be shared with other users, you need to do the following:

  1. Log in as the tw_portal_admin user.
  2. Define the saved search.
  3. Select the saved search, then select the option to share it with other users.

Use the BPM REST API Tester to run your saved query

If you run the REST API Tester at http://localhost:9080/bpmrest-ui/, the business data variables shown in Figure 29 are returned.

Figure 29. Test results
Test results

(See a larger version of Figure 29.)

Notice that the Query Name field is filled in with BusinessData and the Display field is processes because business data variables are at the process scope and not the task scope.

Examine the REST API output

Below is the output from the REST API Tester (http://localhost:9080/rest/bpm/wle/v1/processes/query/BusinessData):

Request: http://localhost:9080/rest/bpm/wle/v1/processes/query/BusinessData

Status: 200 - OK

Header:
Content-Type: application/json Content-Language: en-US Transfer-Encoding: chunked Date: 
Wed, 07 Sep 2011 00:17:24 GMT Server: WebSphere Application Server/7.0 

Result:
{
status: "200", 
data: {
identifier: "PROCESS_INSTANCE.PIID", 
query: "BusinessData", 
entityTypeName: "PROCESS_INSTANCE", 
attributeInfo: [
{
name: "PT_DISPLAY_NAME", 
type: "STRING", 
content: "PROCESS_INSTANCE.DISPLAY_NAME", 
isArray: false, 
sourceAttribute: "BusinessData.bpdName", 
sourceQueryTableIdentifier: "n/a" 

},
{
name: "BD_SECOND_APPROVAL_USER_OR_GROUP_NAME", 
type: "STRING", 
content: "TASK.BD_SECOND_APPROVAL_USER_OR_GROUP_NAME", 
isArray: false, 
sourceAttribute: "BusinessData.SecondApprovalUserOrGroupName", 
sourceQueryTableIdentifier: "n/a" 

},
{
name: "PT_NAME", 
type: "STRING", 
content: "PROCESS_INSTANCE.NAME", 
isArray: false, 
sourceAttribute: "BusinessData.bpdName", 
sourceQueryTableIdentifier: "n/a" 

},
{
name: "PI_DUE", 
type: "TIMESTAMP", 
content: "PROCESS_INSTANCE.DUE", 
isArray: false, 
sourceAttribute: "BusinessData.instanceDueDate", 
sourceQueryTableIdentifier: "n/a" 

},
{
name: "PI_NAME", 
type: "STRING", 
content: "PROCESS_INSTANCE.NAME", 
isArray: false, 
sourceAttribute: "BusinessData.instanceName", 
sourceQueryTableIdentifier: "n/a" 

},
{
name: "BD_FURTHER_APPROVAL_REQUIRED", 
type: "BOOLEAN", 
content: "TASK.BD_FURTHER_APPROVAL_REQUIRED", 
isArray: false, 
sourceAttribute: "BusinessData.FurtherApprovalRequired", 
sourceQueryTableIdentifier: "n/a" 

},
{
name: "BD_FURTHER_APPROVAL_FOR_GROUP", 
type: "BOOLEAN", 
content: "TASK.BD_FURTHER_APPROVAL_FOR_GROUP", 
isArray: false, 
sourceAttribute: "BusinessData.FurtherApprovalForGroup", 
sourceQueryTableIdentifier: "n/a" 

},
{
name: "PI_DISPLAY_NAME", 
type: "STRING", 
content: "PROCESS_INSTANCE.DISPLAY_NAME", 
isArray: false, 
sourceAttribute: "BusinessData.instanceName", 
sourceQueryTableIdentifier: "n/a" 

}
], 
items: [
{
PI_NAME: "FurtherApprovalsSubProcess:603", 
BD_SECOND_APPROVAL_USER_OR_GROUP_NAME: "tw_admin", 
BD_FURTHER_APPROVAL_REQUIRED: true, 
PT_DISPLAY_NAME: "Multi-LevelApprovals", 
BD_FURTHER_APPROVAL_FOR_GROUP: false, 
PT_NAME: "Multi-LevelApprovals", 
PROCESS_INSTANCE.PIID: "603", 
PI_DISPLAY_NAME: "FurtherApprovalsSubProcess:603", 
PI_DUE: "2011-09-19T22:51:13Z" 

}
] 
} 
}

If you examine the REST API output, you'll see two sections. The first section is marked as data and the second is marked as items. The data section includes elements for all attributes, including the business data attributes. The items section includes elements for all active processes, also including the business data attributes.


Conclusion

Most of the time, it's necessary that actual business data be exposed from process instances. This article outlined how to define select variables in your BPD as business data. It also explained how you can leverage saved search queries to expose the business data in process instances. Finally, the article showed you how to use the BPM REST APIs to run saved search queries. This technique is especially useful when you're developing an external user interface and need to build a custom inbox in the external user interface.

Resources

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 Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=836690
ArticleTitle=Leveraging business data attributes in IBM Business Process Manager V7.5 and V8
publish-date=09262012