Implementing web services transactions in WebSphere Process Server V7

Learn how to implement a Web Services Atomic Transaction scenario with a business process and external web service

This tutorial provides instructions to implement a transaction between an IBM® WebSphere® Process Server V7 business process and an external web service running on WebSphere Application Server V7. The tutorial will provide steps to be carried out in IBM WebSphere Integration Developer V7 while developing the business process module and the web service, followed by instructions to configure WebSphere Process Server and WebSphere Application Server to enable Web Services Atomic Transaction. The latter part demonstrates the transaction commit and rollback scenarios to complete the tutorial.

Share:

Rajiv Madassery (rajiv.madassery@in.ibm.com), Principal Software Engineer, IBM

Author photo of Rajiv MadasseryRajiv Madassery is a Principal Software Engineer at IBM and works for the WebSphere Process Server Level 2 Support Team. Rajiv came to IBM in 2003 and has worked with the WebSphere Business Integration Adapters Functional Verification Test team and WebSphere Application Server Level 2 Support team. Rajiv is a developerWorks Contributing Author in the WebSphere Process Server space.



24 November 2010

Also available in Chinese

Introduction

Web Services Atomic Transaction (WS-AT) support in WebSphere Application Server (hereafter called Application Server) enabled web services applications to participate in transactions. With this support, business process applications running in WebSphere Process Server (hereafter called Process Server) can participate in distributed transactions.

To learn more about the web services transaction support, see the Information Center.

In this tutorial

This tutorial provides an illustration of WS-AT based distributed transaction between a business process running on WebSphere Process Server and a Java™ API for XML web services (JAX-WS) based service, residing on an external WebSphere Application Server. The tutorial is follow-on to a previous article, Transactionally integrate Web services with BPEL processes in WebSphere Process Server. That article is intended for Version 6.0.2 of WebSphere Process Server. The focus of this article will be on WS-AT configuration in Version 7.0.

There are two applications developed in the tutorial, a business process application called “ABCBPEL”, which contains a business process and a web services import, and a web service application called “ABCService”, as shown in Figure 1. The business process component in ABCBPEL module invokes the web service in ABCService. ABCService receives a parameter from the business process and uses it as data to insert a row into the database. The business process also has a snippet component, which you can use to raise a fault and to demonstrate a global transaction rollback.

A sample Project Interchange file, WS-ATProjectInterchange.zip, is provided for you to download with this tutorial.

Figure 1. WS-AT context
WS-AT context

The tutorial is divided into the following sections:

Prerequisites

You will need:

  • Previous development experience in WebSphere Integration Developer.
  • Knowledge of basic administration of WebSphere Process Server and WebSphere Application Server.

System requirements

  • Microsoft® Windows® XP Professional Desktop with at least 2 GB of RAM
  • IBM WebSphere Integration Developer V7.0.0.2 with WebSphere Process Server Test Environment V7.0.0.2, WebSphere Application Server V7.0.0.9
  • Database server, such as IBM DB2® Express

Duration

Approximately 1 to 2 hours


Preparing the application development setup

To establish WS-AT in the participating applications, you need to attach the WS-Transaction application policy set to both the web service provider and web service client applications. Policy sets simplify the configuration of policies as enforced by the quality of service. The WS-Transaction policy set enables WS-AT when it is attached to the applications. For more information, see the Information Center topic, Web services policy sets.

The WS-Transaction policy set is provided by default. The first step before developing the applications is to get a copy of the policy set exported from the application server. We will use this policy set copy to attach it to the applications while developing the applications, and after deployment, to the respective application servers.

Exporting the WS-Transaction policy set

In one of the applications servers used in the scenario, perform the following steps to export the WS-Transaction policy set:

  1. From the administrative console, navigate to Services > Policy sets > Application policy sets or Services > Policy sets > System policy sets > Application policy sets, as shown in Figure 2.
    Figure 2. Application policy sets
    Application policy sets
  2. From the Application policy sets panel, select and export WS-Transaction. By default, the WS-Transaction policy set is not displayed. Use the New… button to add the WS-Transaction policy set to the default list. See Figure 3.
    Figure 3. Adding the WS-Transaction policy set
    Adding the WS-Transaction policy set
  3. Select the WS-Transaction policy set and click the Export… button.
  4. In the Export policy set archive file page, locate the policy set archive file and click to download the file as shown in Figure 4.
    Figure 4. Export the policy set
    Export the policy set
  5. Select File > Import > Web services > WebSphere Policy Sets (Figure 5) to import the policy set to WebSphere Integration Developer (hereafter called Integration Developer).
    Figure 5. Importing policy sets
    Importing policy sets
  6. Import the archive file to Integration Developer.
  7. You will need to restart Integration Developer to read the policy set.

