Configuring error handling for Advanced Integration Services in IBM Business Process Manager Advanced V8

In IBM Business Process Manager V8, the Advanced Integration Services (AIS) feature in Process Designer provides the mechanism to integrate with a service component architecture (SCA) service created in Integration Designer. This article shows you how to configure the new error handling feature in BPM V8 to handle any AIS exceptions that may occur.

Share:

Swatee Agrawal (swatee.agrawal@in.ibm.com), IT Specialist, IBM

Swatee Agrawal photoSwatee Agrawal is an Application Integration & Middleware Solutions Specialist with IBM Software Services for WebSphere at the IBM India Software Labs. She has over 10 years of IT industry experience, and has worked on various integration projects using many IBM products, such as WebSphere Process Server, IBM Integration Designer, IBM DataPower, WebSphere Lombardi, and IBM Interchange Server. At present, she is working with WebSphere Education where she designs, develops and delivers IBM Business Process Manager courses. Swatee is certified as an IBM Business Process Manager Advanced V7.5 Application Developer, a Lombardi Business Process Developer, and a WebSphere Application Server Administrator.



19 October 2012

Introduction

IBM Business Process Manager Advanced provides two authoring environments.

  • IBM Process Designer is primarily used by business authors to create human-centric business processes. Because these business authors work very closely with the business owners, they have a good understanding of business needs. To author a business process, business authors use IBM Process Designer and ensure that the process meets the business requirement. Business authors use this tool to create human-centric process.
  • IBM Integration Designer is primarily used by integration developers to implement complex service component architecture (SCA) integration services, for example to integrate with CICS, Enterprise Information Systems (EIS), and so on.

The Advanced Integration Services (AIS) feature of IBM BPM enables collaboration between these two authoring environments. Using AIS you can combine a human-centric process application built in Process Designer with integration-centric services built in Integration Designer to build a robust solution. AIS is basically an SCA service that is called from a process application developed in Process Designer. The SCA service that is created in Integration Designer can be exposed to clients outside the current SCA module using many types of export bindings. For the SCA service to be used by the process application as an AIS, the export binding type must be of SCA type.

Sometimes these SCA services may throw an error when called. Therefore, it's a good practice to include error handling capabilities in your process application, when calling these SCA services. Prior to IBM Business Process Manager Advanced V8, when the SCA service was configured to be used as an AIS, fault specification was not allowed in an AIS interface definition, so fault handling primitives were not supported. In V8, the AIS interface now supports the fault primitive, which enables Process Designer to catch errors that are thrown by the services in Integration Designer when they are called.

Figure 1. Differences in AIS interface between V8 and earlier versions
Differences in AIS interface between V8 and earlier versions

Error handling in IBM BPM V8

You can now build error handling capabilities into business process definitions (BPDs) and services. Table 1 shows how different error events are used in BPDs.

Table 1. Type of error events in BPDs and their usage
BPD eventDescription
Error intermediate event at the boundary of an activity
icon
  • Catches specified errors or all errors
  • Provides error handling logic for errors raised by the activity to which it is attached
Error event subprocess that starts with an error start event
icon
  • Catches specified or all errors
  • Provides error handling logic for errors raised by activities of the BPD, subprocess, or event subprocess that directly contains the error event subprocess
Error end event
icon
  • Throws an error

To understand more about the error events in services and BPDs, refer to Error handling using error events in the IBM Business Process Manager V8 Information Center. For the purpose of this article, the error intermediate event in the BPD is used to catch AIS errors.

When an error intermediate event is attached to the AIS boundary activity, specific or all errors can be caught at runtime depending on the configuration. In BPM Advanced V8, the error handling capability has been enhanced to:

  • Catch specific errors in BPDs and services on the basis of error code, error data or both.
  • Enable multiple boundary error intermediate events to be attached to an activity.

Figure 2 shows the properties of the error intermediate event.

Figure 2. Properties of an error intermediate event
EventDet.jpg

This article walks you through the steps to enable error handling for AIS in IBM BPM Advanced V8. Our scenario uses a bottom-up AIS development approach to implement and test the solution. To understand some of the other types of AIS development approaches, refer to Advanced integration service development process in the IBM Education Assistant.


Getting started

