Transactionally integrate Web services with BPEL processes in WebSphere Process Server

Learn how easy it is to integrate Web services transactionally using Web Services Atomic Transaction for WebSphere® Application Server and WebSphere Process Server Version 6.0.2.

Share:

Peter Y. Xu (peteryxu@us.ibm.com), Consulting I/T Specialist, EMC

Peter Xu is a Consulting I/T Specialist with the IBM Software Services for WebSphere group. Consultants with Software Services for WebSphere help customers deploy IBM products into their organizations. Peter provides consulting services, education, and mentoring on J2EE technologies, and specifically WebSphere and Rational products to Fortune 500 clients.


developerWorks Contributing author
        level

07 March 2007

Overview

Companies have been adopting Web services technologies for several years, but Web services are primarily used for information retrieval. If the Web services are doing transactional work, such as updating or inserting data, they are most likely used in a standalone fashion.

At the same time, new business integration technologies, such as Business Process Execution Language (hereafter called BPEL), have emerged to help with implementing complex business processes. At first glance, Web services seems ideal for BPEL integration, since BPEL specifies its partners using WSDL descriptions. But in the early days of BPEL implementation, use of Web services to invoke BPEL activities was not widespread. Why? Because Web services could not participate in the global transaction initiated at the BPEL process level. BPEL-based process integration has forced the issue of transactional integrity in Web services.

However, things have changed with the arrival of Web Services Atomic Transaction for WebSphere Application Server (hereafter called WS-AT).

Overview of WS-AT

WS-AT is a standard and technology that provides transactional support for Web services. It allows distributed Web Service applications, and the resources they use, to take part in distributed global transactions.

A transaction is a set of operations that must be executed as a single unit, which is often called a logical unit of work. A transaction is either completed in its entirety or not at all; that is, it is indivisible or atomic. Transactions (and transaction-capable application servers) have been around a long time and are a critical part of most tiered distributed applications, whether constructed with Java™ 2 Platform, Enterprise Edition (J2EE) or with other transactions.

In early transactional systems, such as the support in relational databases, transactions affected only data in the database itself, and the transaction's scope was restricted to that database server. However, an application server such as WebSphere Application Server can support a transaction that applies to several databases or other entities, such as message queue managers, that maintain persistent data. (In fact, the J2EE Connector Architecture (JCA) allows propagations of transaction context to transactionally capable legacy systems.) As a result, WebSphere Application Server supports two-phase commits for distributed transactions. A two-phase commit allows several cooperating entities, known as resource managers, to participate in a single distributed unit of work coordinated by a transaction coordinator. WebSphere is typically the coordinator, and the various databases, queue managers, legacy systems, and other entities are the resource managers.

