Developing a distributed WS-AT transaction using an IBM BPM Advanced Integration Service, Part 4: Implementing the Advanced Integration Service

Leveraging the capabilities of the Advanced Integration Services (AIS) in IBM Business Process Manager V8.0.1 Advanced, this series describes the implementation of a distributed WS-AT scenario involving two databases (Microsoft® SQL Server and IBM® DB2®) installed on two different machines and accessed via two web services. The implementation illustrates the automatic rollback capabilities offered by the SCA-based management in an AIS in collaboration with the WS-AT protocol. In Part 4, you'll learn how to implement the AIS for the transaction.

Carlo Randone (carlo_randone@it.ibm.com), Certified IT Architect , IBM

Carlo Randone photoCarlo Randone is a Certified IBM IT Architect and Open Group Master Certified IT Architect in IBM Global Business Services, Italy. Carlo has a deep knowledge of different development platforms and middleware on heterogeneous environments and operating systems. He worked for several years as a Certified Trainer and Solution Developer for a Microsoft® Certified Partner.

Since joining IBM in 2000, Carlo's main job interests are related to SOA and BPM, and their related software engineering methodologies and enabling platforms, and Enterprise Architecture planning and design. He enjoys collecting documentation and hardware pieces related to the historical development of IT, and to support this hobby he is a member of the Charles Babbage Institute.



Marco Antonioni (marco_antonioni@it.ibm.com), Certified IT Architect, IBM

Marco Antonioni photoMarco Antonioni is a Certified IT Architect and Open Group Master Certified IT Architect in IBM Software Group, Italy. Marco has a deep knowledge of WebSphere platforms (WebSphere Application Server, WebSphere Process Server, IBM Business Process Manager, IBM Operational Decision Manager, IBM Business Monitor, WebSphere Service Registry and Repository, and WebSphere Message Broker). Since joining IBM in 2000, his main role has been as a BPM Solution Architect in IBM Software Services for WebSphere.



15 October 2013

Also available in Chinese

Implementing the AIS in Integration Designer

Part 4 in this series guides you through the steps to implement the Advanced Integration Service (AIS) designed to invoke a couple of transactional web services in an SCA-based ESB mediation. The workspace for this demo is defined in KBPM-Main.zip provided for download in Part 1 of this series.

As discussed in the article Linking business processes and enterprise services together using IBM Business Process Manager Advanced, the term Advanced Integration Service is a bit of a misnomer: what is really provided is an "AIS operation" because an AIS in IBM BPM V8 provides the ability to define a single operation of a service. In a service design exercise, a logical service may result in a number of related AIS definitions, one for each operation. In the scenario described in this article, the AIS exposes the transactional operation that performs the transfer of funds.

The assembly diagram of the solution

Figure 1 shows the assembly diagram of the proposed solution. The main components are:

  • The AIS inbound Export TxWSAIS, with the interface TxWSAIS.
  • The mediation TxMediation, with the interface TxWSAIS and the two outbound Imports:
    • IWSChargeBank1SvcImport (interface IWSChargeBank1Svc, with the operation Charge) to wire the WSChargeBank1Svc web service.
    • IWSCreditBank2SvcImport (interface IWSCreditBank2Svc, with the operation Credit) to wire the WSCreditBank2Svc web service.
Figure 1. The assembly diagram of the AIS implementation
The assembly diagram of the AIS implementation

The binding properties of the two web service Imports contains the addresses of the called web services (Figure 2 and Figure 3).

Figure 2. The binding of IWSChargeBank1SvcImport
The binding of IWSChargeBank1SvcImport
Figure 3. The binding of IWSCreditBank2SvcImport
The binding of IWSCreditBank2SvcImport

The TxWSAIS interface, shown in Figure 4, is the interface of the AIS, and is the real interface between the BPMN-based implementation (as modeled in IBM BPM Process Designer) and the technical implementation of the AIS (the ESB mediation) in IBM Integration Designer.

Figure 4. The TxWSAIS interface
The TxWSAIS interface

As you can see, there are Input parameters (to drive the transaction), output parameters (the OutputMessage) and a Fault section that supports the transmission of an ErrorMessage string.