Developing the web service application

The web service application will receive a string parameter from the business process and will subsequently issue an insert statement to the database table.

In this section, the steps required to develop the ABCService web service application are:

  1. Create a new application in Integration Developer by selecting Import > New > Java EE > Enterprise Application Project and name it ABCService.
  2. Add a new Java class to the application and name it ABCService. See Figure 6.
    Figure 6. ABCService application in the workspace
    ABCService application in the workspace
  3. Paste the code in Listing 1 to ABCService.java.
    Listing 1. ABCService.java
    package com.ibm.test;
    import java.sql.Connection;
    import java.sql.Statement;
    import javax.naming.InitialContext;
    import javax.sql.DataSource;
    
    publicclass ABCService {
    	public String callServ(String inputString)
    	{
    	System.out.println("This is ABC Web Service!");
    	try
    	{
    	 InitialContext ic = new InitialContext();
    	 DataSource ds = (DataSource) ic.lookup("jdbc/ABCDB");
    	 Connection conn = ds.getConnection("db2admin","db2admin");
    
    	 Statement st = conn.createStatement();
    	 String mySQL = "insert into administrator.employee (empno) 
             values('"+inputString+"')";
    	 System.out.println("The query is " + mySQL);
    	 st.executeUpdate(mySQL);
    	  return "OK";
    	}
    	 catch (Exception e)
    	{
    	 e.printStackTrace();
    	 return "Error";
    	 }
    	}
    }
  4. Note that to make changes to the above code, adjust the SQL connection properties and the SQL insert statement as needed for your database setup.
  5. Save the changes.
  6. Right-click on the ABCService application and navigate to Properties > Service Policies. Check Enable project specific settings as shown in Figure 7.
    Figure 7. Service policy settings
    Service policy settings
  7. In WebSphere Policy Sets > WebSphere v7.0 Policy Sets, select WSTransaction and check Set as default as shown in Figure 8.
    Figure 8. Setting default policy
    Setting default policy
  8. Save the changes.
  9. Right-click on ABCService.java and select Web Services > Create Web service as shown in Figure 9.
    Figure 9. Create Web service
    Create Web service
  10. In the Web Services wizard, ensure that the web service runtime is IBM WebSphere JAX-WS as shown in Figure 10.
    Figure 10. Configuring JAX-WS
    Configuring JAX-WS
  11. Choose to generate the WSDL as shown in Figure 11.
    Figure 11. Generating WSDL into the web service project
    Generating WSDL into the web service project
  12. Complete the rest of the steps in the wizard to generate the web service.
  13. Save the changes to the application.

Developing the business process application

To develop the ABCBPEL business process application:

  1. Launch Integration Developer and open the Business Integration perspective.
  2. Right-click on the Projects panel and select New > Project > Module.
  3. Enter the module name as ABCBPEL, as shown in Figure 12, and click Finish.
    Figure 12. ABCBPEL module in the workspace
    ABCBPEL module in the workspace

Developing the web service import

  1. From the Components panel in the Integration Developer palette, drag an Import component to the assembly diagram. Name it Import1.
  2. Copy ABCServiceService.wsdl and ABCServiceService_schema1.xsd from the ABCService module to ABCBPEL, and ensure that the ABCServiceDelegate interface is listed under “Interfaces”, as shown in Figure 13.
    Figure 13. Copy the WSDL from web service to BPEL module
    Copy the WSDL from web service to BPEL module
  3. Add ABCServiceDelegate as the interface for Import1.
  4. Right-click on Import1 and select Generate Bindings > Web Service Binding as shown in Figure 14.
    Figure 14. Generating web service binding for import
    Generating web service binding for import
  5. In the Binding wizard, select Use an existing web service port.
  6. In the next window, select ABCServicePort under “Matching service ports”, as shown in Figure 15.
    Figure 15. Selecting the web service port
    Selecting the web service port
  7. In the Select a Transport Protocol window, choose the default, SOAP 1.1/HTTP.
  8. Click Finish and then click OK.
  9. In Properties > Binding, ensure that the hostname and port are specified correctly in the Address field.
  10. In Properties > Binding > Policy Sets, select Default policy set to WSTransaction, as shown in Figure 16.
    Figure 16. Setting the WSTransaction policy set to Import
    Setting the WSTransaction policy set to Import