In order to complete the steps in this article, you must have IBM Business Process Manager Advanced V8.0, including IBM Process Designer V8.0 and IBM Integration Designer V8.0 installed on a Windows XP machine.

You should be familiar with the IBM Process Designer and IBM Integration Designer authoring tools and have an understanding of AIS.

Two files are provided for download with this article. You can download and import these files and refer to them as you follow the steps to implement the sample scenario in this article:

  • ApparelStorePI.zip is a project interchange file that you can download and import into Integration Designer.
  • ApparelStoreProcessAPP.twx is a completed process application that you can import into Process Designer.

Sample scenario overview

The sample scenario used in this article is a billing process in an apparel store. The process flows as follows:

  1. The customer shops at the apparel store and goes to the billing counter to make the payment using shopping vouchers.
  2. The billing person collects the order details from the customer, along with the voucher number with which the customer wants to pay for the purchase, then enters the collected information in the online form and submits.
  3. The automatic process, makes a decicison based on the mode of payment ( voucher or credit card):
    • If the mode type is voucher, its validity is checked through the voucher validity AIS service:
      • If the voucher code is 333444, the AIS returns normally and the process goes to the next activity to process payment.
      • If the voucher code is 111222, the AIS returns an error and the process goes back to the billing form to offer a choice to the customer to choose some other mode of payment because the voucher is not valid.
    • If the mode type is credit card, the activity simply goes to the next activity to process the payment and the flow terminates.

Normally, in a bottom-up scenario, the integration developer iteratively develops and tests an SCA module and then performs the integration steps to integrate the SCA module with a process application. Since this article focuses mainly on the configuration and testing of the AIS error handling capability, the article just walks you through the steps needed to build a sample SCA module and integrate it with the process application, followed by the detailed steps to enable error handling in AIS.

Following are the steps to be completed in Integration Designer to build an SCA module and make it available for integration with a process application:

  1. Create an SCA module and library.
  2. Associate the SCA module with a process application.

Following are the steps to be completed in Process Designer to configure and test the AIS error handling capability:

  1. Create a BPD containing the AIS.
  2. Configure an error handler on the AIS.
  3. Test the solution.

The rest of this article will walk you through those steps in detail.


Step 1. Create an SCA module and library in Integration Designer

  1. Create a module called ApparelStore, which is dependent on the ApparelStoreLibrary library, as shown in Figure 3.
    Figure 3. SCA module and library
    SCA module and library
  2. In the ApparelStoreLibrary, create a Customer business object to store business data, as shown in Figure 4.
    Figure 4. Customer business object
    Customer business object
  3. In the ApparelStoreLibrary, create a FaultMessage business object that contains fault-related data, as shown in Figure 5.
    Figure 5. FaultMessage business object
    FaultMessage business object
  4. In ApparelStoreLibrary, create an interface ApparelStoreService with the request/response two-way operation checkVoucherValidity, as shown in Figure 6.
    Figure 6. ApparelStoreService interface
    ApparelStoreService interface
  5. Create a BPEL process VoucherValidityCheckBPEL with the activities shown in Figure 7, as follows:
    Figure 7. A BPEL process
    A BPEL process
    • Create an Assign activity, as shown in Figure 8, to assign the InputCustomer variable to the OutputCustomer variables. These variables are automatically created when you implement a BPEL process and assign an interface to it.
      Figure 8. Assign activity in a BPEL process
      Assign activity in a BPEL process
    • Create CheckValidity Java™ snippet to validate the voucher and enter the following code. This logic may be more complex in real-world scenarios, but for the purpose of this article we kept it simple.
      If(InputCustomer.getString("VoucherNumber").equals("111222")){
      OutputCustomer.setString("Valid", "No");
      }
      If(InputCustomer.getString("VoucherNumber").equals("333444")){
      OutputCustomer.setString("Valid", "Yes");
      }
    • Create a VoucherValid? choice structure. This choice structure returns true if the Valid property of the OutputCustomer business object is Yes, otherwise it returns false. If the Valid field of the OutputCustomer business object is Yes, the BPEL process sends the Normal reply and returns the OutputCustomer business object. Configure the Normal Reply activity as shown in the Figure 9.
      Figure 9. Reply normal
      Reply normal
    • If the Valid field of the OutputCustomer business object is No, the BPEL process sends the Fault reply and returns the OutputCustomer business object. Before sending the fault reply, the fault message business object needs to assigned. Assign the FaultMessage business object as shown in Figure 10.
      Figure 10. Assign fault
      Assign fault
    • Configure the Fault Reply activity as shown in Figure 11.
      Figure 11. Reply fault
      Reply fault
  6. Expose the BPEL as an SCA service. Note that for the SCA module to be used as an AIS in the process application, the export binding type must be SCA. When you create an export for any SCA implementation, make sure the export type selected is SCA Binding so the module is available as an AIS.
    Figure 12. SCA binding export
    SCA binding export