You need to configure the following SCA transactional qualifiers to enable the participation of both web services (WSChargeBank1Svc and WSCreaditBank2Svc) in the same global transactional context (initiated by the mediation), as shown in Figure 5:

  • Set Join transaction to true on the two participant interfaces ICharge and ICredit
  • Set Suspend transaction to false on the two references IChargePartner and ICreditPartner
  • Set Join transaction to True for:
    • TxMediation: Interfaces, TxWSAIS and invoke
    • IWSChargeBank1SvcImport: Interfaces, IWSChargeBank1Svc and Charge
    • IWSCreditBank2SvcImport: Interfaces, IWSCreditBank2Svc and Credit
  • Set Transaction to Global for TxMediation Implementation.
  • Set Suspend transaction to False for TxMediation References IWSCreditBank2SvcPartner and IWSChargeBank1SvcPartner.
Figure 5. The transactional qualifiers
The transactional qualifiers

IBM BPM Advanced uses the transaction manager in WebSphere Application Server as the basis for its transactions. For a mediation module, the transactional boundary can be configured for the entire module. In our case, we need a configuration in which the two involved web services, WSChargeBank1Svc and WSCreditBank2Svc, live in the same transactional context of the mediation, "joining" the global transactional context. The SCA transaction qualifiers specified for the mediation and the services that are called must be configured to enable the global transaction propagation.

The IWSCreditBank2Svc and IWSChargeBank1Svc interfaces (with the related operations Credit and Charge) are shown in Figure 6 and Figure 9.

Figure 6. The IWSCreditBank2Svc interface and the Credit operation
The IWSCreditBank2Svc interface and the Credit operation

The structure of the Credit and CreditResponse types is shown in Figure 7 and Figure 8.

Figure 7. The Credit type
The Credit type
Figure 8. The CreditResponse type
The CreditResponse type
Figure 9. The IWSChargeBank1 interface and the Charge operation
The IWSChargeBank1 interface and the Charge operation

The Input and Output parameters of the two operations Credit and Charge corresponds to the signature of the two methods Credit and Charge in the implementation of the two Web services WSCreditBank2Svc (implemented in Java using JAX-WS) and WSChargeBank1Svc (implemented in C# using .NET WCF), that are, respectively:

public String credit(String myConnection, String myTable, String myAccount, Integer myAmount))

and

public string Charge(string myConnection, string myTable, string myAccount, int myAmount)

The SCA ESB mediation in Integration Designer

The AIS used in the scenario described in this article is implemented using an SCA-based mediation, implemented in IBM Integration Designer. Mediation is a way of mediating or intervening dynamically between services. A mediation flow implements a mediation.

Mediation has several useful functions. For example, you can use mediation when you need to transform data from one service into an acceptable format for another service. You can use logging to log messages from a service before they are sent to the next service. You can use routing to route data from one service to an appropriate service determined by the mediation flow.

You can also use a mediation to map interfaces. Interfaces can have different operation names and the operations can have different parameter types. An interface map maps the operations and parameters of these methods so that the differences are resolved and the two components may interact. An interface map is like a bridge between the interfaces of two components allowing them to be wired together despite differences.

A mediation operates independently of the services that it connects to. In IBM Integration Designer, a mediation in the assembly editor appears as a mediation flow component between exports and imports. A mediation flow is a construct created with the mediation flow editor. When you select a mediation flow component in the assembly editor, you automatically open the mediation flow editor. In the mediation flow editor, an operation from one service (the service requester or export) is mapped to the operation of another service (the service provider or import), along with functions provided by the mediation flow editor. These functions are called mediation primitives and are wired in a mediation flow. You can use mediation primitives supplied by IBM, or you can create your own custom primitives. In fact, a couple of custom mediation primitives are part of our proposed solution. Mediation primitives can act on both message content and message context, where context is binding-specific information such as Simple Object Access Protocol (SOAP) or Java Message Service (JMS) headers, or user-defined properties.

Mediation primitives are connected together through terminals, which provide points of input to, and output from, the mediation primitives. All mediation primitives have an input terminal (called in) that can be wired to accept a message. Most mediation primitives have one fail terminal (called fail) and one or more output terminals. However, the stop and fail mediation primitives have no fail terminal and no output terminals.

We'll execute the credit operation to the target account (on Bank2 on DB2 server B) before the charge operation on the source account (on Bank1 on SQL Server A), to show explicitly how, for example, a try to set a negative remaining amount on the source account is triggered, and how it fires a local rollback on server A. We'll demonstrate how this rollback is propagated to the entire distributed transaction, causing the actual undo of the credit operation already done (or better, just "prepared" and still waiting for a final commit) on server B, thanks to the transactional support offered by combining the SCA-based AIS implementation in IBM BPM with the WS-AT protocol.