Developing the business process

  1. From the Components panel in the Integration Developer palette, drag a Process component to the assembly diagram. Name it Component1.
  2. Use the Add Interface button in Component1 to open the Interface wizard and create a new interface called BPELInterface.
  3. Wire Component1 with Import1 and click OK at the message, prompting the reference partner creation as shown in Figure 17.
    Figure 17. Wiring import and BPEL process
    Wiring import and BPEL process
  4. Right-click on Component1 and click Generate Implementation.
  5. In the Properties > Details tab, change the Business process type to Microflow as shown in Figure 18.
    Figure 18. BPEL component is implemented as microflow
    BPEL component is implemented as microflow
  6. Add a Snippet from the palette after the Receive activity and name it Snippet.
  7. In Properties > Details, choose Java and add the code from Listing 2.
    Listing 2. Code for Snippet
    System.out.println("ABC BPEL");
  8. Create a variable in the Variables panel and name it input1, as shown in Figure 19.
    Figure 19. Create input1 variable in the BPEL
    Create input1 variable in the BPEL
  9. Add an Assign activity after Snippet and map input1 to parameters.arg0, as shown in Figure 20.
    Figure 20. Mapping input1 to web service parameter
    Mapping input1 to web service parameter
  10. Add an Invoke activity and configure the Properties > Details tab, as shown in Figure 21.
    Figure 21. Configuring Invoke activity in BPEL
    Configuring Invoke activity in BPEL
  11. Add another Snippet activity after Invoke and name it Snippet1.
  12. In the Properties > Details tab, choose Java and add the code from Listing 3.
    Listing 3. Code for Snippet1
    System.out.println("After invoke" + input1);
    if (input1.equalsIgnoreCase("fail"))
    {
    	System.out.println("Raise fault...");
    	raiseFault(new QName("http://test.ibm.com/ABCBPEL","Fault"));
    }
    System.out.println("Done BPEL!");
  13. Save Component1 and the assembly diagram.

Setting the transactional qualifiers in the application

Transactional qualifiers are one among the many quality of service qualifiers provided in Integration Developer. There are three qualifiers that are required to be set: Transaction at the Component1 implementation, Join Transaction at the Import1 reference, and Suspend Transaction at the Component1 interface. Remember that a microflow is a synchronous implementation and all the activities will execute in a single transaction.

The required transaction qualifiers for this tutorial are summarized in Table 1.

Table 1. Transaction qualifiers
QualifierLocationValueExplanation
Transaction Component1 Implementation Global Enables the business process and web service to participate in a single transaction context.
Suspend Transaction Component1 Reference False When the business process synchronously calls the web service, this qualifier specifies that the business process will propagate the transaction context to the web service (Import).
Join Transaction Import1 Interface True Enables the web service (Import) to join the transaction propagated by the business process.

To learn more about the transactional quality of service, see the Information Center topic, Quality of service qualifier reference.

In Integration Developer, set the transactional qualifiers as follows:

  1. Navigate to Component1, Properties > Implementation.
  2. Add Transaction quality of service.
  3. In the Value column, select Global from the list, as shown in Figure 22.
    Figure 22. Adding Transaction quality of service
    Adding Transaction quality of service
  4. Save the changes.
  5. Navigate to Component1, Properties > Details > References > ABCServiceDelegatePartner.
  6. Add the Suspend transaction quality of service.
  7. In the Value column, select False from the list, as shown in Figure 23.
    Figure 23. Suspend transaction quality of service
    Suspend transaction quality of service
  8. Save the changes.
  9. Navigate to Import1, Properties > Details > Interfaces > ABCServiceDelegate.
  10. Add the Join transaction quality of service.
  11. In the Value column, select True from the list, as shown in Figure 24.
    Figure 24. Join transaction quality of service
    Join transaction quality of service

Deploying the applications

The next step is to deploy the applications to the respective application servers. The ABCBPEL application is to be deployed to WebSphere Process Server and the ABCService application to the remote WebSphere Application Server.

Deploying the ABCBPEL application

  1. Right-click on the ABCBPEL module in Integration Developer and select Export > Java EE > EAR file.
  2. Export the module as ABCBPEL.ear for deployment.
  3. Start the Process Server integrated test server.
  4. Launch the administrative console.
  5. Deploy the application to the application server.
  6. Navigate to Services > Service clients and click on ABCServiceService (Figure 25).
  7. In the Policy set attachments panel, check ABCServiceService.
    Figure 25. Service clients
    Service clients
  8. Click Attach Client Policy Set > WSTransaction to attach the policy set to the application (Figure 26), if it is not already attached.
    Figure 26. Attaching WSTransactions Client Policy Set
    Attaching WSTransactions Client Policy Set
  9. Save the changes and restart the test server.