To be part of a distributed transaction, a resource manager must support the XA standard, which governs the propagation of transaction contexts. WebSphere and many other products are XA-capable, and this technology has been in use in WebSphere Application Server for many years. However, until the advent of WS-AT, transactions have always been propagated either via J2EE transaction contexts (significant only to WebSphere and other J2EE-based containers) or XA (which typically relies on the resource manager vendor's adapter or client code), and which is often difficult to interoperate.

In J2EE, support for transactions is implemented as the Java Transaction API, or JTA. The API itself is usually invisible to programmers, as the scope of transactions is delineated by declarative data found in deployment descriptors. JTA is part of the J2EE specifications.

WS-AT for WebSphere Application Server uses the standard JTA support in the J2EE programming model to scope transactions. JTA transactions are interpreted by WS-AT in the WebSphere Application Server runtime environment and are encoded into CoordinationContexts, such that a WS-AT representation of the current JTA transaction is made to flow in Web service application requests.

If the system hosting the target Web Services endpoint is also WS-AT capable, it automatically establishes a JTA transaction in the target's runtime environment, which becomes the transactional context under which the target Web service application will run. When the Web service request enters the target server, WS-COOR is used to register for participation in a two-phase commit coordinated by the originator of the transaction context. The two-phase commit protocol is driven by the caller's WS-AT coordinator when it is ready to commit the transaction.

If a JTA transaction is active on the thread when a Web service application request is made, the transaction is propagated across on the SOAP/HTTP request and established in the target's environment. This is analogous to the distribution of transaction context over IIOP as described in the EJB specification. Any transactional work performed in the target environment becomes part of the same global transaction. Figure 1 shows how this operates:

Figure 1. Sharing transaction context
Figure 1. Sharing transaction context

From a development perspective, no specific development tasks required for taking advantage of WS-AT for Web services other than specifying it in the deployment descriptors, which we'll describe later. No explicit registration of participants is required by the application developer. The WebSphere Application Server runtime environment takes responsibility for the registration of WS-AT participants, in the same way as it does the registration of XAResources in the JTA transaction to which the WS-AT transaction is federated. When the transaction is completed, all XAResources and WS-AT participants are atomically coordinated by the WebSphere Application Server transaction manager.

The scenario

In order to show WS-AT in action, we'll use a scenario involving a corporate human resource department. In the example, we'll register and enroll a new employee into different existing systems, such as a payroll system, an employee registry, and a service to validate the employee’s social security number.

Let's assume that you're the integration developer charged with implementing this HR process. You're told there is a Web service available to add an employee to the registry, and you're responsible for writing the two other services. You're also informed that the three services are to be completed in a single unit of work, and need to all succeed or, if not, to roll back.

Where do you start? Well, you're choreographing a set of services into a business process, so BPEL seems like a good candidate for the process implementation. You decide to use a microflow process to scope the unit of work. The payroll service and social security number check will be implemented and deployed in the same WebSphere Process Server as the BPEL process. The only remaining problem is how to integrate the employee registry Web service running in a different server. You'd like that service to participate in the global transaction started by the BPEL process.

After talking with the employee registry Web service provider department, you know that the service is running inside a WebSphere Enterprise Service Bus server (hereafter called the ESB server). Since WebSphere ESB is built on top of WebSphere Application Server Version 6.0, which implements WS-AT, you're now more confident that you can use this Web service in a transactional way, in other words, that it can be reliably rolled back in case of failure inside the BPEL process.

When deployed, your solution architecture will look like Figure 2:

Figure 2. HR process solution
Figure 2. HR process solution

Implementing the BPEL process

In this section, we'll describe how to implement the BPEL process for the scenario.

Assembly

As you can see in the assembly diagram in Figure 3, we have a BPEL process HRProcess, which is wired to a Web service import binding EmpRegistryImport. If you select the Binding tab on the left, you'll see in the Address field that the employee service is deployed at a local server, accessible through port 9081, which turns out to be the WebSphere ESB Server.

Figure 3. HR module diagram
Figure 3. HR module diagram

Web service

The Web service we're using is very straightforward. It takes an employee object, and inserts a record, or row, into a DB2® database, as shown in Figure 4.

Figure 4. Employee service implementation
Figure 4. Employee service implementation

Note that for the DataSource lookup, we use jdbc/Sample, which is defined as WebSphere Server JDBC resources. Make sure this is created as an XA datasource. Failure to do this will break WS-AT.

BPEL process

Figure 5 shows the HR BPEL process that invokes the EmployeeRegistry Web service:

Figure 5. BPEL diagram
Figure 5. BPEL diagram

To keep the scenario simple, the payroll service and SSN checking service implementation have been stubbed out. However, to emulate failure in BPEL, we're raising fault on a certain condition inside the checkSSN snippet, which is executed after the Web service call. Since the fault is not handled inside the BPEL process, it will result in the global transaction rollback, consequently undoing what the EmployeeRegistry Web service has done. If you look at the checkSSN code in Figure 6 you can see that we're purposely generating fault if the empNO starts with character C.

Figure 6. Raising fault
Figure 6. Raising fault

Test cases

We'll test the EmployeeRegistry Web service first, then exercise the BPEL process in a successful scenario. Last but not the least, we'll test the BPEL process in a failing situation to make sure WS-AT works as expected.

We'll use the following data for test purposes:

EmpNoFirstNameMILastNameEdLevel
Web Service Test 1234 Peter Y Xu 10
BPEL Success 1235 Sammy P Xu 7
BPEL Failure C1235 Mike T Sminoff 10

Run and test the sample

Before using the sample code, you must do the following:

  1. Install DB2 Version 8 or Version 9.
  2. Create a Sample database.
  3. Define an XA data source with a JNDI name of jdbc/Sample in the WebSphere ESB server.

Import the sample code

To import the projects into WebSphere Integration Developer, complete the following steps:

  1. Download the zip file from the Downloads section to a temporary directory.
  2. In WebSphere Integration Developer, select File > Import.
  3. On the Select page of the Import Wizard, select Project interchange as the import source, and click Next.
  4. On the Import Projects page, in the From zip file field, specify the zip file downloaded in the first step, then click Select All to select all projects, as shown in Figure 7:
    Figure 7. Import projects
    Figure 7. Import projects
  5. Click Finish. You'll see the imported projects in the Physical Resources view of the workspace, as shown in Figure 8:
    Figure 8. Imported projects
    Figure 8. Imported projects

Test the sample Web service application

Before starting, make sure you have created the data source jdbc/Sample in WebSphere ESB server.

  1. Start WebSphere ESB Server v6.0.
  2. Right-click WESB server, and select Add and remove project.
  3. Select EmployeeHR from the Available projects list and click Add to add it to the Configured projects, then click Finish, as shown in Figure 9, and wait for the publication of the project to finish.
    Figure 9. Add employee application
    Figure 9. Add employee application
  4. Navigate to the EmployeeService.wsdl in the Physical Resources view, as shown in Figure 10:
    Figure 10. Locate the WSDL
    Figure 10. Locate the WSDL
  5. Right-click EmployeeService.wsdl file, then select Web Services => Test with Web Services Explorer, as shown in Figure 11:
    Figure 11. Start Web Service Explorer
    Figure 11. Start Web Service Explorer
  6. From the window that opens, select addEmployee from the Navigator list.
  7. Enter some sample data in the forms as shown below, then click Go, as shown in Figure 12:
    Figure 12. Test the Web service
    Figure 12. Test the Web service
  8. If all goes smoothly, this Web Services call will create a new row in the Employee table in the SAMPLE DB2 database. You can verify this by opening the IBM DB2 Control Center utility, as shown in Figure 13:
    Figure 13. A new employee row
    Figure 13. A new employee row

Test the BPEL process in a successful scenario

To test the BPEL process in a successful scenario:

  1. Right-click WebSphere Process Server v6.0, and select Add and remove project.
  2. Select EmployeeHR from the Available projects list, and click Add to add it to the Configured projects, then click Finish, as shown in Figure 14:
    Figure 14. Add BPEL application to WebSphere Process Server
    Figure 14. Add BPEL application to WebSphere Process Server
  3. Open the Assembly Diagram of HRProcessModule, then right-click HRProcess and select Test Component.
  4. In the Test window shown in Figure 15, remove EmpRegistryImport from the emulator in the Configuration tab, then enter the values as shown, and click Continue.
    Figure 15. Test BPEL success
    Figure 15. Test BPEL success
  5. If everything goes well, you should see the following output in the server console:
    Figure 16. Console output
    Figure 16. Console output
  6. If you look at the EMPLOYEE table in the DB2 database, you'll see that a new row is inserted, as shown in Figure 17:
    Figure 17. New record in DB2 table
    Figure 17. New record in DB2 table

Test the BPEL process in a failing scenario

  1. Return to the Test window and enter the data as shown in Figure 18. Notice that a value of C1235 for empID will cause the BPEL fail, as described earlier.
    Figure 18. Test BPEL failure
    Figure 18. Test BPEL failure
  2. Click Continue and wait for the call to finish. You should see the following errors:
    Figure 19. BPEL failed
    Figure 19. BPEL failed
  3. From the message above, we know that the CheckSSN activity raised a fault, which results in an SCA ServiceRuntimeException and causes the global transaction rollback. But what happened to the Web service call before the CheckSSN activity? That EmployRegistry call was supposed to insert a new row in the employee table. Let's open the employee table again and take a look:
    Figure 20. No new record inserted
    Figure 20. No new record inserted
  4. As you can see, there is no row with C1235 in the table. Apparently, the update made by the Web service call has been rolled back, which is what we expected.

WS-AT configuration

As discussed earlier in the article, there is no additional programming effort to use WS-AT, but some configuration may be required.

To enable WS-AT, the deployment descriptors for Web and EJB modules must be configured as follows:

  • In a Web module that invokes a Web service, specify Send Web Services Atomic Transaction on requests to propagate the transaction to the target Web service.
  • In a Web module that implements a Web service, specify Execute using Web Services Atomic Transaction on incoming requests to run under a received client transaction context.
  • In an EJB module that invokes a Web service, specify Use Web Services Atomic Transaction to propagate the EJB transaction to the target Web service.
  • In an EJB module, specify bean methods with transaction type Required (the default) to participate in a global atomic transaction.

Fortunately, if you use the Rational® Application Developer or WebSphere Integration Developer to develop Web services and BPEL processes, these configurations are set by default, so you even don't need to manually change them.

Now, let's look at the configuration for the sample application. Navigate to the deployment descriptor for the generated EJB project of the HRProcess module, ejb-jar.xml, and double-click to open it, as shown in Figure 21:

Figure 21. EJB deployment descriptor
Figure 21. EJB deployment descriptor

On the Bean tab, select Module on the left, and you'll see that Use Web Services Atomic Transaction is checked in the Global Transaction section, as shown in Figure 22:

Figure 22. EJB deployment descriptor WS-AT
Figure 22. EJB deployment descriptor WS-AT

Now, let's look at the configuration on the Web service side. Open the Web deployment descriptor and find the servlet for EmployeeService on the left. Again, you'll see that Execute using Web Services Atomic Transactions on incoming requests is checked in the Global Transaction section, as shown in Figure 23:

Figure 23. Execute WS-AT on incoming request
Figure 23. Execute WS-AT on incoming request

If you're really curious and want to see what's exchanged over the wire when using WS-AT, you can enable the TCP Monitor feature of WebSphere Integration Developer, to view the SOAP message flow with WS-AT headers, as shown in Figure 24. Details on how to do this are outside the scope of this article.

Figure 24. SOAP message with WS-AT
Figure 24. SOAP message with WS-AT

Summary

As you've seen in this article, transactionally integrating Web services with BPEL processes is effortless for developers, thanks to the tools support. As Web services transaction technologies mature, you'll see more and more Web services integration in complex and mission-critical systems and transactional business processes.

Acknowledgment

The author wants to thank Robert Drelles for his thorough review of this article.


Download

DescriptionNameSize
Sample project interchange fileIntegrateWS_PI.zip1KB

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Business process management
ArticleID=200097
ArticleTitle=Transactionally integrate Web services with BPEL processes in WebSphere Process Server
publish-date=03072007