Figure 10 shows the diagram of the TxMediationflow in IBM Integration Designer.

Figure 10. The ESB mediation implementation in Integration Designer
The ESB mediation implementation in Integration Designer

Click to see larger image

Figure 10. The ESB mediation implementation in Integration Designer

The ESB mediation implementation in Integration Designer

The two core elements of this flow are the two calls to the Credit and Charge services, implemented by the two service invoke mediations, InvokeCredit and InvokeCharge. The following list of components (mediation primitives) defines the flow of operations implemented and executed in the case of a positive outcome of both of the service invocations. In this case, the different types of mediations used here, and the specific configurations adopted, are as follows:

  • Input (invoke): The input node is the starting point for the request flow. It sends the message from the source operation into the request flow.
  • FanOut1 (of type Fan Out): The Fan Out primitive is used in this scenario with the Fan In primitive, to aggregate or combine the two service responses (from the Credit and Charge web services).
  • FlowOrder1 (of type Flow Order): Allows the two branches of the flow to be completed in the order specified on the output terminals (the Credit operation is executed before the Charge operation).
  • MapForCredit (of type Mapping): Transforms the input message format by selecting only the values required to drive the Credit operation.
  • InvokeCredit (of type Service Invoke): Calls the WSCreditBank2Svc web service.
  • MsgElementSetterCredit (of type Message Element Setter): Copies /body/CreditResponse/CreditResult to /context/shared/ResponseFromCredit to enable the transfer (using the Service Message Object context) of the result from the Credit operation to the Input response node.
  • FromCreditToFanIn (of type Mapping): Is a simple pass through to the Fan In.
  • MapForCharge (of type Mapping): Transforms the input message format by selecting only the values required to drive the Charge operation.
  • InvokeCharge (of type Service Invoke): Calls the WSChargeBank1Svc web service.
  • MsgElementSetterCharge (of type Message Element Setter): Copies /body/ChargeResponse/ChargeResult to /context/shared/ResponseFromCharge to enable the transfer (using the Service Message Object context) of the result from the Charge operation to the Input response node.
  • FromChargeToFanIn (of type Mapping): Is a simple pass through to the Fan In.
  • FanIn1 (of type Fan In): Allows for the combination of multiple messages (created using the Fan Out primitive) within an aggregation. This Fan In is configured to fire output terminal when two messages have been received.
  • PrepareOutputMsg (of type Mapping): Is a mediation used to cancatenate the two (positive) output messages from the Credit and Charge operations (the two messages are read from the SMO context).
  • Input Response (invoke): The input response node is an endpoint in the request and response flows. It returns the processed message as a response to the source operation.

In case of an error in one of the two service invokes (InvokeCredit or InvokeCharge), the flow of operations executed is different. As described later in Service Invoke mediation primitive, the Service Invoke mediation primitive has one input terminal (in) and multiple output terminals. There is a fail terminal (fail) for unmodeled faults, and one output terminal (exception) for each modeled fault. Modeled faults are those that are explicitly listed in a WSDL file; any other fault is an unmodeled fault.

The Credit web service can generate a modeled exception fault (for example, for a nonexistent credit account) or an unmodeled fault. In the case of a modeled fault error in the InvokeCredit, the flow of operations implemented and executed (starting from the output terminal exception of the InvokeCredit) are as follows:

  • ManageCreditExc (of type mediation): Extracts the error information from the exception message and copies this string to the InvokeFault1Msg element in the body of the output message.
  • SynchTxRollback (of type Synchronous Transaction Rollback): Rolls back the current transaction when the flow is invoked in a synchronous style (as in our proposed scenario)
  • Input Fault (invoke): An endpoint in the request flow, the Input Fault node has an input terminal for each fault message type defined in the source operation. The error message is present in invokeFault1Msg.

In the case of an unmodeled fault error in the InvokeCredit, the flow of operations implemented and executed (starting from the output teminal fail) are as follows:

  • ManageCreditFail (of type custom mediation): extracts the error information from the context and copies this information to the InvokeFault1Msg element in the body of the output message.
  • Input Fault (invoke): The error message is present in invokeFault1Msg.