Step 2. Associate the SCA module with a process application in Integration Designer

  1. In Integration Designer, open the Process Center perspective, and click Open in workspace beside the process application to which you want to associate the SCA service. For this article, that is ApparelStoreProcessAPP,as shown in Figure 13.
    Figure 13. Process application
    Process application
  2. In the Open Process Applications or Toolkits in the Workspace dialog, leave the defaults and click OK.
  3. Associate the SCA service and the dependent library with the process application and click Next, then Finish, as shown in Figure 14.
    Figure 14. Associate SCA projects with the process application
    Associate SCA projects with the process application
  4. Mirror the ApparelStoreLibrary library module, as shown in Figure 15. In this scenario, the SCA module ApparelStore is dependent on ApparelStoreLibrary. The ApparelStore SCA module uses the interface and business object definitions contained in ApparelStoreLibrary. In order for the interface and business object definitions to be available to the process application or toolkit that contains the AIS, the library must be mirrored.
    Figure 15. Enable library mirroring
    Enable library mirroring
  5. Make the operations of the SCA export binding interface visible to Process Designer, as shown in Figure 16. With this step, every operation defined on the interface of the export becomes visible in the Process Designer when an AIS is generated in the process application.
    Figure 16. Make interface operations visible
    Make interface operations visible
  6. Publish changes to the Process Center repository by right-clicking the process application module and selecting Refresh and Publish, as shown in Figure 17. The contents of the process application, including the SCA module and library, are published to the Process Center repository. This publishing process generates an AIS in the process application for every operation defined on the interface of the export that is defined as visible to the Process Designer.
    Figure 17. Publish to Process Center repository
    Publish to Process Center repository

Step 3. Create a BPD containing AIS in Process Designer

In this step, you build a complete BPD with various activities, including Advanced Integration Services. The completed BPD should like Figure 18.

