This chapter discusses a business-to-business (B2B) e-commerce example illustrating a hypothetical supply chain relationship among a car dealer, the manufacturer, and a part supplier. This example is based on the one contained in [WS Architecture 2003]. The example shows how the Web services protocol stack enables secure, reliable, and transactional interactions in a B2B scenario. In this example, the dealer and supplier access Web services exposed by a car manufacturer, which enables them to efficiently maintain the supply of car parts that consumers need. The interactions also involve accessing internal applications, some of them exposed as Web services. Quality of service protocols are enabled in each of these interactions as required.
In this scenario, a car dealer has secure access to a manufacturer’s Web site so that he can order auto parts. The dealer can access the car manufacturer applications using a Web browser to place orders and to check the status of existing orders. The interaction requires the requester’s authentication with both the dealer and car manufacturer systems. After the dealer achieves authentication, he can access a Web service on the manufacturer’s site to retrieve order data and to place new orders.
The manufacturer, in turn, maintains a relationship with a parts supplier who is chartered with maintaining an appropriate supply of certain parts from the manufacturer’s inventory. With this purpose, the manufacturer and the supplier have entered into an agreement by which the supplier can check inventory levels and place orders on behalf of the manufacturer when levels fall below certain thresholds. To do this, the manufacturer provides direct access to its internal systems (the inventory systems in this case) through a secure Web service.
Finally, the supplier’s internal systems are Web service enabled to allow open integration among different platforms. To place an order (this time on behalf of this particular car manufacturer), the ordering application contacts the warehouse system, which is also exposed as a Web service, and transmits the order as an XML message. The warehouse application then divides the order between two provisioning systems used to fulfill orders.
The interactions among the parties are shown in the next three figures. Figure 15-1 illustrates the dealer-to-manufacturer relationship. Employees of the car dealer log on to the dealer’s intranet using their browser, and then are authenticated with the system. From the car dealer page, they are able to access the manufacturer ordering site. When this happens, credentials for the dealer employee are communicated following a WS-Federation protocol to the manufacturer, which directly authenticates and grants access to its ordering systems to the dealer’s employee.
At this point, the Web services–enabled browser can interact with the Web service that the car manufacturer provides for placing orders. The dealer’s Web service retrieves and updates information from the customer database at the manufacturer. It ensures integrity of the messages exchanged by using WS-Security to sign messages sent by both parties. In Figure 15-1, wide arrows show Web services–based interactions. These include the WS-Federation taking place between authentication systems at the dealer and manufacturer sites and the interaction between the Web service–enabled browser at the dealer and the ordering Web service at the manufacturer. Thin black arrows represent other interactions, such as traditional Web requests from a browser or database access to the manufacturer’s customer database.
The interaction between the supplier and the manufacturer is shown in Figure 15-2. Once again, one can see how WS-Federation allows employees who are using the supplier applications to access the car manufacturer services by logging into the supplier systems. This is because both the supplier and manufacturer have federated their authentication systems. Based on their supplier agreement, the supplier can access the status of inventories at the manufacturer and order additional supplies when levels are low. A Web service provides access to the inventory systems. WS-Security protects the integrity and confidentiality of messages that are exchanged between the supplier Web service access application and the inventory service.
Accessing the inventory system, the supplier employees detect low levels of a certain part. They place an order on behalf of the manufacturer into the supplier’s ordering system. This interaction is shown in Figure 15-3. The request goes to the internal warehouse system, transmitted reliably using WS-ReliableMessaging to ensure exactly-once delivery of orders. This guarantees that orders are not lost because of network failure or because of the temporal unavailability of any of the systems involved. The warehouse system works with two warehouse subsystems at the two production sites that the supplier maintains.
The company policy requires the two sites to divide the order in a certain way, so coordinated requests are sent to the warehouse systems at the two sites. To ensure that the complete order is fulfilled, the complete interaction is conducted transactionally using WS-AtomicTransactions. If one of the plants cannot provide the requested amount, both internal warehouse requests are cancelled, and the ordering application is informed of the error condition. The employee can then check inventories at the plants and, if needed, override the company policy to receive the supplies from whatever source is available.
This section explains how the description of the Web services involved in this scenario should be written. To focus on the fundamental aspects of the description, Web Services Description Language (WSDL) 1.1 service definitions are shown but the details of schema and policy definitions are omitted (the latter because the definition of policy assertion dialects is in an early stage). Note also that, for simplicity and readability, XML namespace declarations are omitted in this and in the next section’s examples, and we limit the use of namespace prefixes to element names. Thus, the examples are meant to be illustrative rather than executable.
This example has five services: the ordering service and inventory checking at the car manufacturer, and the ordering services at the warehouse systems at the supplier (the one where orders are sent, and one in each of the two production plants). All three warehouse Web services implement the same port type.
The port type of the ordering Web service at the manufacturer provides three operations: retrieving the list of outstanding orders, checking the status of an order, and placing a new order:
<definitions targetNamespace="...">
<!-- WSDL definitions in this document -->
<!-- referenced using "mfr" prefix -->
<types>
<xsd:schema>
<!-- XSD definitions for this service -->
<!-- referenced using "mfx" prefix -->
<xsd:import namespace=
"http://www.car-
manufacturer.com/xsd/customer"/>
</xsd:schema>
</types>
<message name="customerID">
<part name="customer" element="mfx:custID"/>
</message>
<message name="orderID">
<part name="order" element="mfx:orderID"/>
</message>
<message name="orderInfo">
<part name="order" element="mfx:orderInfo"/>
</message>
<message name="orderList">
<part name="ID" element="mfx:orderList"/>
</message>
<portType name="partOrderPortType">
<operation name="requestOrderList">
<input message="mfr:customerID"/>
<output message="mfr:orderList"/>
</operation>
<operation name="requestOrderStatus">
<input message="mfr:orderID"/>
<output message="mfr:orderInfo"/>
</operation>
<operation name="newOrder">
<input message="mfr:orderInfo"/>
<output message="mfr:orderID"/>
<fault name="notAccepted" message="mfr:orderFault"/>
</operation>
</portType>
<binding name="partOrderBinding"
type="mfr:partOrderPortType">
<wsp:PolicyReference URI=
"http://www.car-manufacturer.com/policies/DSig"/>
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
</binding>
<service name="partOrderService">
<port name="partOderPort" binding="mfr:partOrderBinding">
<soap:address location=
"http://www.car-manufacturer/partOrder-svc"/>
</port>
</service>
</definitions>
Note that these three operations use four WSDL message definitions. Two—customerID and orderID—are used for customer and order identification. The orderInfo message encodes all information necessary to place an order and is used to transmit order information and status, also. A list of orders is encoded as an orderList message, which relies on a schema element definition containing a variable number of orderInfo elements. Note also that the binding that the service provides is a SOAP document/literal-style binding.
The manufacturer offers a second service, this time to its parts supplier. This service offers a single operation for retrieving the list of parts and the inventory levels for each of them. Access to this service requires both the digital signing and encryption of the bodies of the messages that are exchanged. This is expressed in the next block of code by the two policy attachment elements in the port type binding.
<definitions targetNamespace="...">
<!-- WSDL definitions in this document -->
<!-- referenced using "mfr" prefix -->
<types>
<xsd:schema>
<!-- XSD definitions for this service -->
<!-- referenced using "mfx" prefix -->
<xsd:import namespace=
"http://www.car-manufacturer.com/xsd/inventory"/>
</xsd:schema>
</types>
<message name="supplierID">
<part name="suppplier" element="mfx:supplierID"/>
</message>
<message name="inventoryList">
<part name="ID" element="mfx:inventoryList"/>
</message>
<portType name="inventoryPortType">
<operation name="requestInventoryList">
<input message="mfr:supplierID"/>
<output message="mfr:inventoryList"/>
</operation>
</portType>
<binding name="inventoryBinding"
type="mfr:inventoryPortType">
<wsp:PolicyReference URI=
"http://www.car-manufacturer.com/policies/DSig"/>
<wsp:PolicyReference URI=
"http://www.car-manufacturer.com/policies/Encrypt"/>
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
</binding>
<service name="inventoryService">
<port name="partOderPort" binding="mfr:inventoryBinding">
<soap:address location=
"http://www.car-manufacturer/inventory-svc"/>
</port>
</service>
</definitions>
Finally, all the internal warehouse systems at the supplier implement the same warehouse order port type. The port type offers a one-way “warehouseOrder” operation, which is shown in the definition that follows for the central warehouse service. For completeness and to support the message examples included in the next section, we also provide XML Schema element definitions for the service.
<definitions targetNamespace="...">
<!-- WSDL definitions in this document -->
<!-- referenced using "spl" prefix -->
<types>
<xsd:schema targetNamespace="...">
<!-- XSD definitions in this document -->
<!-- referenced using "spx" prefix -->
<xsd:element="warehouseOrder">
<xsd:complexType>
<xsd:complexContent>
<xsd:sequence>
<xsd:element name="Date" type="xsd:date"/>
<xsd:element name="Originator"
type="xsd:anyURI"/>
<xsd:element name="CustomerId"
type="xsd:string"/>
<xsd:element name="ItemNo"
type="xsd:unsignedLong"/>
<xsd:element name="Qty"
type="xsd:unsignedLong"/>
</xsd:sequence>
</xsd:complexContent>
<xsd:complexType>
<xsd:element>
</xsd:schema>
</types>
<message name="warehouseOrder">
<part element="spx:warehouseOrder"/>
</message>
<portType name="warehouseOrderingPortType">
<operation name="placeOrder">
<input message="spl:warehouseOrder"/>
</operation>
</portType>
<binding name="reliableWarehouseBinding"
type="spl:warehouseOrderingPortType">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsp:PolicyReference URI=
"http://www.supplier.com/policies/ReliableMsgPolicy"/>
</binding>
<service name="warehouseOrderService">
<port name="warehouseorderPort"
binding="spl:reliableWarehouseBinding">
<soap:address location=
"http://www.car-manufacturer/inventory-svc"/>
</port>
</service>
</definitions>
The receiving warehouse responds to the requesting application that sent the order message with a confirmation or an error message, which is sent back asynchronously. (We do not include here the definition of the port type where these messages are received.) The bindings for all warehouse services have attached policies to indicate that certain QoS protocols must be followed. As shown in the preceding service definition, the initial order is transmitted to the central warehouse service over a reliable connection using WS-Reliable Messaging. The binding attaches a policy that requires the use of the WS-Reliable Messaging protocol when the service is accessed.
This section provides an overview of how the interactions that are carried out in this example and the specific QoS protocols that are required in each case appear on the wire as SOAP messages. First, note that all SOAP messages that are exchanged in this example are encoded according to the document-literal model. Also, in every case, the WS-Addressing specification dictates a certain set of mandatory headers to be used. Each specific QoS protocol that is used requires particular headers to be encoded. Because the basic elements are common in all the messages that are exchanged, we will show one full example and then indicate the modifications introduced in each specific exchange.
The initial interaction between the Web services–enabled browser at the dealer and the order service at the manufacturer uses digital signatures to protect message integrity. The interaction between the supplier and the manufacturer inventory service, on the other hand, requires that the messages also be encrypted. The request message used in this interaction incorporates both a digital signature and an encryption section in its WS-Security SOAP header. A sample message is shown next. Again, note that we have omitted namespace declarations; we have also removed most of the digital data corresponding to the digital signature and encrypted body for readability.
<S:Envelope>
<S:Header>
<wsa:To>
http://www.car-manufacturer.com/inventory-svc
</wsa:To>
<wsa:Action>
http://www.car-manufacturer.com/svcs/
inventoryPortType/requestInventoryListRequest
</wsa:Action>
<wsa:ReplyTo>
<wsa:Address>
http://schemas.xmlsoap.org/ws/2004/03/
addressing/role/anonymous
</wsa:Address>
</wsa:ReplyTo>
<wsse:Security>
<wsse:UsernameToken Id="Username">
<wsse:Username>
CN=Joe, OU=ordering-system,O=supplier.com, C=US
</wsse:Username>
</wsse:UsernameToken>
<xenc:EncryptedKey Id="SecretKey">
<xenc:EncryptionMethod Algorithm=
"http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
<dsig:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Reference URI="#Username"/>
</wsse:SecurityTokenReference>
</dsig:KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>
HGRO3csrbtFLtMP3iC+s0r/...
</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedKey>
<xenc:ReferenceList>
<xenc:DataReference URI="#BodyContent" />
</xenc:ReferenceList>
</wsse:Security>
</S:Header>
<S:Body>
<xenc:EncryptedData Id="BodyContent">
<xenc:EncryptionMethod Algorithm=
"http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
<dsig:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Reference URI="#SecretKey" />
</wsse:SecurityTokenReference>
</dsig:KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>
F0LXfmjBbaiRtn4I86CVMlrXMgm7OwC0Sf...
</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedData>
</S:Body>
</S:Envelope>
Observe how the body is encrypted inside an EncryptedData element. Note also the presence of the mandatory WS-Addressing headers—To, Action, and ReplyTo (because this is a request response interaction)—and how the anonymous URI is used in the Address field of the ReplyTo header to indicate that the response needs to be sent back synchronously over the open HTTP connection.
The message exchanges inside the supplier’s enterprise network are not secured; however, different protocols ensure reliable processing of the order. First, the order message sent by the ordering application to the central warehouse Web service is exchanged using the reliable messaging protocol. A reliable messaging sequence header is used in this case, and the body is not encrypted.
<S:Envelope>
<S:Header>
<wsa:To>
http://www.supplier.com/warehouse/orders-svc
</wsa:To>
<wsa:Action>
http://www.supplier.com/warehouse/svcs/warehouseOrderingPortType/placeOrderRequest
</wsa:Action>
<wsa:ReplyTo>
<wsa:Address>
http://www.supplier.com/requests/callback
</wsa:Address>
</wsa:ReplyTo>
<rm:Sequence S:mustUnderstand="1">
<util:Identifier>
http://www.supplier.com.com/warehouse#0936987027956930
</util:Identifier>
<rm:MessageNumber>1</rm:MessageNumber>
</rm:Sequence>
<rm:AckRequested>
<util:Identifier>
http://www.supplier.com.com/warehouse#0936987027956930
</rm:Identifier>
<rm:MessageNumber>1</rm:MessageNumber>
</rm:AckRequested>
</S:Header>
<S:Body>
<spx:warehouseOrder>
<spx:Date>2005-10-01</spl:Date>
<spx:Originator>
http://www.supplier.com/sales-id=67
</spl:Originator>
<spx:CustomerId>751-CarM</spl:CustomerId>
<spx:ItemNo>72519-GFa</spl:ItemNo>
<spx:Qty>50</spl:Qty>
</spx:warehouseOrder>
</S:Body>
</S:Envelope>
Observe that this ReplyTo address does not contain the anonymous URI (indicating, for instance, that one must not send the response over the current connection). Because the confirmation message is sent asynchronously, the ReplyTo endpoint reference must contain an actual address to send the response. The use of the reliable messaging protocol results in two additional headers in this message: the mandatory Sequence header identifying this as the first message in the reliable message sequence, and the AckRequested header requesting that an acknowledgement be returned to the originator of the message.
Finally, the orders that the central warehouse sends to the supplier production plants are executed as an atomic transaction, because they involve coordinated updates in the systems at the two plants. The central warehouse application initiates an atomic transaction, and the coordination service at the central warehouse initiates an exchange with the coordinators at the two plant warehouses. A coordination context in the messages exchanged supports the atomic protocol in this case. Following is one sample application message that the warehouse central service sends to the warehouse service in Plant 1, which carries the coordination context header message that the WS-AtomicTransaction protocol uses. A more complete example of the message’s exchange in an interaction of this kind is provided in Chapter 16, “Case Study: Ordering Service Packs.”
<S:Envelope>
<S:Header>
<wsa:To>
http://www.supplier.com/warehouse-1/orders-svc
</wsa:To>
<wsa:Action>
http://www.supplier.com/warehouse/svcs/warehouseOrderingPortType/placeOrderRequest
</wsa:Action>
<wsa:ReplyTo>
<wsa:Address>
http://www.suplier.com/warehouse/callback
</wsa:Address>
</wsa:ReplyTo>
<wsc:CoordinationContext>
<util:Identifier>
http://www.supplier.com/00000000000FF4A64A2CA0902122F00
</util:Identifier>
<wsc:CoordinationType>
http://schemas.xmlsoap.org/ws/2003/09/wsat
</wsc:CoordinationType>
<wsc:RegistrationService>
<wsa:Address>
http://www.supplier.com/warehouse/registrationCoordinator
</wsa:Address>
<wsa:ReferenceProperties>
<spl-tx:TransactionId>
http://www.supplier.com/00000000000FF4A64A2CA0902122F00
</spl-tx:TransactionId>
</wsa:ReferenceProperties>
</wsc:RegistrationService>
</wsc:CoordinationContext>
</S:Header>
<S:Body>
<spl:warehouseOrder>
<spl:Date>01102005</spl:Date>
<spl:Originator>
http://www.supplier.com/warehouse-central
</spl:Originator>
<spl:CustomerId>751-CarM</spl:CustomerId>
<spl:ItemNo>72519-GFa</spl:ItemNo>
<spl:Qty>25</spl:Qty>
</spl:warehouseOrder>
</S:Body>
</S:Envelope>
This chapter illustrated the use of SOAP, WSDL, WS-Addressing, WS-Policy, WS-Security, WS-ReliableMessaging, and WS-AtomicTransaction to address a B2B integration scenario. The example does not include a discussion of what implementation platform or technology any of the parties use. That’s because Web services works at a level above that and provides a clean architecture for building integrated B2B applications.