The Charge web service can generate only unmodeled faults in the InvokeCharge. Following is the flow in case of an error (for example, if in the case of a nonexistent account to charge or of unavailability of funds), starting from the output terminal fail of the InvokeCharge:

  • ManageChargeFail (of type custom mediation): extracts the error information from the context and copies this information to the InvokeFault1Msg element in the body of the output message.
  • Input Fault (invoke): The error message is present in invokeFault1Msg. Same comment.

Note that in the case of a modeled fault in the InvokeCredit, an explicit transaction rollback (using the mediation SynchTxRollback of type Synchronous Transaction Rollback) is required. On the other hand, unmodeled faults cause an automatic rollback of the global transaction.


Mediation primitive types in the solution

In the previously described flows, different kinds of mediation primitives are used. This section describes the main characteristics of the primitive types used in this scenario.

Fan Out and Fan In mediation primitives

You can use the Fan Out mediation primitive to create different messages from a repeating element in the input message. You can also use it, along with the Fan In mediation primitive, to aggregate, or combine, service responses. This second pattern is the one leveraged in our transactional scenario.

The Fan Out mediation primitive has one input terminal (in), two output terminals (out and noOccurrences), and a fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message.

In default mode, the out terminal is used to propagate the input message and the terminal is fired only once. If you use a Fan Out mediation primitive followed by a Fan In mediation primitive, you can aggregate the responses from two or more service invocations; the group of mediation primitives that occur between a Fan Out and a Fan In is called an aggregation block. This is exactly the pattern adopted in our scenario.

If an aggregation block contains Service Invoke mediation primitives on multiple branches, and the Service Invoke primitives are configured for synchronous invocation, (as in our scenario) the Service calls are synchronous, and there is, by design, no parallelism involved.

You can use the Fan Out and Fan In mediation primitives to aggregate the responses from two service invocations into one output message, as we've done in our scenario.

The shared context area of the SMO is for storing aggregation data between a Fan Out primitive and a Fan In primitive.

The Fan In mediation primitive is used to combine multiple messages, which you create using the Fan Out mediation primitive. The Fan In mediation primitive receives messages until a decision point is reached, then the last message to be received is propagated to the output terminal. Three types of decision points are supported:

  • Simple count: When a set number of messages are received at the input terminal, the Fan In mediation primitive fires the output terminal. The firing of the Fan In output terminal does not stop the Fan Out mediation primitive from sending messages. Therefore, the decision point might be reached more than once, resulting in multiple firings of the output terminal. This is the configuration adopted in our project.
  • XPath decision: If an XPath evaluation of the input message evaluates to true, the Fan In mediation primitive fires the output terminal.
  • Iterate: The Fan In mediation primitive waits to receive all of the messages produced by the corresponding Fan Out mediation primitive, and then fires the output terminal.

The Fan In mediation primitive has two input terminals (in and stop), two output terminals (out and incomplete) and a fail terminal (fail). The input terminals are wired to accept a message and the other terminals are wired to propagate a message. The in terminal accepts input messages until a decision point is reached, at which point the out terminal is fired. The Fan In mediation primitive cannot be used without the Fan Out mediation primitive.

Flow Order mediation primitive

You can use the Flow Order mediation primitive to customize the flow by specifying the output terminals to be fired. The Flow Order mediation primitive does not change the input message.

The Flow Order mediation primitive has one input terminal (in) and any number of output terminals. The in terminal is wired to accept a message and the other terminals are wired to propagate a message.

The output terminals are fired in the order that they are defined on the primitive, with each branch completing before the next starts. Each output terminal is fired with an unmodified copy of the input message. Each branch of the flow is completed before the next terminal is fired.

In our scenario, FlowOrder1 is used to call the Credit services before the Charge services, to explicitly demonstrate the automatic rollback capabilities of the IBM BPM mediation module with the WS-AT protocol.

Mapping mediation primitive

When you are integrating services, you often need to transform data into a format that the receiving service can process. The Mapping mediation primitive lets you transform one message type into a different message type. It gives you a simple mechanism for manipulating messages, using an XSLT transformation or a business object map. You can change the headers, context, or body of the SMO by mapping between the input and output message.

In our scenario, this kind of mediation primitive is used to implement MapForCredit, MapForCharge, FromCreditToFanIn, FromChargeToFanIn, ManageCreditExc and PrepareOutputMsg.

Message Element Setter mediation primitive

You can use the Message Element Setter mediation primitive to provide a simple mechanism for setting message content; it does not change the type of the message. You can change, add or delete message elements by setting the mediation primitive properties. Target elements are specified as XPath expressions using the Target property.