Figure 18. Complete business process definition diagram
Complete business process definition diagram
  1. Create an OrderBO business object, as shown in Figure 19. This business object holds the purchase data entered by the billing person.
    Figure 19. Create a business object in Process Designer
    Create a business object in Process Designer
  2. In ApparelStoreBPD, create the following variables, as shown in Figure 20.
    • Add the input variable CustomerInputVariable with a variable type of OrderBO.
    • Add an output variable CustomerOutputVariable with a variable type of OrderBO.
    • Add two private variables, one called AISFault with a varibable type of FaultMessage, the other called AISDataVariable with a variable type of Customer.
    Figure 20. Create variables in Process Designer
    Create variables in Process Designer
  3. Create an Enter Billing Information human service, as shown in Figure 21.
    Figure 21. Create a human service
    Create a human service
  4. Create the following input and output variables for the Coach, as shown in Figure 22:
    • Add an input variable called OrderInput with a variable type of OrderBO.
    • Add an output variable called OrderOutput with a variable type of OrderBO.
    Figure 22. Create the variables for the human service
    Create the variables for the human service
  5. Create the Enter billing information Coach in the Enter Billing Information human service, as shown in Figure 23. When you drag and drop the input variable to the Coach design area, it automatically creates all the labels and the fields. This way the fields are automatically bound to the input variable fields.
    Figure 23. Create the Coach to enter order data
    Create the Coach to enter order data
  6. Create the IntializeOutput server script as shown in the following listing. This script initializes the output variable and assigns the variable with the date that has been inputted by the billing person.
    tw.local.OrderOutput = new tw.object.OrderBO()
    tw.local.OrderOutput = tw.local.OrderInput
  7. In the BPD, configure the Data Mapping of the Enter Billing Information human service, as shown in Figure 24.
    Figure 24. Data mapping for the human service activity
    Data mapping for the human service activity
  8. In the BPD, create the Exclusive Gateway PaymentMode? to route the data token to the corresponding service on the basis of mode of payment, as shown in Figures 25 and 26. If the payment mode entered by the billing person is voucher, the gateway routes to the voucher validity AIS service. If the payment mode is credit card, the data token goes directly to the next activity, which is the process payment service.
    Figure 25. Create a decision gateway
    Create a decision gateway
    Figure 26. Create a decision gateway implementation
    Create a decision gateway implementation
  9. Since you configured the SCA module to be available as AIS in the previous step, it is now available. Create an activity CheckVoucherValidityAIS in a System swimlane and select the ApparelStoreService AIS as the implementation of this activity, as shown in Figures 27 and 28.
    Figure 27. Create an AIS
    Create an AIS
    Figure 28. Select an AIS
    Select an AIS
  10. Create the Data Mapping of the AIS activity as shown in Figure 29.
    Figure 29. Data mapping for the AIS service
    Data mapping for the AIS service
  11. Create the Pre & Post assignments for the AIS activity to initialize and assign the AIS-specific business object (AISDataVariable), as shown in Figure 30.
    Figure 30. Pre & Post assignments for the AIS service
    Pre & Post assignments for the AIS service
  12. Create another human service ProcessPayment in a Participant swimlane and set the implementation to User Task, as shown in Figure 31. For the purpose of this article, this service does not contain any complex logic, it is used just to display that the payment mode selected by the billing person is valid and now the system is processing the payment. The process terminates after this activity.
    Figure 31. ProcessPayment activity
    ProcessPayment activity
  13. Implement the ProcessPayment human service, as shown in Figure 32.
    Figure 32. ProcessPayment human service
    ProcessPayment human service
  14. Create the ProcessPayment Coach as shown in Figure 32, which is used to display the message that the payment mode selected is valid and the system is processing the payment.
    Figure 33. ProcessPayment Coach
    ProcessPayment Coach

Step 4. Configure the error handler on the AIS in Process Designer

  1. In the BPD, select the AIS activity and attach an error intermediate event to the boundary of the CheckVoucherValidityAISactivity by selecting the intermediate event icon from the palette and dropping it on the boundary of the AIS activity, as shown in Figure 34.
    Figure 34. Attach an error intermediate event to the AIS
    Attach an error intermediate event to the AIS
  2. Select the Intermediate Event on the activity and open the Properties tab to define the error behavior for the events. In the Error Properties section, select Catch Specific Errors, as shown in Figure 35.
    Figure 35. Configure error intermediate event to catch faults
    Configure error intermediate event to catch faults
  3. To filter the errors that are caught, select the faultMessage error code from the error code list, as shown in Figure 36.
    Figure 36. Select the error code
    Select the error code
  4. Select an Error Mapping variable that was previously defined on the Variables tab to map the error data into a variable, as shown in Figure 37. When you configure to catch specific errors, you can select the error code, map the error data, or both.
    Figure 37. Configure error mapping
    Configure error mapping
  5. The complete configuration of the error intermediate event is shown in Figure 38.
    Figure 38. Completed error event configuration
    Completed error event configuration
  6. Create a post assignment to the error intermediate event by selecting the Error Intermediate Event icon and clicking Pre & Post in the Properties dialog, as shown in Figure 39. This assigns the input variable of the Enter Billing Information human service. This step is to retain the data that has already been filled in by the billing person when the order data is first captured in the system, so that he or she does not need to enter the purchase details again.
    Figure 39. Configure post assignment on intermediate event
    Configure post assignment on intermediate event
  7. In the BPD, create the Invalid Voucher human service in the Participant lane to display the cause of failure to the billing person, as shown in Figure 40.
    Figure 40. Create a human service to display fault message
    Create a human service to display fault message
  8. Create a Coach input variable called FaultMessage with a variable type of String, as shown in Figure 42.
    Figure 42. Create variables for the Coach
    Create variables for the Coach
  9. Create a Coach, as shown in Figure 43, to display the fault message returned by the AIS service. The control type is Output Text and the control is bound to the FaultMessage input variable, so the fault message returned from the AIS is displayed in this control.
    Figure 43. Create a Coach to show the fault message
    Create a Coach to show the fault message
  10. In the BPD, create the data mapping for this human service as shown in Figure 44. Only the input mapping is needed.
    Figure 44. Data mapping for the InvalidVoucher human service
    Data mapping for the InvalidVoucher human service
  11. Connect the complete BPD process as shown in Figure 45.
    Figure 45. Completed BPD process
    Completed BPD process

