Menu

XML Transactions for Web Services, Part 3

May 27, 2003

Faheem Khan

In the first article of this series I introduced the idea of XML-based transactions. In the second article, I described an Enterprise Application Integration (EAI) scenario which was meant to demonstrate XML messaging in an Atomic Transaction (AT). I demonstrated how the sales module of a PC assembler interacts with inventory, database, assembly line management and accounts modules to fulfill a bookOrder method invocation request.

In this third and final article of the series, I'll discuss another type of XML transaction, the Business Activity (BA). The BA specification is included in the same WS-Transaction document that includes the AT specification.

I will extend the AT discussion of the second article to establish a case for BA and demonstrate how BA enables XML-based transactions to cross the boundaries of an enterprise and allows humans to interact with software modules and participate in real world business tasks.

An Application Scenario

Let's suppose that a distributor of PC related items wants to order some components. The distributor calls the order a purchase activity. The distributor wants to buy three of the items included in the purchase activity from the PC Assembler that we introduced in the second article. The distributor will send three bookOrder method invocation calls to the PC Assembler's sales module.

The three method invocation calls are independent of each other in the sense that the PC Assembler may opt to supply any one, two, or all three items. However, the three method invocation calls are not absolutely independent of each other, as they all relate to the same purchase activity.

The distributor wants to know whether the PC assembler can supply all the three items. The PC assembler's sales module will perform one AT (exactly as described in the second article) for each item. The outcome of the transaction will tell whether the PC assembler can supply the item or not.

If the PC Assembler has no problem supplying the three items, the distributor will confirm the order. If there are problems in any of the three items, the distributor would like to reconsider the entire purchase activity. For example, the distributor may want to contact some other supplier to ask for the availability of the three items and may eventually buy only one item from the PC assembler.

Business Activities

Try to compare this purchase activity with the bookOrder activity that we discussed in the second article. The sales module of the PC assembler tried to perform a transaction to confirm the availability of all components required to fulfill the order. The purchase order and bookOrder activities are similar in the sense that both activities need coordination across different SOAP request-response pairs. For example, the final outcome of the purchase order activity will depend upon the result of various SOAP method invocation calls.

However the purchase order activity is not totally analogous to the bookOrder scenario. There are significant differences, including the following:

  1. In the bookOrder activity, we were required to confirm the availability of all components. It was an all or none requirement. If all the components were available the activity would commit, otherwise the entire activity would roll back. On the other hand, the purchase activity is more flexible. Here the distributor will ask the PC Assembler to check if the three items are available. If one or more items cannot be supplied, the distributor will analyze the scenario and may even check alternate sources before making the final decision. So the end result in the purchase activity will not look like an all or none decision. The final decision may fall somehwere in between.

  2. The bookOrder activity was a completely automated operation. There was no need for any human interaction during the course of the activity. On the other hand, the purchase activity may involve human interaction. For example, there may be a Purchase Manager responsible to analyze and decide what to do if the PC Assembler cannot supply all the three items.

  3. This human interaction also means that the purchase activity will have a longer life as compared to the bookOrder activity. For example, the Purchase Manager may not be immediately available when his interaction is required in the activity. So we will have to wait for the Purchase Manager to play a role.

  4. The bookOrder activity never crossed the boundaries of a trusted domain. So we had no problem locking our resources. However, we cannot guarantee that the purchase order activity will always take place between organizations that enjoy a high level of trust for each other. For example, the distributor may also ask the availability of some items from vendors that are new to him, thus bringing those new organizations within the scope of a BA.

Thus, the purchase order activity is a coordinated activity just like the bookOrder activity was. However, the two activities are not exactly the same and they have several fundamental differences. These differences provide the basic rationale for defining a flexible type of coordinated activity that allows partly committed and partly rolled-back operations, that is longer lived, and that allows us to cross the boundaries of trusted domains. The Business Activity (BA) as defined by the WS-Transaction specification is an attempt to define an XML-based mechanism for such coordinated activities.

The four differences between the purchase and bookOrder activities mentioned above do not form the complete basis for defining the BA process. There is one more fundamental reason for it. Business Activities allow nested activities, which means that we can create activities that have parent-child relationship with each other. There can be any number of nesting levels.

For example, if we consider the aforementioned application scenario, the overall purchase activity can be considered as a parent activity, while there can be a number of child activities, one for each item. This concept is shown graphically in Figure 1, which illustrates the fact that the parent purchase activity consists of many child activities, where each child represents the purchase of a single item. Notice that each child activity may further consist of one or more ATs. The next section of this article will demonstrate the actual exchange of messaging that accomplishes this.