In our scenario, the two mediations MsgElementSetterCredit and MsgElementSetterCharge are used to set a message in the header with the positive outcome of the calls to the Credit and Charge web services, respectively.

Service Invoke mediation primitive

You can use the Service Invoke mediation primitive to call a service from inside a mediation flow, as an alternative to using the callout mechanism at the end of the mediation flow. You can have multiple Service Invoke mediation primitives inside one mediation flow. Therefore, you can have a series of service calls. You can use the Service Invoke mediation primitive in a request or response mediation flow.

The Service Invoke mediation primitive has one input terminal (in) and multiple output terminals. There is a fail terminal (fail) for unmodeled faults, and one output terminal for each modeled fault. Modeled faults are those that are explicitly listed in a WSDL file; any other fault is an unmodeled fault. In addition, there is an output terminal (out), which is used for successful service calls, and a timeout terminal (timeout), which is used for some types of asynchronous calls.

In the scenario described in this article:

  • The Charge .NET web service can generate an unmodeled fault; in this case, the fail terminal of the Service Invoke can be activated (a custom mediation follows to extract the error information string from the context of the returned message); the unmodeled fault automatically raises a transaction rollback at the mediation level.
  • The Credit JEE web service can generate an exception (a modeled fault, as defined in the WSDL of the web service); in this case, the corresponding terminal of the Service Invoke is activated (a standard mapping mediation primitive follows to extract the error information string from the returned SOAP message). The modeled fault does not automatically roll back the global transaction, so in this case, there is a Synchronous Transaction Rollback mediation primitive in the mediation flow.

Note that these two different options in the web services implementation, and the related different modes of errors exposure, have been chosen also to illustrate the different ways of handling errors in the mediation.

The developerWorks article Tracing, logging, and error handling in mediation modules using IBM Integration Designer, WebSphere ESB, WebSphere Process Server, and Business Process manager Advanced Edition, Part 2 – Strategies for designing error handling in web service mediations describes in detail the different patterns and techniques to manage errors in a mediation flow.

Synchronous Transaction Rollback mediation primitive

You can use the Synchronous Transaction Rollback mediation primitive to roll back the current transaction and then continue processing the flow. The Synchronous Transaction Rollback can be used only in mediation flows that use a synchronous invocation style, as is done in our scenario.

Use the Synchronous Transaction Rollback primitive if you want to explicitly roll back the current transaction in a mediation flow, as part of an error handling routine. In our case, this mediation primitive is used to explicitly rollback the global transaction when there is a modeled fault in the Credit Service Invoke.

Custom Mediation mediation primitive

You can use the Custom Mediation primitive to implement your own mediation logic in Java code. This primitive combines the flexibility of a user-defined mediation primitive with the simplicity of a predefined mediation primitive. You can add new terminals and create your own properties, which this allows you to create complex transformations and routing patterns.

In our scenario, the custom mediations ManageCreditFail and ManageChargeFail are used to extract the error information (in the case of unmodeled faults) from the context of the returned errors from the Credit and Charge service invokes.


Mediation flow details and mediation primitive configuration

The main configurations implemented in the mediation flow introduced earlier are described in the following. The "happy path" is described first, followed by the error paths.

The happy path

  • MapForCredit (of type Mapping): This primitive is used to prepare the parameter for the invocation of the WSCreditBank2Svc web service. Figure 11 shows the implemented mapping. As you can see, only the Credit-related values are transferred to the service invoke.
    Figure 11. The MapForCredit mediation
    The MapForCredit mediation
  • MapForCharge (of type Mapping): This primitive is used to prepare the parameter for the invocation of the WSChargeBank1Svc web service. Figure 12 shows the implemented mapping. As you can see, only the Charge-related values are transferred to the service invoke.
    Figure 12. The MapForCharge mediation
    The MapForCharge mediation

    Click to see larger image

    Figure 12. The MapForCharge mediation

    The MapForCharge mediation
  • FanIn1 (of type Fan In): In the FanIn1 properties, it is important to note that the output terminal is fired only when two messages are received, as shown in Figure 13.
    Figure 13. FanIn1 configuration properties
    FanIn1 configuration properties
  • PrepareOutputMsg (of type Mapping): This mediation is used to concatenate the two positive output messages from the Credit and Charge operation (the two messages are read from the SMO context), as shown in Figure 14.
    Figure 14. The PrepareOutputMsg mediation
    The PrepareOutputMsg mediation

    Click to see larger image

    Figure 14. The PrepareOutputMsg mediation

    The PrepareOutputMsg mediation