Step 5. Test the solution in Process Designer

To test the solution, you'll use the playback feature of the Process Designer.

  1. Click the Run Process icon, as shown in Figure 46, then click Yes to switch to the Inspector view.
    Figure 46. Run the BPD process
    Run the BPD process
  2. The token is currently at the first human service activity and waiting for the billing person to enter purchase details, as shown in Figure 47.
    Figure 47. Token waiting at the first human service
    Token waiting at the first human service
  3. Select the process instance and click the Run icon, as shown in Figure 48.
    Figure 48. Run the task
    Run the task
  4. Click OK to select the user to start the task.
  5. When the browser window opens, enter the following data, as shown in Figure 49:
    • Customer Name = Peter
    • Number Of Items = 5
    • Payment Mode = Voucher
    • Voucher Or Credit Card Number = 111222
    Note that the voucher number entered is the invalid number. Click OK.
    Figure 49. Enter purchase order details
    Enter purchase order details
  6. This takes you back to the Inspector view. Keep clicking the Refresh button for the instance until you see the token waiting at the Invalid Voucher human service, as shown in Figure 50.
    Figure 50. Token waiting at InvalidVoucher human service
    Token waiting at InvalidVoucher human service
  7. Select the Invalid Voucher human service and run the task again.
  8. The browser window displays the fault message that is thrown by the AIS service and caught by the error intermediate event, as shown in Figure 51. Click OK.
    Figure 51. Invalid voucher fault message shown to the billing person
    Invalid voucher fault message shown to the billing person
  9. Back in the Inspector window keep clicking refresh until you see the token again waiting at the Enter Billing Information human service.
    Figure 52. Token waiting at the billing person to provide the valid voucher number
    Token waiting at the billing person to provide the valid voucher number
  10. Click on the Enter Billing Information human service and run the task. The browser displays the purchase order, as shown in Figure 53. Change the valid voucher number and click OK.
    Figure 53. Change invalid voucher number
    Change invalid voucher number
  11. You are returned to the Inspector view. Keep clicking the Refresh button for the instance until you see the token waiting at the ProcessPayment human service, as shown in Figure 54.
    Figure 54. Token waiting at the ProcessPayment human service
    Token waiting at the ProcessPayment human service
  12. Select the ProcessPayment human service and run the task again. The browser window opens to display the message that the payment chosen is valid and the system is processing the payment, as shown in Figure 55. Click OK.
    Figure 55. Valid voucher message displayed
    Valid voucher message displayed
  13. Because the voucher number is valid, the process terminates and all task instances are complete, as shown in Figure 56.
    Figure 56. Completed task instances
    Completed task instances
  14. You can run another test in which you select Credit Card as the payment mode. In this test, the flow does not route to the AIS Voucher Validity path, but instead goes directly to the ProcessPayment service and the process terminates. To test this, select Credit Card from the drop-down menu in the Enter Billing Information human service, as shown in Figure 57.
    Figure 57. Change the payment mode
    Change the payment mode

Conclusion

This article described how to configure error handling on Advanced Integration Services in IBM Business Process Manager Advanced V8, and showed you how to enable an SCA service to be used as an AIS in IBM Process Designer.


Acknowledgements

The author would like to thank Ashok Iyenger, Norman Seto and Sharad Chandra for their review of this article.


Downloads

DescriptionNameSize
SCA module project interchange fileApparelStorePI.zip62KB
Process application twx fileApparelStoreProcessAPP.twx915KB

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=840609
ArticleTitle=Configuring error handling for Advanced Integration Services in IBM Business Process Manager Advanced V8
publish-date=10192012