Figure 1
Figure 1. A Parent BA May Consist of Child Activities

You can think of each BA as a scope. The child activities will live within the scope of their parent. For example, the BA related to a single item will be valid only within the scope of the parent purchase activity. Also notice that the purchase activity will depend on the outcome of activities related to individual items. For example, the overall purchase activity will depend on whether the PC Assembler can or cannot supply the three items that the distributor requires from him. Thus, the concept of BA enables the breaking of a business process into a hierarchy of smaller and more manageable tasks. This provides another reason for the Business Activity process.

Exchange of Messages in Business Activities

A new BA is created using the same WS-Coordination activation service that we demonstrated in the second article. Similarly, the participants will also register their roles using the WS-Coordination registration service. There are two possible roles that a participant can assume in a BA. For each role the WS-Transaction specification defines a protocol.

I have provided a graphical illustration of the activities that take place during the execution of the purchase BA in Figure 2. Notice that there are three participants (actors) in the purchase order business activity: the distributor's purchase module, the distributor's coordinator, and the PC assembler's sales module. The distributor's purchase module and the coordinator are two distinct modules that belong to the distributor's enterprise implementation. However, for the PC assembler's sales module, the other two participants (the distributor's purchase module and the coordinator) appear to be the same actor, as the two participants belong to the same enterprise.

Figure 2
Figure 2. Exchanging Messages During the Course of a BA

All messages are shown as numbered arrows in Figure 2 and explained below:

1. The distributor's purchase module initiates the purchase activity by requesting the activation service of the coordinator to create a new BA. The purchase module sends a CreateCoordinationContext request as shown in Listing 1 to its coordinator's activation service.

Listing 1


<?xml version="1.0"?> 
<SOAP:Envelope 
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
    xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
    <SOAP:Body>
        <wscoor:CreateCoordinationContext>
            <wscoor:ActivationService>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/WSTM/activation
                </wsu:Address>
            </wscoor:ActivationService>
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/purchase
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinationType>
                http://schemas.xmlsoap.org/ws/2002/08/wsba
            </wscoor:CoordinationType>                                
        </wscoor:CreateCoordinationContext>
   </SOAP:Body>
</SOAP:Envelope>

Listing 1 is very similar to step 1 of Exchange of Messages in Atomic Transactions section in the second article, where we created a new AT. The only differences are the following:

  • This time the address of the coordinator's activation service is http://www.AFictitiousDistributor.com/WSTM/activation (look at the content of the wsu:Address element within the wscoor:ActivationService element in Listing 1).
  • Similarly, this time the address of the requester is http://www.AFictitiousDistributor.com/purchase (look at the content of the wsu:Address element within the RequesterReference element).
  • Also notice the contents of the wscoor:CoordinationType element. This time the content is http://schemas.xmlsoap.org/ws/2002/08/wsba, which is the identifier string for business activities.

2. The coordinator's activation service responds with a CreateCoordinationContextResponse message as shown in Listing 2. The CreateCoordinationContextResponse element in Listing 2 wraps two child elements. The first child is a RequesterReference element, while the second child is a CoordinationContext element. We described both these elements in detail in the second article in step 2 of the Exchange of Messages in Atomic Transactions section, when the coordinator responded after instantiating a new AT.

Listing 2


<?xml version="1.0"?>  
<SOAP:Envelope 
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" 
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
    <SOAP:Body> 
        <wscoor:CreateCoordinationContextResponse 
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor" 
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"> 
            <wscoor:RequesterReference> 
                <wsu:Address> 
                    http://www.AFictitiousDistributor.com/purchase 
                </wsu:Address> 
            </wscoor:RequesterReference> 
            <wscoor:CoordinationContext> 
                <wsu:Identifier> 
http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786 
                </wsu:Identifier> 
                <wscoor:CoordinationType> 
                    http://schemas.xmlsoap.org/ws/2002/08/wsba 
                </wscoor:CoordinationType> 
                <wscoor:RegistrationService> 
                    <wsu:Address> 
                        http://www.AFictitiousDistributor.com/WSTM/registration 
                    </wsu:Address> 
                </wscoor:RegistrationService> 
            </wscoor:CoordinationContext> 
        </wscoor:CreateCoordinationContextResponse> 
    </SOAP:Body> 
</SOAP:Envelope>

3. Now the purchase module of the distributor creates a new BA, representing the first item of the purchase order. For this purpose, it sends another CreateCoordinationContext message (as shown in Listing 3) to the coordinator's activation service.

Listing 3


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:CreateCoordinationContext
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:ActivationService>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/WSTM/activation
                </wsu:Address>
            </wscoor:ActivationService>
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/purchase
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinationType>
                http://schemas.xmlsoap.org/ws/2002/08/wsba
            </wscoor:CoordinationType>     
            <pcdc:NestedCreate
                wsu:MustUnderstand="true" 
                xmlns:pcdc=
"http://www.AFictitiousDistributor.com/schemas/coordinator"
                parentIdentifer=
"http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786"
                relationship="PurchaseActivityToItem" /> 
         </wscoor:CreateCoordinationContext>
   </SOAP:Body>
</SOAP:Envelope>

Listing 3 is similar to Listing 1, except that the CreateCoordinationContext element in Listing 3 has a NestedCreate child element. Notice that the NestedCreate element belongs to the distributor's own namespace (http://www.AFictitiousDistributor.com/schemas/coordinator). This is an extensibility mechanism allowed by the WS-Transaction specification. Applications can use their own elements within the CreateCoordinationContext message to identify the relationship between parent and child business activities.

The NestedCreate element in Listing 3 specifies that the CreateCoordinationContext message is requesting to create a child activity of an existing parent BA whose identifier is http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786. The relationship attribute of the NestedCreate element. belongs to the distributor's own namespace and states that the relationship between the parent and child business activities will be that of a purchase order and an item of a purchase order.

I have also included a wsu:MustUnderstand attribute in the NestedCreate element. It is mandatory for this extension element to contain the wsu:MustUnderstand="true" attribute, so that implementations who do not understand this attribute return a standard SOAP Misunderstood fault. The purpose of including this NestedCreate element is to let the coordinator know that we want to create a new child activity of the parent BA whose identifier is http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786.

4. The coordinator responds with a CreateCoordinationContextResponse message as shown in Listing 4.

Listing 4


<?xml version="1.0"?>
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:CreateCoordinationContextResponse
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/purchase
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinationContext>
                <wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item1OfPurchaseOrderActivity786
                </wsu:Identifier>
                <wscoor:CoordinationType>
                    http://schemas.xmlsoap.org/ws/2002/08/wsba
                </wscoor:CoordinationType>
                <wscoor:RegistrationService>
                    <wsu:Address>
                        http://www.AFictitiousDistributor.com/WSTM/registration
                    </wsu:Address>
                </wscoor:RegistrationService>
            </wscoor:CoordinationContext>
        </wscoor:CreateCoordinationContextResponse>
   </SOAP:Body>
</SOAP:Envelope>

5--8. Similarly, the purchase module creates two more child activities within the scope of the parent activity that the purchase module created in steps 1 and 2. Listing 5 is the CreateCoordinationContext request for a business activity related to item 2, while Listing 6 is the corresponding response. Listing 7 is the CreateCoordinationContext request for a business activity related to item 3, while Listing 8 is the corresponding response.

Listing 5


<?xml version="1.0"?>
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:CreateCoordinationContext
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:ActivationService>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/WSTM/activation
                </wsu:Address>
            </wscoor:ActivationService>
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/purchase
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinationType>
                http://schemas.xmlsoap.org/ws/2002/08/wsba
            </wscoor:CoordinationType>
            <pcdc:NestedCreate
                wsu:MustUnderstand="true" 
                xmlns:pcdc=
"http://www.AFictitiousDistributor.com/schemas/coordinator"
                parentIdentifer=
"http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786"
                relationship="PurchaseActivityToItem" /> 
        </wscoor:CreateCoordinationContext>
   </SOAP:Body>
</SOAP:Envelope>

Listing 6


<?xml version="1.0"?>  
<SOAP:Envelope 
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" 
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
    <SOAP:Body> 
        <wscoor:CreateCoordinationContextResponse 
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor" 
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"> 
            <wscoor:RequesterReference> 
                <wsu:Address> 
                    http://www.AFictitiousDistributor.com/purchase 
                </wsu:Address> 
            </wscoor:RequesterReference> 
            <wscoor:CoordinationContext> 
                <wsu:Identifier> 
http://www.AFictitiousDistributor.com/WSTM/ids/Item2OfPurchaseOrderActivity786 
                </wsu:Identifier> 
                <wscoor:CoordinationType> 
                    http://schemas.xmlsoap.org/ws/2002/08/wsba 
                </wscoor:CoordinationType> 
                <wscoor:RegistrationService> 
                    <wsu:Address> 
                        http://www.AFictitiousDistributor.com/WSTM/registration 
                    </wsu:Address> 
                </wscoor:RegistrationService> 
            </wscoor:CoordinationContext> 
        </wscoor:CreateCoordinationContextResponse> 
   </SOAP:Body> 
</SOAP:Envelope>

Listing 7


<?xml version="1.0"?>
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:CreateCoordinationContext
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:ActivationService>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/WSTM/activation
                </wsu:Address>
            </wscoor:ActivationService>
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/purchase
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinationType>
                http://schemas.xmlsoap.org/ws/2002/08/wsba
            </wscoor:CoordinationType>                                
            <pcdc:NestedCreate
                wsu:MustUnderstand="true" 
                xmlns:pcdc=
"http://www.AFictitiousDistributor.com/schemas/coordinator"
                parentIdentifer=
"http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786"
                relationship="PurchaseActivityToItem" /> 
        </wscoor:CreateCoordinationContext>
   </SOAP:Body>
</SOAP:Envelope>

Listing 8


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:CreateCoordinationContextResponse
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousDistributor.com/purchase
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinationContext>
                <wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item3OfPurchaseOrderActivity786
                </wsu:Identifier>
                <wscoor:CoordinationType>
                    http://schemas.xmlsoap.org/ws/2002/08/wsba
                </wscoor:CoordinationType>
                <wscoor:RegistrationService>
                    <wsu:Address>
                        http://www.AFictitiousDistributor.com/WSTM/registration
                    </wsu:Address>
                </wscoor:RegistrationService>
            </wscoor:CoordinationContext>
        </wscoor:CreateCoordinationContextResponse>
   </SOAP:Body>
</SOAP:Envelope>

I have created four business activities so far. The identifier for the parent purchase order activity is http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786. The purchase order business activity contains three child activities, one for each item to be procured. The identifiers for the three child business activities are http://www.AFictitiousDistributor.com/WSTM/ids/Item1OfPurchaseOrderActivity786, http://www.AFictitiousDistributor.com/WSTM/ids/Item2OfPurchaseOrderActivity786, and http://www.AFictitiousDistributor.com/WSTM/ids/Item3OfPurchaseOrderActivity786 for items 1, 2, and 3 respectively.

9. Now the purchase module of the PC distributor sends an application specific message (shown in Listing 9) to the sales module of the PC assembler. The message will convey that the distributor wants to order item 1 to the PC Assembler. Notice from Listing 9 that the SOAP Body contains the application specific message, while the SOAP Header contains a CoordinationContext element related to the business activity representing the purchase of first item of the purchase order.

Listing 9


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
    xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
    <SOAP:Header>
        <wscoor:CoordinationContext>
             <wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item1OfPurchaseOrderActivity786
              </wsu:Identifier>
              <wscoor:CoordinationType>
                    http://schemas.xmlsoap.org/ws/2002/08/wsba
              </wscoor:CoordinationType>
              <wscoor:RegistrationService>
                  <wsu:Address>
                        http://www.AFictitiousDistributor.com/WSTM/registration
                  </wsu:Address>
              </wscoor:RegistrationService>
        </wscoor:CoordinationContext>
    </SOAP:Header>
    <SOAP:Body>
       <!--An application specific message from the distributor’s purchase module 
            to the PC assembler's sales module.-->
    </SOAP:Body>
</SOAP:Envelope>

10. The PC assembler's sales module now registers the business activity for item 1, so that it can perform the actual in-house AT as described in the second article. So it sends a Register message to the coordinator. The Register message is shown in Listing 10, which is very similar to the Register message that we discussed in point number 3 of the section Exchange of Messages in Atomic Transactions in the second article. Why did the sales module register for the business activity related to the first item? The simple reason is that the sales module has a role to play in this activity. And WS-Coordination does not allow participants to play roles (i.e. participate) in coordinated activities without registering.

Listing 10


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:Register
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:RegistrationService>
                <wsu:Address>
                    http://www.AFictitiousPCDistributor.com/WSTM/registration
                <wsu:Address>
            </wscoor:RegistrationService>
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousPCAssembler.com/sales
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:ProtocolIdentifier>
                     http://schemas.xmlsoap.org/ws/2002/08/wsba/BusinessAgreement
            </wscoor:ProtocolIdentifier>
            <wscoor:ParticipantProtocolService>
                <wsu:Address> 
                    http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wscoor:ParticipantProtocolService>
       </wscoor:Register>
   </SOAP:Body>
</SOAP:Envelope>

Notice the ProtocolIdentifier element in Listing 10, which wraps the URI http://schemas.xmlsoap.org/ws/2002/08/wsba/BusinessAgreement. This URI is the identifier of the BusinessAgreement protocol. The PC assembler's sales module wants to register for the BusinessAgreement protocol. The WS-Transaction specification defines two BA protocols, BusinessAgreement and BusinessAgreementWithComplete.

11. The coordinator sends a RegisterResponse message (Listing 11) in response to the Register request of Listing 10.

Listing 11


<?xml version="1.0"?>
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:RegisterResponse
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousPCAssembler.com/sales
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinatorProtocolService>
                <wsu:Address> 
http://www.AFictitiousDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wscoor:CoordinatorProtocolService>
        </wscoor:RegisterResponse>
    </SOAP:Body>
</SOAP:Envelope>

12. Now the sales module of the PC Assembler is ready to perform an in-house AT to fulfill the requirements of supplying item 1 to the distributor. Notice that I'm assuming that the AT concludes successfully, so that the PC Assembler can tell the distributor that it can deliver item 1 on time.

The PC assembler registered for the BusinessAgreement protocol in step 10. This protocol means that the application registering for the protocol will immediately start working on the task, without waiting to receive any further instructions. That's why the sales module started working on the in-house AT immediately after getting registered.

On the other hand, if the sales module had registered for the BusinessAgreementWithComplete protocol, the coordinator would have sent a Complete message to the sales module, without which the sales module would not have started performing any work on the business task. This is the only difference between BusinessAgreement and BusinessAgreementWithComplete protocols. (In an attempt to match step numbers with listing numbers, I am omitting some listing numbers. There is neither a Listing nor a step 12.)

13. Now the PC Assembler's sales module sends a Completed message (Listing 13) to the purchase module of the distributor. Notice that Listing 13 contains only two child elements namely TargetProtocolService and SourceProtocolService. We have already discussed these two elements in point number 15 of the section Exchange of Messages in Atomic Transactions in the second article.

Listing 13


<?xml version="1.0"?>
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
    <SOAP:Body>
       <wsba:Completed
            xmlns:wsba="http://schemas.xmlsoap.org/ws/2002/08/wsba">
            <wsba:TargetProtocolService>
                <wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wsba:TargetProtocolService>
            <wsba:SourceProtocolService>
                <wsu:Address> 
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wsba:SourceProtocolService>
       </wsba:Completed>
      </SOAP:Body>
</SOAP:Envelope>

14--16. Listing 14, Listing 15, and Listing 16 perform the same operation for item 2 of the purchase order that Listing 9, Listing 10, and Listing 11 did for item 1. The distributor's purchase module sends an application specific message (Listing 14) to of the PC assembler's sales module and the sales module registers for the business activity (Listing 15 and Listing 16).

Listing 14


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
    xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
    <SOAP:Header>
        <wscoor:CoordinationContext>
             <wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item2OfPurchaseOrderActivity786
              </wsu:Identifier>
              <wscoor:CoordinationType>
                    http://schemas.xmlsoap.org/ws/2002/08/wsba
              </wscoor:CoordinationType>
              <wscoor:RegistrationService>
                  <wsu:Address>
                        http://www.AFictitiousDistributor.com/WSTM/registration
                  </wsu:Address>
              </wscoor:RegistrationService>
        </wscoor:CoordinationContext>
    </SOAP:Header>
    <SOAP:Body>
        <!--An application specific message from the distributor’s purchase module 
            to the PC assembler's sales module.-->
    </SOAP:Body>
</SOAP:Envelope>

Listing 15


<?xml version="1.0"?>
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:Register
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:RegistrationService>
                <wsu:Address>
                    http://www.AFictitiousPCDistributor.com/WSTM/registration
                <wsu:Address>
            </wscoor:RegistrationService>
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousPCAssembler.com/sales
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:ProtocolIdentifier>
                     http://schemas.xmlsoap.org/ws/2002/08/wsba/BusinessAgreement
            </wscoor:ProtocolIdentifier>
            <wscoor:ParticipantProtocolService>
                <wsu:Address> 
                    http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wscoor:ParticipantProtocolService>
       </wscoor:Register>
    </SOAP:Body>
</SOAP:Envelope>

Listing 16


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP:Body>
        <wscoor:RegisterResponse
            xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wscoor:RequesterReference>
                <wsu:Address>
                    http://www.AFictitiousPCAssembler.com/sales
                </wsu:Address>
            </wscoor:RequesterReference>
            <wscoor:CoordinatorProtocolService>
                <wsu:Address> 
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wscoor:CoordinatorProtocolService>
        </wscoor:RegisterResponse>
    </SOAP:Body>
</SOAP:Envelope>

17. Now is the time for the PC Assembler's sales module to perform an AT for item 2. Let's suppose that some of the components required to assemble item 2 are not available in the inventory, so the AT fails this time (i.e. the AT fails to commit and gets rolled back).

18. As the AT for item 2 was not successful, so the PC Assembler's sales module cannot send a Completed message to the distributor's purchase module. But the PC assembler's business logic does not want to give up an order just because the components required to fulfill the order are not in stock. It will try to get the components from their corresponding vendors. Therefore it sends business activity messages to other vendors. I have not shown the messages that the PC Assembler sends to component vendors; the entire messaging exchange between the PC Assembler and its vendors will be just like the messaging between the distributor and the assembler. You can imagine that the supply chain of this business activity is extended to include another link, that is, vendors that the PC Assembler wants to buy from. Let's assume that the PC assembler's business logic is successful in sourcing the required components from the vendors it usually buys from.

19. Now the PC assembler's sales module sends a Completed message (for the business activity related to item 2) to the distributor's purchase module. This message is shown in Listing 19.

Listing 19


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
    <SOAP:Body>
       <wsba:Completed
            xmlns:wsba="http://schemas.xmlsoap.org/ws/2002/08/wsba">
            <wsba:TargetProtocolService>
                <wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wsba:TargetProtocolService>
            <wsba:SourceProtocolService>
                <wsu:Address> 
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wsba:SourceProtocolService>
       </wsba:Completed>
      </SOAP:Body>
</SOAP:Envelope>

20--22. These steps are the same as 14, 15, and 16, but this time for item 3.

23. As readers might have already guessed, the PC assembler's sales module tries to perform an AT for item 3. Let's suppose that the AT fails again, due to unavailability of required components.

24. So the PC assembler's business logic contacts its vendors. Let's suppose the required components are not available even from the vendors.

25. Now the PC assembler knows there's no way it can fulfill the distributor's requirement for item 3. So it sends a Faulted message (Listing 25) to the distributor's purchase module. A Faulted message indicates that something went wrong while performing the business activity and the task could not be completed.

Listing 25


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
       <wsba:Faulted
            xmlns:wsba="http://schemas.xmlsoap.org/ws/2002/08/wsba"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wsba:TargetProtocolService>
                <wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wsba:TargetProtocolService>
            <wsba:SourceProtocolService>
                <wsu:Address> 
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wsba:SourceProtocolService>
       </wsba:Faulted>
      </SOAP:Body>
</SOAP:Envelope>

26. The distributor's purchase module now has updates on business activities related to all the three items (items 1 and 2 are available for supply from the PC Assembler, while item 3 is not). The purchase module will present all the information for the attention of a person in charge, perhaps a Purchase Manager. The Purchase Manager will assess the scenario and make decisions regarding the items that are not available according to the purchase order. He might want to try some other vendors to check the availability of the missing items. Let's suppose that the Purchase Manager is able to locate item 3 from some alternate source, but the alternate source is offering special prices in case items 1 and 3 are purchased together (instead of just the third item). So the Purchase Manager decides to buy items 1 and 3 from the alternate source and only item 2 from the PC Assembler.

27. The distributor's purchase module sends a Compensate message for item 1 to the PC assembler's sales module (refer to Listing 27). The Compensate message means that the sales module needs to undo what it did while completing its task. Recall from step 12 that the sales module performed an AT in order to fulfill the requirements of the bookOrder method call for item 1. Therefore, the sales module now needs to undo everything that was done while performing the AT.

Listing 27


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
        <wsba:Compensate
            xmlns:wsba="http://schemas.xmlsoap.org/ws/2002/08/wsba"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wsba:TargetProtocolService>
                <wsu:Address>
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wsba:TargetProtocolService>
            <wsba:SourceProtocolService>
                <wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wsba:SourceProtocolService>
       </wsba:Compensate>
      </SOAP:Body>
</SOAP:Envelope>

28. The PC Assembler's sales module undoes the AT.

29. After undoing the AT, the PC Assembler sends a Compensated message back to the distributor's sales module. This is the end of story for item 1. I have shown that the PC Assembler simply accepts this lost business opportunity. In real world business applications, there may be other types of compensative actions associated with such situations.

30. The distributor's purchase module sends a Close message for item 2 to the PC assembler's sales module. This message is like confirming the purchase of this item and, thus, equivalent to asking to close the business activity.

31. Recall from step 18 that the PC Assembler had engaged its vendors to get the components required to assemble item 2. The PC assembler's sales module according to its business logic finds out that in order to book this order, it needs to send confirmations to its vendors.

32. The PC Assembler's sales module sends Close messages to its vendors corresponding to the business activity related to item 2. I have not provided code listings to demonstrate messaging between the PC assembler and its vendors, but it is similar to the messaging that we have shown between the PC distributor and the PC assembler.

33. Now the PC Assembler's sales module sends a Closed message (Listing 33) back to the distributor's purchase module, thus confirming that the activity has been closed.

Listing 33


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
       <!-- PCAssembler responds "Closed" message for 
	       Item2 wrapped inside the SOAP body.-->
       <wsba:Closed
            xmlns:wsba="http://schemas.xmlsoap.org/ws/2002/08/wsba"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wsba:TargetProtocolService>
                <wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wsba:TargetProtocolService>
            <wsba:SourceProtocolService>
                <wsu:Address> 
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wsba:SourceProtocolService>
       </wsba:Closed>
      </SOAP:Body>
</SOAP:Envelope>

This is the end of story for this business activity for item 2. Some readers may object to ending the story with just the booking of an order, while logically this is just the start of a series of activities like manufacturing, packing, shipping etc. Well, we have ended the story only for the sake of simplicity. In actual practice, at this stage, a new child business activity will be generated for item 2, which will carry on until the order is delivered.

34. Now the distributor's purchase module sends a Forget message (Listing 34) to the PC Assembler's sales module for the activity related to item 3. Recall from step 25 that the PC assembler's sales module sent a Faulted message to the distributor's purchase module for item 3. A Forget message in response to a Faulted message is like saying "It's all right if you cannot perform the required activity, so just forget the request". This marks the end of business activity related to item 3.

Listing 34


<?xml version="1.0"?> 
<SOAP:Envelope
    xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
       <!-- Distributor sends "Forget" message for Faulted 
	       Item3 wrapped inside the SOAP body.-->
       <wsba:Forget
            xmlns:wsba="http://schemas.xmlsoap.org/ws/2002/08/wsba"
            xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
            <wsba:TargetProtocolService>
                <wsu:Address>
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
                </wsu:Address>
            </wsba:TargetProtocolService>
            <wsba:SourceProtocolService>
                <wsu:Address> 
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
                </wsu:Address>
            </wsba:SourceProtocolService>
       </wsba:Forget>
      </SOAP:Body>
</SOAP:Envelope>

An Ambiguity in the BA Specification

Before concluding this series of articles, I would like to briefly mention an ambiguity that I found while using the BA specification. This is purely my own point of view and authors of the BA specification may not agree with it.

If you look at Figure BA2 (BusinessAgreement Protocol State Diagram) and its associated explanation in section 12.1 of the WS-Transaction specification, you will notice that the diagram depicts communication between a participant and a coordinator, while the accompanying explanation discusses communication between a parent and a child. This creates confusion because a parent and its children may share the same coordinator. The BA process is effectively trying to achieve a hierarchical (parent-child) nesting of activities. In my view, the nested hierarchy should not be confused with the sequence of messages between a participant and a coordinator. These are two different concepts and should be treated independently of each other. The BA specification perhaps needs to improve on this point.

Conclusion

In this series of articles I have discussed XML-based transactions and their use in web services, demonstrating two types of XML transactions: Atomic Transactions and Business Activities. Both AT and BA represent coordinated activities. AT is an all-or-nothing activity, while BA is flexible. I have also demonstrated the use of BA on a higher level to divide the entire business logic as a hierarchy of small and easier to manage tasks. Finally, I have shown how you can represent the smallest unit of a coordinated activity as an AT.