The error paths

There are at least three main kinds of typical exceptions that the Credit and Charge web services (called by the InvokeCredit and InvokeCharge flow activities, respectively) can throw, and that are managed, or caught, by the mediation flow:

  • The unavailability of the account name of the source (for Charge) or target (for Credit) bank account. In this case, the web services raise an error with the message "Invalid account."
  • The unavailability of sufficient money in the charge account. In this case, the trigger on the database raises an "Insufficient money" exception that the web service can re-throw to the caller.
  • Any other runtime error (for example a wrong table name, an unavailable JDBC connection, a network error to reach the remote database engine, and so on) captured and re-launched by the Web service, with the related error message

The Credit web service can generate a modeled exception fault (for example, for a nonexistent credit account) or an unmodeled fault. Modeled faults correspond to errors defined on the WSDL interface. Unmodeled faults are errors that are not declared in the WSDL interface.

In case of an modeled fault error in the InvokeCredit, the two involved mediations are the ManageCreditExc (of type mediation) and the SynchTxRollback (of type Synchronous Transaction Rollback).

The ManageCreditExc mediation primitive is designed to extract the error information (a string) from the exception message, and to generate an output body with this string in the InvokeFault1 element, as shown in Figure 15.

Figure 15. The ManageCreditExc mediation
The ManageCreditExc mediation

Click to see larger image

Figure 15. The ManageCreditExc mediation

The ManageCreditExc mediation

Note that in the case of a modeled fault in InvokeCredit, a explicit transaction rollback is required, using the mediation SynchTxRollback; unmodeled faults cause an automatic transaction rollback.

In the case of an unmodeled fault error in InvokeCredit, there is a ManageCreditFail mediation (of type Custom mediation). The ManageCreditFail is similar to the ManageChargeFail custom mediation used to handle the unmodeled fault from the Service Invoke to the WSChargeBank1Svc.

Listing 1 contains the code of the ManageCreditFail custom mediation.

Listing 1. The source code of the ManageCreditFail custom mediation code
/**
 * GENERATED COMMENT - DO NOT MODIFY
 * Variables:  for output terminals - out (com.ibm.wsspi.sibx.mediation.OutputTerminal)
 *             for user properties - <No user properties defined>
 * Inputs:     inputTerminal (com.ibm.wsspi.sibx.mediation.InputTerminal), 
	smo (com.ibm.websphere.sibx.smobo.ServiceMessageObject)
 * Exceptions: com.ibm.wsspi.sibx.mediation.MediationConfigurationException, 
	com.ibm.wsspi.sibx.mediation.MediationBusinessException
 */