Deploy the ABCService application

  1. Right-click on the ABCService application and select Export > Java EE > EAR file.
  2. Export the application as ABCServiceApp.ear for deployment.
  3. Start WebSphere Application Server.
  4. Launch the administrative console.
  5. Deploy the application to the server.
  6. Navigate to Services > Service Providers and click on ABCServiceService, as shown in Figure 27.
    Figure 27. Service providers
    Service providers
  7. In the Policy set attachments panel, check ABCServiceService.
  8. Click Attach > WSTransaction to attach the policy set to the application, if it is not already attached.
    Figure 28. Attach the WSTransaction policy set to service
    Attach the WSTransaction policy set to service
  9. Save the changes and restart the application server.

Ensure that the applications have started successfully on both application servers.


Configuring the servers

Before running the application scenarios, additional configuration on the servers are required.

The web service application uses a data source to connect to the database. You will create a data source in the WebSphere Application Server.

  1. Create a new data source named ABCDB, scoped to the Cell, as shown in Figure 29.
    Figure 29. Data source properties
    Data source properties
  2. Ensure that the data source is XA enabled. For participating in the global transaction context, the data source is required to be XA enabled.
  3. Verify that the data source properties are set in compliance with the data source connection properties (Figure 30) set in ABCService.java.
    Figure 30. Datasource connection properties
    Datasource connection properties

If security is enabled at the application servers, additional configurations are required prior to running the applications:

  1. It is required to import the Light-weight Third Party Authentication (LTPA) tokens from Process Server to Application Server. The procedures to export and import the LTPA tokens are explained in detail in the Information Center.
  2. It is required to import the Secure Sockets Layer (SSL) certificates from Application Server and add it to the trust store in Process Server to avoid SSL handshake errors.

Testing the transactional behavior

You can now test the transactional behavior as all the required configurations are complete.

Scenario: Transaction commit

  1. Go to Integration Developer and open ABCBPEL module.
  2. Right-click on the Component1 in the assembly diagram and select Test Component.
  3. Navigate to Initial request parameters enter a value of success and invoke the request.
  4. The business process invokes the web service (Figure 31). The transaction context is propagated to the web service, but because of the transactional qualifiers set, the web service transaction will execute in the same context as the client transaction.
  5. The web service reads the input parameter and subsequently adds a row to the database. This database transaction will also run in the client context.
    Figure 31. Test Component run 1
    Test Component run 1
  6. Verify the database that the record is entered into the database table (Figure 32).
    Figure 32. Verifying the database table
    Verifying the database table
  7. The transaction will commit after calling Snippet1.

In this scenario, the transaction context is propagated from Process Server and the web service. The database transactions all participate in a global transaction context.

Scenario: Transaction rollback

  1. Go to Integration Developer and open the ABCBPEL module.
  2. Right-click on the Component1 in the assembly diagram and select Test Component.
  3. Navigate to Initial request parameters enter a value of fail and invoke the request.
  4. The business process invokes the web service.
  5. The web service reads the parameter and writes the record to the database.
  6. At this stage, the transaction is still active and Snippet1 is called.
  7. In Snippet1, the request parameter is checked and if it is “fail”, a BPEL fault will be raised.
  8. A ServiceRuntimeException is thrown in the business process and this triggers the global transaction rollback, as shown in Figure 33.
    Figure 33. Test component ends in ServiceRuntimeException
    Test component ends in ServiceRuntimeException
  9. Look in the database table and you will observe that the record is not committed to the database. There is no entry for “fail”.
    Figure 34. Verify the database after the exception
    Verify the database after the exception

In this scenario, the transaction rollback is initiated by ServiceRuntimeException raised in the business process. Since the transaction context is used by the web service and the database, the corresponding transactions at the web service and the database transaction are rolled back, thereby ensuring data integrity. ServiceRuntimeException itself is induced using a BPEL fault.


Conclusion

In this tutorial, you learned to set up a global transaction using business process and a web service using WS-AT. The web services policy sets in WebSphere Application Server facilitates web services transactions. Enabling WS-AT in applications is achieved with a few configuration steps as illustrated in the tutorial. There is no requirement for additional coding or application level configurations from the application developers.

Acknowlegement

The author wishes to acknowledge Skulrat Charoenphong from Technical Sales, IBM Thailand, for her help in reviewing this tutorial.


Download

DescriptionNameSize
Code sampleWS-ATProjectInterchange.zip37KB

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, SOA and web services
ArticleID=588498
ArticleTitle=Implementing web services transactions in WebSphere Process Server V7
publish-date=11242010