try
{
// fault parsing
javax.xml.parsers.DocumentBuilderFactory factory = 
	javax.xml.parsers.DocumentBuilderFactory.newInstance();
javax.xml.parsers.DocumentBuilder builder = factory.newDocumentBuilder();
String soapFault = smo.getContext().getFailInfo().getFailureString();
java.io.ByteArrayInputStream bis = new java.io.ByteArrayInputStream (soapFault.getBytes());
org.w3c.dom.Document document = builder.parse(bis);

String faultstring = "";

faultstring = 
	document.getElementsByTagName("faultstring").item(0).getChildNodes().item(0).getNodeValue();

com.ibm.websphere.sca.ServiceManager serviceManager = new com.ibm.websphere.sca.ServiceManager();
com.ibm.websphere.bo.BOFactory bofactory = 
	(com.ibm.websphere.bo.BOFactory)serviceManager.locateService("com/ibm/websphere/bo/BOFactory");

commonj.sdo.DataObject newbody = 
	bofactory.createByMessage("http://KBPM/AIS/TxWSAIS", "invokeFault1Msg");
newbody.setString("invokeFault1", faultstring);
smo.setBody(newbody);

out.fire(smo);

}
catch (Exception ex)
{
ex.printStackTrace();

The Charge web service can generate only unmodeled faults in InvokeCharge (this web service does not expose faults in the WSDL). In this case, the flow reaches the ManageChargeFail mediation. The ManageChargeFail is similar to the ManageCreditFail custom mediation used to handle the unmodeled fault from the Service Invoke to the WSCCreditBank1Svc.

In case of error, the error message must be extracted from the Context/failInfo/failureString structure. The failureString is an XML string like this:

<soapenv:Body 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Fault>
<faultcode>soapenv:Client</faultcode>
<faultstring>Exception from Charge (-): 
	myConnection: Data Source=localhost; Uid=sa; Initial Catalog=Bank1; 
	Pwd=mypwd; strSQL: UPDATE dbo.Accounts SET Amount = Amount - 200 
	WHERE Description = &apos;Karl&apos;; ex.Message: Insufficient money.&#xd;
The transaction ended in the trigger. The batch has been aborted.
</faultstring>
</soapenv:Fault>
</soapenv:Body>

The XML payload listed above (the complete failureString) is initially acquired with the code:

String soapFault = smo.getContext().getFailInfo().getFailureString();

Later, from the complete soapFault XML string (the XML code listed above) the simple faultstring is extracted with the code:

Click to see code listing

faultstring = document.getElementsByTagName("faultstring").item(0).getChildNodes().item(0).getNodeValue();

And the faultstring is then used to build the answer in the message body as follows:

newbody.setString("invokeFault1", faultstring);
smo.setBody(newbody);

Listing 2 the complete code of the ManageChargeFail custom mediation.

Listing 2. ManageChargeFail custom mediation
/**
 * GENERATED COMMENT - DO NOT MODIFY
 * Variables:  for output terminals - out (com.ibm.wsspi.sibx.mediation.OutputTerminal)
 *             for user properties - <No user properties defined>
 * Inputs:     inputTerminal (com.ibm.wsspi.sibx.mediation.InputTerminal), 
	smo (com.ibm.websphere.sibx.smobo.ServiceMessageObject)
 * Exceptions: com.ibm.wsspi.sibx.mediation.MediationConfigurationException, 
	com.ibm.wsspi.sibx.mediation.MediationBusinessException
 */
try
{
// fault parsing
javax.xml.parsers.DocumentBuilderFactory factory = 
	javax.xml.parsers.DocumentBuilderFactory.newInstance();
javax.xml.parsers.DocumentBuilder builder = factory.newDocumentBuilder();
String soapFault = smo.getContext().getFailInfo().getFailureString();
java.io.ByteArrayInputStream bis = 
	new java.io.ByteArrayInputStream (soapFault.getBytes());
org.w3c.dom.Document document = builder.parse(bis);

String faultstring = "";
faultstring = 
	document.getElementsByTagName("faultstring").item(0).
	getChildNodes().item(0).getNodeValue();

com.ibm.websphere.sca.ServiceManager serviceManager 
	= new com.ibm.websphere.sca.ServiceManager();
com.ibm.websphere.bo.BOFactory bofactory = 
	(com.ibm.websphere.bo.BOFactory)serviceManager.
	locateService("com/ibm/websphere/bo/BOFactory");

commonj.sdo.DataObject newbody = 
	bofactory.createByMessage("http://KBPM/AIS/TxWSAIS", "invokeFault1Msg");

newbody.setString("invokeFault1", faultstring);
smo.setBody(newbody);

out.fire(smo);
}
catch (Exception ex)
{
ex.printStackTrace();
}

For a good, technical description of the error handling in IBM BPM V8 with AIS, refer to the IBM developerWorks articles Configuring error handling for Advanced Integration Services in IBM Business Process Manager Advanced V8 and, especially for the ESB mediations, to Tracing, logging, and error handling in mediation modules using IBM Integration Designer, WebSphere ESB, WebSphere Process Server, and Business Process Manager Advanced Edition, Part 2.


Configuring and applying the transactional policy set

In addition to configuring the transaction service on the WebSphere Application Server, you need to perform the following steps to enable the policy set for the Java web service provider (the Credit web service), and the two web service consumers in the SCA-based mediation in IBM BPM. We recommend that you apply these configurations in the WebSphere administrative console and also in the Integration Designer development environment.

Create and export a new transactional policy

  1. In the WebSphere administrative console, select Services => Policy sets => Application policy sets.
  2. Click New, then specify a name (for example, myWSTransaction) and add WS-Transaction in the policies section. Click OK and save the changes.
  3. Navigate to the WS-Transaction settings on the newly created policy set. Select the Mandatory option for WS-Atomic Transaction, as shown in Figure 16 and save the changes.
    Figure 16. Configure the new transactional policy
    Configure the new transactional policy

    Click to see larger image

    Figure 16. Configure the new transactional policy

    Configure the new transactional policy
  4. From Application policy sets. select the new policy, and then select Export to export the new policy to a file, such as myWSTransaction.zip. This file will be used to import and use the policy in Integration Designer.
  5. Restart WebSphere Application Server.

Apply the transactional policy to the JAX-WS Credit web service provider

Apply the policy using WebSphere Administrative console as follows:

  1. Select Services => Service providers.
  2. Click the service provider for the Credit web service (WSCreditBank2Svc).
  3. Check your service provider.
  4. Click Attach and select the new policy, such as myWSTransaction.
  5. Click Save.

Apply the policy in Integration Designer as follows:

  1. In Integration Designer, open the workspace with the WSCreditBank2Svc Web service.
  2. From File/Import, select WebSphere Policy Sets (in the Web services category). Where is File/Import? Is that a menu item?
  3. Select the zip file that contains the transactional policy exported from the WebSphere administrative console (for example, myWSTransaction.zip).
  4. Click Finish.
  5. In the Services view, expand JAX-WS and right-click WSCreditBank2Project: {...}WSCreditBank2Svc.
  6. Select Manage Policy Set Attachments/Server Side.
  7. Add the myWSTransaction policy to the WSCreditBank2Svc service. The final configuration should look like Figure 17.
Figure 17. Add the transactional policy to the Credit Web service provider in Integration Designer
Add the transactional policy to the Credit Web service provider in Integration Designer

Apply the policy to the web services imports in the ESB mediation

Apply the policy using the WebSphere administrative console as follows:

  1. Select Services => Service clients.
  2. Select the service client name, such as WSChargeBank1Svc (with the deployed asset name KWSBPM-Tip-KWSBPMMediationModuleApp).
  3. Select WSChargeBank1Svc.
  4. In the Attach Client Policy Set, select the transactional policy (myWSTransaction), and click Save.
  5. Select Services =>Service clients.
  6. Select the other service client name, such as WSCreditBank2Svc (with the same deployed asset name, KWSBPM-Tip-KWSBPMMediationModuleApp, as the WSChargeBank1Svc).
  7. Select WSCreditBank2Svc.
  8. In the Attach Client Policy Set, select the transactional policy (myWSTransaction), and click Save.

Apply the policy in Integration Designer as follows

  1. In Integration Designer, open the workspace with the Advanced Integration Service (KWSBPM Main) implementation.
  2. Under File/Import, select WebSphere Policy Sets (in the Web services category).
  3. Select the zip file that contains the transactional policy exported from the WebSphere Application Server administrative console (for example, myWSTransaction.zip).
  4. Click Finish.
  5. Open the KWSBPMMediationModule assembly diagram.
  6. Click IWSChargeBank1SvcImport.
  7. In the properties of the Import, click Policy Sets.
  8. Select the transactional policy myWSTransaction as the default policy set.
  9. In the assembly diagram, click IWSCreditBank2SvcImport.
  10. In the properties of the import, click Policy Sets.
  11. Select the transactional policy myWSTransaction as the default policy set.

Conclusion

Part 4 of this series covered how to implement the transactional AIS in Integration Designer, based on an SCA-based ESB mediation, with the invocation of two transactional web services. You've learned how to design the AIS in Integration Designer as an assembly diagram, how to design the ESB mediation flow, how to configure the interfaces and the transactional qualifiers, and how to call the two transactional web services to manipulate the data on the two databases Bank1 and Bank2. In the final part of this series, Part 5, you'll learn how to execute and test different transactional scenarios with the components designed and developed in the previous parts of this series, and will learn about the ACID (atomicity, consistency, isolation, durability) characteristics of the implemented solution.


Acknowledgements

The authors would like to thank their colleagues Giuseppe Bottura and Simone Chiucchi for their reviews of this article, and their colleagues Stefano Angrisano, Matteo Franciolli, and Daniele Rossi for their contributions. We also want to thank Andrew J. Howes, Billy Lo, Frank I. Toth, Dave Screen, Callum Jackson, Konstantin Luttenberger and Oliver Rebmann for their inspiring and thoughtful developerWorks articles.

Resources

Resources specific to the .NET platform

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=948322
ArticleTitle=Developing a distributed WS-AT transaction using an IBM BPM Advanced Integration Service, Part 4: Implementing the Advanced Integration Service
publish-date=10152013