Web Services Architecture Usage Scenarios

Editors' copy $Date: 2002/06/24 12:29:37 $ 19 June 2002

This version:
http://www.w3.org/2002/ws/arch/2/ws-arch-scenarios-20020619 (XML version and HTML version)
Latest version:
http://www.w3.org/TR/ws-arch-scenarios/
Previous version:
http://www.w3.org/2002/ws/arch/2/wd-wsawg-scenarios-05012002
Editors:
Allen Brown, Microsoft
Roger Cutler, ChevronTexaco
Hugo Haas, W3C
John Ibbotson, IBM
David Orchard, BEA Systems

Abstract

This document describes the Web Service Architecture Usage Scenarios.

Status of this Document

This document is an editors' copy that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This is a public draft of a document that the Web Services Architecture Working Group intends to eventually publish as a Working Draft.

For a detailed list of changes since the last publication of this document, refer to appendix A Part 1 Change Log . A list of open issues against this document is maintained by the Working Group.

Comments on this document should be sent to www-wsa-comments@w3.org ( public archive ). It is inappropriate to send discussion emails to this address.

Discussion of this document takes place on the public www-ws-arch@w3.org mailing list ( public archives ) per the email communication rules in the Web Services Architecture Working Group Charter

Table of Contents

1 Introduction
2 Usage Scenarios
2.1 S001 Fire-and-forget to single receiver
2.1.1 Scenario Definition
2.1.2 Description
2.2 S002 Fire-and-forget to multiple receivers
2.2.1 Scenario Definition
2.2.2 Description
2.3 S003 Request/Response
2.3.1 Scenario Definition
2.3.2 Description
2.4 S004 Remote Procedure Call (RPC)
2.4.1 Scenario Definition
2.4.2 Description
2.5 S006 Multiple Faults
2.5.1 Scenario Definition
2.5.2 Description
2.5.3 WS-Arch WG Specific
2.5.3.1 Requirements
2.5.3.2 Non-requirements
2.5.3.3 Priority, Effort
2.6 S007 Multiple asynchronous responses
2.6.1 Scenario Definition
2.6.2 Description
2.7 S010 Request with acknowledgement
2.7.1 Scenario Definition
2.7.2 Description
2.7.3 WS-Arch WG Specific
2.7.3.1 Requirements
2.7.3.2 Non-requirements
2.7.3.3 Candidate Technologies
2.7.3.4 Priority, Effort
2.8 S030 Third party intermediary
2.8.1 Scenario Definition
2.8.2 Description
2.9 S031 Communication via multiple intermediaries
2.9.1 Scenario Definition
2.9.2 Description
2.10 S032 Caching
2.10.1 Scenario Definition
2.10.2 Description
2.11 S035 Routing
2.11.1 Scenario Definition
2.11.2 Description
2.12 S036 Tracking
2.12.1 Scenario Definition
2.12.2 Description
2.13 S037 Caching with expiration
2.13.1 Scenario Definition
2.13.2 Description
2.14 S040 Conversational message exchange
2.14.1 Scenario Definition
2.14.2 Description
2.14.3 WS-Arch WG Specific
2.14.3.1 Requirements
2.14.3.2 Non-requirements
2.14.3.3 Candidate Technologies
2.14.3.4 Priority, Effort
2.15 S061 Request with encrypted payload
2.15.1 Scenario Definition
2.15.2 Description
2.15.3 WS-Arch WG Specific
2.15.3.1 Requirements
2.15.3.2 Non-requirements
2.15.3.3 Candidate Technologies
2.15.3.4 Priority, Effort
2.16 S062 Message header and payload encryption
2.16.1 Scenario Definition
2.16.2 Description
2.17 S063 Authentication
2.17.1 Scenario Definition
2.17.2 Description
2.17.3 WS-Arch WG Specific
2.17.3.1 Requirements
2.17.3.2 Non-requirements
2.17.3.3 Candidate Technologies
2.17.3.4 Priority, Effort
2.18 S064 Message Integrity
2.18.1 Scenario Definition
2.18.2 Description
2.18.3 WS-Arch WG Specific
2.18.3.1 Requirements
2.18.3.2 Non-requirements
2.18.3.3 Candidate Technologies
2.18.3.4 Priority, Effort
2.19 S070 Asynchronous messaging
2.19.1 Scenario Definition
2.19.2 Description
2.19.3 WS-Arch WG Specific
2.19.3.1 Requirements
2.19.3.2 Non-requirements
2.19.3.3 Candidate Technologies
2.19.3.4 Priority, Effort
2.20 S071 Asynch/Synchronous specificity
2.20.1 Scenario Definition
2.20.2 Description
2.20.3 WS-Arch WG Specific
2.20.3.1 Requirements
2.20.3.2 Non-requirements
2.20.3.3 Priority, Effort
2.21 S080 Transaction
2.21.1 Scenario Definition
2.21.2 Description
2.21.3 WS-Arch WG Specific
2.21.3.1 Requirements
2.21.3.2 Non-requirements
2.21.3.3 Candidate Technologies
2.21.3.4 Priority, Effort
2.22 S090 Sending non-XML data
2.22.1 Scenario Definition
2.22.2 Description
2.22.3 WS-Arch WG Specific
2.22.3.1 Requirements
2.22.3.2 Non-requirements
2.22.3.3 Candidate Technologies
2.22.3.4 Priority, Effort
2.23 S091 Incremental parsing/processing of SOAP messages
2.23.1 Scenario Definition
2.23.2 Description
2.24 S092 Streaming Response
2.24.1 Scenario Definition
2.24.2 Description
2.24.3 WS-Arch WG Specific
2.24.3.1 Requirements
2.24.3.2 Non-requirements
2.24.3.3 Candidate Technologies
2.24.3.4 Priority, Effort
2.25 S200 Event notification
2.25.1 Scenario Definition
2.25.2 Description
2.26 S201 Event Management Model
2.26.1 Scenario Definition
2.26.2 Description
2.26.3 WS-Arch WG Specific
2.26.3.1 Requirements
2.26.3.2 Non-requirements
2.26.3.3 Priority, Effort
2.27 S300 System Messages
2.27.1 Scenario Definition
2.27.2 Description
2.27.3 WS-Arch WG Specific
2.27.3.1 Requirements
2.27.3.2 Non-requirements
2.27.3.3 Candidate Technologies
2.27.3.4 Priority, Effort
2.28 S500 Service Metadata
2.28.1 Scenario Definition
2.28.2 Description
2.28.3 WS-Arch WG Specific
2.28.3.1 Requirements
2.28.3.2 Non-requirements
2.28.3.3 Priority, Effort
2.29 S501 Service Level attributes
2.29.1 Scenario Definition
2.29.2 Description
2.29.3 WS-Arch WG Specific
2.29.3.1 Requirements
2.29.3.2 Non-requirements
2.29.3.3 Priority, Effort
2.30 S502 Operation Level attributes
2.30.1 Scenario Definition
2.30.2 Description
2.30.3 WS-Arch WG Specific
2.30.3.1 Requirements
2.30.3.2 Non-requirements
2.30.3.3 Priority, Effort
2.31 S503 Namespaces with data and interfaces
2.31.1 Scenario Definition
2.31.2 Description
2.31.3 WS-Arch WG Specific
2.31.3.1 Requirements
2.31.3.2 Non-requirements
2.31.3.3 Priority, Effort
2.32 S504 Versioning
2.32.1 Scenario Definition
2.32.2 Description
2.32.3 WS-Arch WG Specific
2.32.3.1 Requirements
2.32.3.2 Non-requirements
2.32.3.3 Priority, Effort
2.33 S505 Classification system for operations
2.33.1 Scenario Definition
2.33.2 Description
2.33.3 WS-Arch WG Specific
2.33.3.1 Requirements
2.33.3.2 Non-requirements
2.33.3.3 Priority, Effort
2.34 S510 Quality of service
2.34.1 Scenario Definition
2.34.2 Description
2.35 S600 Address based Discovery
2.35.1 Scenario Definition
2.35.2 Description
2.35.3 WS-Arch WG Specific
2.35.3.1 Requirements
2.35.3.2 Non-requirements
2.35.3.3 Candidate Technologies
2.35.3.4 Priority, Effort
2.36 S601 Registry based discovery
2.36.1 Scenario Definition
2.36.2 Description
2.36.3 WS-Arch WG Specific
2.36.3.1 Requirements
2.36.3.2 Non-requirements
2.36.3.3 Candidate Technologies
2.36.3.4 Priority, Effort
2.37 S Template
2.37.1 Scenario Definition
2.37.2 Description
2.37.3 WS-Arch WG Specific
2.37.3.1 Requirements
2.37.3.2 Non-requirements
2.37.3.3 Candidate Technologies
2.37.3.4 Priority, Effort
3 Use cases
3.1 Travel agent use case
3.1.1 Description
3.1.2 Scope
3.1.3 Stakeholders / Interests
3.1.4 Actors & Goals
3.1.5 Usage scenarios
3.1.5.1 1. User requests availabilities about some travel dates
3.1.5.1.1 Goal / Context
3.1.5.1.2 Scenario / Steps
3.1.5.1.3 Extensions
3.1.5.1.4 Technologies / Requirements
3.1.5.2 2. User requests chooses flight and looks for hotels
3.1.5.2.1 Goal / Context
3.1.5.2.2 Scenario / Steps
3.1.5.2.3 Extensions
3.1.5.2.4 Technologies / Requirements
3.1.5.3 3. User books hotel room and flight
3.1.5.3.1 Goal / Context
3.1.5.3.2 Scenario / Steps
3.1.5.3.3 Extensions
3.1.5.3.4 Technologies / Requirements
3.1.5.4 Notes on the scenario
3.2 EDI-like purchasing
3.2.1 Description
3.2.2 Scope
3.2.3 Stakeholders / Interests
3.2.4 Actors & Goals
3.2.5 Use Cases
3.2.5.1 1. Typical Widget Purchase
3.2.5.1.1 Goal / Context
3.2.5.1.2 Scenario / Steps
3.2.5.1.3 Extensions
3.2.5.1.4 Technologies / Requirements
3.2.5.2 2. Transaction Log Mismatch
3.2.5.2.1 Goal / Context
3.2.5.2.2 Scenario / Steps
3.2.5.2.3 Extensions
3.2.5.2.4 Technologies / Requirements
3.2.5.3 3. SmallCo Incorrectly Thinks They Weren't Paid
3.2.5.3.1 Goal / Context
3.2.5.3.2 Scenario / Steps
3.2.5.3.3 Extensions
3.2.5.3.4 Technologies / Requirements
3.2.5.4 4. SmallCo Really Wasn't Paid
3.2.5.4.1 Goal / Context
3.2.5.4.2 Scenario / Steps
3.2.5.4.3 Extensions
3.2.5.4.4 Technologies / Requirements
4 References
4.1 Informative References

Appendix

A Part 1 Change Log (Non-Normative)
A.1 Web Services Architecture Usage Scenarios Changes


1 Introduction

This document specifies a variety of web services usage scenarios. It is organized roughly as:

  1. S0**: Message exchange patterns, ie rpc, asynchrony, security, reliablity, conversations

  2. S2**: Event based message exchange patterns

  3. S3**: System and other messages

  4. S5**: Service Description above and beyond those in less than 5** numbers

  5. S6**: Discovery.

2 Usage Scenarios

2.1 S001 Fire-and-forget to single receiver

2.1.1 Scenario Definition

A sender wishes to send an unacknowledged message to a single receiver (e.g. send a stock price update every 15 minutes).

2.1.2 Description

Figure 1 Fire-and-forget to single receiver

A fire-and-forget feature in scenario S1 requires a mechanism to send a message to a single SOAP Receiver and is illustrated in Figure 1. The SOAP Sender does not require any status information that the message has been sent to or received by the recipient. The underlying transport protocol may implement a response mechanism, but status on whether the message was successfully sent or otherwise is not returned to the sending SOAP Processor.

Example: Fire-and-forget SOAP message
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>        
    <r:StockPriceUpdate xmlns:r="http://example.org/2001/06/quotes">
      <r:Symbol>BigCo</r:Symbol>
      <r:Price>34.5</r:Price>
    </r:StockPriceUpdate>
  </env:Body>
</env:Envelope>

2.2 S002 Fire-and-forget to multiple receivers

2.2.1 Scenario Definition

A sender wishes to send unacknowledged messages to a set of receivers (e.g. send a stock price update every 15 minutes).

2.2.2 Description

Figure 2 Fire-and-forget to multiple receivers

Scenario S2 extends S1 to implement a fire-and-forget feature to multiple SOAP Receivers and is illustrated in Figure 2. This requires a mechanism to deliver the same message to multiple SOAP Receivers. The delivery of the messages could be implemented using multicast distribution technology if the underlying transport layer supports this. An alternative implementation may use repeated applications of scenario S1 with a distribution list of intended recipients.

2.3 S003 Request/Response

2.3.1 Scenario Definition

Two parties wish to conduct electronic business by the exchange of business documents. The sending party packages one or more documents into a request message, which is then sent to the receiving party. The receiving party then processes the message contents and responds to the sending party. Examples of the sending party's documents may be purchase order requests, manufacturing information and patient healthcare information. Examples of the receiving party's responses may include order confirmations, change control information and contractual acknowledgements.

2.3.2 Description

Scenario S3 requires a request/response message feature. A request containing some business document is sent by a SOAP Sender to a SOAP Receiver where some business application is invoked. The business application processes the request and generates a response, which is returned to the SOAP Sender that originated the request. Two alternative solutions are described which depend upon the characteristics of the underlying transport layer. In either case, the SOAP Sender is informed of the status (successful or otherwise) of the request message delivery.

Figure 3 Request/Response using underlying transport

If the underlying transport protocol supports the correlation of a request and its matching response directly, then the solution illustrated in Figure 3 may be appropriate. An example of such an underlying transport protocol would be a synchronous HTTP POST. This implementation would make use of the transport binding proposed in other XML Protocol WG documents. The business document sent as a request by the SOAP Sender would be inserted as the payload of the request message. Following the receipt of the request, the processing application would generate a document which would be returned as the payload of the response message with appropiate status codes. If for whatever reason, the request message was not received or processed by the intended business application, suitable status messages would be generated by the underlying transport layer and reported to the SOAP Sender.

Figure 4 Request/Response using SOAP headers

If the underlying transport protocol does not support a request/response model, then the configuration shown in Figure 4 may be appropriate. Examples of such an underlying protocol may include unidirectional queuing middleware. In this case, message identification and correlation is provided by SOAP Headers. In the request SOAP message, a Message Identifier Handler is responsible for generating a unique message identifier and inserting it into a SOAP Header. This forms part of the SOAP request message and is sent from SOAP Application 1 to the receiving SOAP Application 2. The request message is processed by a business application and a response message is assembled. This includes a SOAP Header built by a Message Correlation Handler which links the response message to its associated request.

Example: SOAP request message containing a message identifier
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <n:MessageId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:MessageId>
    </n:MsgHeader>
  </env:Header>
  <env:Body>
      ........
  </env:Body>
</env:Envelope>
Example: SOAP response message containing correlation to original request
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <n:MessageId>uuid:09233523-567b-2891-b623-9dke28yod7m9</n:MessageId>
      <n:ResponseTo>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:ResponseTo>
    </n:MsgHeader>
  </env:Header>
  <env:Body>
      ........
  </env:Body>
</env:Envelope>

2.4 S004 Remote Procedure Call (RPC)

2.4.1 Scenario Definition

The sender invokes the service by passing parameters that are serialized into a message for transmission to the receiving server.

2.4.2 Description

Scenario S4 differs from scenario S3 in that the request message consists of a set of serialized parameters used to invoke some remote procedure which responds with a set of results. This is a different programming model to the document exchange one illustrated by scenario S3. Scenario S4 requires a request/response mechanism as in S3, with the parameter and result serialization needed for the RPC programming model form the SOAP Body element.

Figure 5 RPC using underlying transport

Figure 5 illustrates an RPC invocation over an underlying transport protocol such as HTTP that supports request/response. In this case, no additional headers are needed to correlate the request and response messages. Example request and response SOAP messages are:

Example: SOAP RPC request message
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <r:GetLastTradePrice env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
                            xmlns:r="http://example.org/2001/06/quotes">
      <r:Symbol>DEF</r:Symbol>
    </r:GetLastTradePrice>
  </env:Body>
</env:Envelope>
Example: SOAP RPC response message
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <r:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
                            xmlns:r="http://example.org/2001/06/quotes"
                            xmlns:rpc="http://www.w3.org/2001/09/soap-rpc">
      <rpc:Result>34.5</rpc:Result>
    </r:GetLastTradePriceResponse>
  </env:Body>
</env:Envelope>
Figure 6 RPC using SOAP headers

In Figure 6, the underlying transport protocol does not support request/response directly. The RPC request and response elements again form the Body of the SOAP messages. Correlation of the request and response is provided by the Message Identifier and Message Correlation handlers as described in scenario S3.

Example: SOAP RPC request message with message identification
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <n:MessageId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:MessageId>
    </n:MsgHeader>
  </env:Header>
  <env:Body>
    <r:GetLastTradePrice env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
                            xmlns:r="http://example.org/2001/06/quotes">
      <r:Symbol>DEF</r:Symbol>
    </r:GetLastTradePrice>
  </env:Body>
</env:Envelope>
Example: SOAP RPC response message containing correlation to original request
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <n:MessageId>uuid:09233523-567b-2891-b623-9dke28yod7m9</n:MessageId>
      <n:ResponseTo>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:ResponseTo>
    </n:MsgHeader>
  </env:Header>
  <env:Body>        
    <r:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
                                    xmlns:r="http://example.org/2001/06/quotes"
                                    xmlns:rpc="http://www.w3.org/2001/09/soap-rpc">
      <rpc:Result>34.5</rpc:Result>
    </r:GetLastTradePriceResponse>
  </env:Body>
</env:Envelope>

2.5 S006 Multiple Faults

2.5.1 Scenario Definition

Declaration of a method that raises multiple faults

2.5.2 Description

A web service interface method can fail due to several reasons. The faults raised by the method may be semantically different from each other and further more, some of the faults may be standard faults defined for a group of web services. For example, in an accounting system, there may be a general "creation fault" defined for indicating the failure such as out of resources or PO already exists. The creation of PO could also fail because the data provided to initialize the PO is invalid. The web service method "createPO" might then fail because of any of the reasons described above and may want to raise separate faults depending on the reason for failure.

2.5.3 WS-Arch WG Specific

2.5.3.1 Requirements

2.5.3.2 Non-requirements

2.5.3.3 Priority, Effort

2.6 S007 Multiple asynchronous responses

2.6.1 Scenario Definition

An application requests some information from a server, which is returned at a later time in multiple responses. This can be because the requested information was not available all at once (e.g., distributed web searches).

2.6.2 Description

Figure 16 Multiple asynchronous responses

Scenario S20 is an extension of scenario DS17 - asynchronous messaging. Instead of a single response message, more than one can be sent by the receiving application to the originator. A simple architecture would be the same as DS17 with multiple responses received by the originating application and corelated to the original request by a Message Correlation Handler. Figure 15 illustrates an extension to this using a Sequence Handler. The Sequence Handler ensures that a unique sequence number is added to each response message. If the responding application knows in advance that there will be a fixed number of multiple responses, then the Sequence Handler may use an N of M format to indicate how many response messages are to be expected.

Example: SOAP request message containing a message identifier
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <n:MessageId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:MessageId>
    </n:MsgHeader>
  </env:Header>
  <env:Body>
    ........        
  </env:Body>
</env:Envelope>
Example: First SOAP response message containing sequencing and correlation to original request
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <!-- MessageId will be unique for each response message -->
      <!-- ResponseTo will be constant for each response message in the sequence-->
      <n:MessageId>uuid:09233523-567b-2891-b623-9dke28yod7m9</n:MessageId>
      <n:ResponseTo>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:ResponseTo>
    </n:MsgHeader>
    <s:Sequence xmlns:s="http://example.org/sequence">
      <s:SequenceNumber>1</s:SequenceNumber>
      <s:TotalInSequence>5</s:TotalInSequence>
    </s:Sequence>
  </env:Header>
  <env:Body>
    ........        
  </env:Body>
</env:Envelope>
Example: Final SOAP response message containing sequencing and correlation to original request
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <!-- MessageId will be unique for each response message -->
      <!-- ResponseTo will be constant for each response message in the sequence-->
      <n:MessageId>uuid:40195729-sj20-pso3-1092-p20dj28rk104</n:MessageId>
      <n:ResponseTo>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:ResponseTo>
    </n:MsgHeader>
    <s:Sequence xmlns:s="http://example.org/sequence">
      <s:SequenceNumber>5</s:SequenceNumber>
      <s:TotalInSequence>5</s:TotalInSequence>
    </s:Sequence>
  </env:Header>
  <env:Body>
    ........        
  </env:Body>
</env:Envelope>

2.7 S010 Request with acknowledgement

2.7.1 Scenario Definition

A sender wishes to reliably exchange data with a receiver. It wishes to be notified of the status of the data delivery to the receiver. The status may take the form of:

  1. The data has been successfully delivered to the receiver, or

  2. Some failure has occurred which prevents the successful delivery to the receiver.

2.7.2 Description

Figure 7 Request with acknowledgement

Figure 7 illustrates a request/response scenario with the SOAP Sender requesting status information from the matching SOAP Receiver. This status may provide delivery information to the sender in addition to other business related responses that the receiving application may generate. Figure 7 assumes that the underlying transport protocol supports the request/response exchange model. A Status Handler is registered with the SOAP Sender and configured to request the status information. A matching handler on the SOAP Receiver generates the requested status information and places it in the response message which is then returned to the originating SOAP Sender.

In the example SOAP messages below, a StatusRequest header element includes an identifier for the message being sent. The inclusion of the StatusRequest header results in the receiving SOAP processor including a StatusResponse Header in the response. This includes information about the delivered message including an enumerated status and timestamp.

Example: SOAP request message with staus request header
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:StatusRequest xmlns:n="http://example.org/status">
      <n:MessageId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:MessageId>
    </n:StatusRequest>
  </env:Header>
  <env:Body>
    -----
  </env:Body>
</env:Envelope>
Example: SOAP response message containing delivery status for request
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:StatusResponse xmlns:n="http://example.org/status">
      <n:MessageId>uuid:09233523-567b-2891-b623-9dke28yod7m9</n:MessageId>
      <n:MessageStatus>DELIVERED</n:MessageStatus>
      <n:Timestamp>2001-03-09T12:22:30Z</n:Timestamp>
    </n:StatusResponse>
  </env:Header>
  <env:Body>        
    -----
  </env:Body>
</env:Envelope>

2.7.3 WS-Arch WG Specific

2.7.3.1 Requirements

  1. A Sender shall be able to determinine from a receiver message whether a message has been reliably delivered, as specified by the receiver.

  2. A sender and receiver shall be able to engage in message exchange patterns that exhibit best-effort, at least once, at most once, ordered qualities of service.

2.7.3.2 Non-requirements

  1. specifying quality of service of the sender/receiver software, particularly the durability of the message on a particular side. Justification: qos would be a static definition, not part of a reliablity ACK Protocol. It seems in appropriate to specify a software quality in a wire-protocol.

  2. Sender over-riding receiver default qos (ie tcp's ack before enqueue)

  3. Specifying time to live of messages in message itself. This is more of a WSD definition. It would complicate the protocol somewhat, ie what happens if the TTL is too high, or higher than a WSD definition. the 80/20 point seems lower than this

2.7.3.3 Candidate Technologies

ebXML Messaging Service, Proprietary Messaging Systems, Java Messaging Service

2.7.3.4 Priority, Effort

High priority, medium effort. Justification: specs like ebXML MS, JMS, etc. have reliability specified in under 30 pages.

2.8 S030 Third party intermediary

2.8.1 Scenario Definition

A blind auction marketplace serves as a broker between buyers and suppliers. Buyers submit their requirements to the marketplace hub, which broadcasts this information to multiple suppliers. Suppliers respond to the marketplace hub where the information is logged and ultimately delivered to the buyer.

2.8.2 Description

Figure 9 Marketplace intermediary

Figure 9 illustrates an infrastructure where SOAP based messaging is used to support a third party marketplace acting as an intermediary between buyers and sellers. The market place business model involves the recruitment of multiple suppliers for goods and services. Buyers may then connect to the marketplace and take advantage of the services they provide. The marketplace acts as a channel for the commercial transactions between a buyer and its chosen seller. A marketplace can exist to serve both B2B and B2C transactions.

In scenario S7, the marketplace acts as a blind intermediary. A buyer connects to the marketplace and places an order for items or services it requires. The buyer may be as simple as a browser or as complex as a procurement application. Once the marketplace has received the buyer's order, it contacts an appropriate set of sellers who then provide competitive bids aginst the order. The marketplace can then select the most attractive bid and connect the winning seller to the buyer. A purchasing process is then initiated with the marketplace acting as an intermediary in the transaction.

From a SOAP messaging point of view, the scenario illustrated in Figure 9 consists of a set of request/response messages between the buyer and the marketplace resulting in the buyer's order being registered. Once received, the marketplace then contacts its set of selected sellers again by a set of request/response messages. Design decisions made during the implementation of the marketplace software will determine whether supplier messages are sent from a single SOAP Sender to multiple SOAP Receivers, one at each of the seller's sites. Alternatively, a SOAP Sender could be instantiated for each supplier and a physical 1:1 relationship established. Prior agreements on message qualities such as reliability, security and structure would be put in place between the marketplace and its sellers. These qualities would define what additional SOAP Handlers were needed for the message exchange patterns between the marketplace and sellers.

2.9 S031 Communication via multiple intermediaries

2.9.1 Scenario Definition

An intermediary forwards a message to the ultimate receiver on behalf of an initial sender. The initial sender wishes to enforce the non-repudiation property of the route. Any intermediate message service handler that appends a routing message must log the routing header information. Signed routing headers and the message readers must be logged at the message handler which passes the message to the ultimate receiver to provide the evidence of non-repudiation.

2.9.2 Description

Figure 12 Routing and logging through intermediaries

Scenario S11 requires an audit chain to be created between a SOAP Sender that originates the message and the ultimate SOAP Receiver including any SOAP Intermediaries that the message passes through. Figure 12 illustrates a possible implementation of this scenario. Each SOAP Node on the message path has access to a persistent store (typically a database) that can be used to store an audit record for each message. A Routing Logging Handler on each SOAP Node has the responsibility of logging each message in the persistent store. A further responsibility of the handler is to sign the message routing header before passing the message on to the next SOAP Node in the path. Support for certificates and other artifacts required for signing a message are not shown.

2.10 S032 Caching

2.10.1 Scenario Definition

Some applications may wish to make caching possible for latency, bandwidth use or other gains in efficiency. To enable this, it should be possible to assign cacheability in a variety of circumstances. For example, "read" caching might be used to store messages at intermediaries for reuse in the response phase of the request/response message exchange pattern. Such caching might be on the scope of an entire message, a SOAP module, or scoped to individual SOAP module elements.

Similarly, "write" caching may be useful in situations when a request message in a request/response message exchange pattern (as well as similar messages in other message exchange patterns) does not need to be immediately forwarded or responded to. Such cachability might be scoped by different methods, as outlined above.

Cacheability scoped by different elements might be associated by an attribute to the target element, through use of XML Query or XPath to describe the target elements in a header, or implied by the document schema, for example.

Cacheability mechanisms applied to messages, bodies or elements might include time-to-live (delta time), expiry (absolute time), entity validation, temporal validation, subscription to invalidation services, and object update/purge.

Finally, some applications may be capable of describing the dependencies and relationships between message elements. For example, a response element may be applicable to a wide range of requests; it would be beneficial to describe this element's relationship with request elements, so that it may satisfy a wide range of requests in an economical fashion. Similarly, the presence of a particular element may be a trigger for a cacheability mechanism to be applied to another element, such as validation or invalidation.

2.10.2 Description

Caching is frequently used as an optimization in distributed systems. It can be used to avoid re-doing computations or complex database access when the results remain valid for an extended period of time. In this case, subsequent requests for the same information can be served with the cached version rather than repeat the processing with the associated overheads. Another use of caching is in the transmission of data where copies may be held at leaf servers for local service provision rather than repeatedly access a central information repository. This has the combined effect of providing faster access to the information, reducing network bandwidth requirements and reducing the workload on a central server. Caching may be provided as part of an underlying transport infrastructure but in the case of this scenario, it is assumed that the caching is independent of any underlying transport.

An example of this kind of scenario is the caching of the response to a request in situations where a subsequent request can be safely answered with the same result. This example coincides with scenario S809 (Caching with expiry) where a catalog is updated at 8am each morning. Once the catalog has been updated, all price queries against it are valid until 8am the following day. If a price query request is repeated against the same item, then a cached response can be returned to the SOAP Sender otherwise the request is forwarded to the catalog server and its response is cached. All entries in the cache are purged at the time of the updated catalog being available. Figure 18 illustrates a possible architecture.

Figure 18 Result Caching

SOAP Application 1 initiates a request for catalog price information illustrated in the following example.

Example: SOAP request message for catalog price information
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <c:CatalogPriceRequest xmlns:c="http://example.org/2001/06/catalog">
      <c:PartNumber>ABC-1234</c:PartNumber>
    </c:CatalogPriceRequest>
  </env:Body>
</env:Envelope>

The caching intermediary SOAP Application 2 is unable to fulfil the request from its local store so it forward the request which ultimately arrives at the catalog server SOAP Application 3. The catalog server process the request and assembles a response message containing the requested price information. An additional SOAP Header is placed in the response to control any caches that may exist in the return path. The CacheControl Header contains a CacheKey which allows matching of future requests to the cached response together with an Expires element that sets the time the local copy must be purged. This response is returned via the caching intermediary.

Example: SOAP response with caching header received by intermediary
<?xml version="1.0" ?>
<e nv:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <ca:CacheControl xmlns:ca="http://example.org/2001/06/cache">
      <ca:CacheKey>ABC-1234</ca:CacheKey>
      <ca:Expires>2001-03-09T08:00:00Z</ca:Expires>
    </ca:CacheControl>
  </env:Header>
  <env:Body>
    <c:CatalogPriceResponse xmlns:c="http://example.org/2001/06/catalog">
      <c:PartNumber>ABC-1234</c:PartNumber>
      <c:PartPrice c:currency="USD">120.37</c:PartPrice>
    </c:CatalogPriceResponse>
  </env:Body>
</env:Envelope>

At the caching intermediary, the CacheControl header information is used to make a local copy of the response message, keyed by the CacheKey. The copy will be purged at the time specified by the Expires element. The CacheControl header element is removed by the intermediary and the catalog price information is returned to the original sender. The request/response path for this message is the complete roundtrip between the original SOAP Sender and SOAP Receiver and is shown by Message Path 1 in Figure 18.

Example: SOAP response with received by original Sender
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <c:CatalogPriceResponse xmlns:c="http://example.org/2001/06/catalog">
      <c:PartNumber>ABC-1234</c:PartNumber>
      <c:PartPrice c:currency="USD">120.37</c:PartPrice>
    </c:CatalogPriceResponse>
  </env:Body>
</env:Envelope>

Since there is now a local copy of the price information for item ABC-1234 in the intermediary cache, subsequent requests for price information can be fulfilled by the intermediary. This is the shorter request/response path Message Path 2.

2.11 S035 Routing

2.11.1 Scenario Definition

A developer wishes to force an explicit message path through certain intermediaries - for instance, he might use an anonymizing intermediary to make a call to a specified remote service without allowing the target service to track the identity/IP of the caller. In this case, the intermediary is responsible for calling the target service and returning the results to the caller, using its own authentication credentials if any are required by the target service.

2.11.2 Description

This scenario has been addressed in detail by the WS-Routing [4] (formerly SOAP-RP) specification.

2.12 S036 Tracking

2.12.1 Scenario Definition

A service provider wishes to track incoming messages to see exactly which processing intermediaries have touched it by the time it arrives at its destination. It therefore requires a tracking extension to be included by all clients, and by any processing intermediaries along the message paths from the clients to the server.

2.12.2 Description

Figure 19 Message Tracking

Scenario S805 describes a routing requirement whch is addressed in detail by the WS-Routing [4] (formerly SOAP-RP) specification. This describes how a message may be reouted through some messaging infrastructure. Once the message has arrived at its ultimate receiver, the route the message has taken may be required for auditing purposes. A track of the message path may be created by adding a tracking header to the message in addition to any routing information.

This is illustrated in the following example. A routing header has been added to the message in accordance with WS-Routing [4]. A TrackingHeader is used to maintain a list of Intermediary names and associated Timestamp elements. As the message passes through each intermediary, a Tracking Handler appends a Via element to the TrackingHeader. The Via element contains the name of the intermediary together with the date/time the message arrived or was forwarded by the intermediary. The list of Via elements therefore forms the audit trail for the message.

Example: SOAP request with routing and tracking headers
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <t:TrackingHeader xmlns:t="http://example.org/2001/06/tracking">
      <t:Via>
        <t:Intermediary>soap://A.com/some/endpoint</t:Intermediary>
        <t:Timestamp>2001-03-09T08:00:00Z</t:Timestamp>
      </t:Via>
      <t:Via>
        <t:Intermediary>soap://B.com</t:Intermediary>
        <t:Timestamp>2001-03-09T08:01:00Z</t:Timestamp>
      </t:Via>
      <t:Via>
        <t:Intermediary>soap://C.com</t:Intermediary>
        <t:Timestamp>2001-03-09T08:02:00Z</t:Timestamp>
      </t:Via>
      <t:Via>
        <t:Intermediary>soap://D.com/some/endpoint</t:Intermediary>
        <t:Timestamp>2001-03-09T08:03:00Z</t:Timestamp>
      </t:Via>
      </t:TrackingHeader>
      <wsrp:path xmlns:wsrp="http://schemas.xmlsoap.org/rp">
        <wsrp:action>http://www.im.org/chat</wsrp:action>
        <wsrp:to>soap://D.com/some/endpoint</wsrp:to>
        <wsrp:fwd>
          <wsrp:via>soap://B.com</wsrp:via>
          <wsrp:via>soap://C.com</wsrp:via>
        </wsrp:fwd>
        <wsrp:from>soap://A.com/some/endpoint</wsrp:from>
        <wsrp:id>uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6</wsrp:id>
      </wsrp:path>
  </env:Header>
  <env:Body>
    .....
  </env:Body>
</env:Envelope>

2.13 S037 Caching with expiration

2.13.1 Scenario Definition

BizCo updates their online price catalog every morning at 8AM. Therefore, when remote clients access their SOAP inventory service, clients and intermediaries may cache the results of any price queries until 8AM the next day.

2.13.2 Description

See description for DS24.

2.14 S040 Conversational message exchange

2.14.1 Scenario Definition

Two partners are engaged in a long-running process, which involves multiple message exchanges. Examples of such processes may be complex supply chain management, dynamic manufacturing scheduling or information retrieval. There may be multiple instances of the same process in progress between the same two partners.

2.14.2 Description

Figure 10 Conversational message exchange

Interactions between business partners are usually more complex than a single request/response message exchange. A long running set of message exchanges may, for example be used to implement a business interaction such as procurement of goods or services. In this case there are advantages in grouping individual messages into a longer running set of exchanges. Such an exchange of messages is known as a conversation. Conversations may continue between a pair of trading partners for a long time. Completion of a conversation instance may take days, weeks or months. In a procurement process, an example conversation may be:

  1. A buyer request a quotation for some goods, the seller responds with the quote.

  2. The buyer places a puchase order which the seller accepts.

  3. The seller informs the buyer of delivery dates, the buyer accepts.

  4. The buyer acknowledges delivery of the goods, the seller acknowledges.

  5. The buyer provides payment, the seller issue a receipt.

All of the example message exchanges are related an instance of any agreement between the two partners. For a message to be valid as part of the agreed rules, each partner has to check whether the current message is valid within the scope of the TPA.

Figure 10 illustrates how this scenario could be implemented. Each partner's SOAP processor has access to a database which is configured by the agreement agreed between the two partners. A Conversation State Handler in the SOAP Sender configures its SOAP Block with information that identifies a message with conversation instance it is part of. A matching handler in the SOAP Receiver uses the sender's information to test whether the received message is acceptable within the rules of the agreement. It does this by checking with its own rules database where the state information on each of the conversation instances currently active is stored. If a message violates the rules of the agreement, then the application can raise a fault condition.

Note that Figure 10 does not include handlers for other message headers to support reliability or security which may be required under the agreement.

In the following request and response examples, a ConversationState Header is used to identify which agreement governs the exchange between the two trading partners (AgreementId). To support multiple concurrent conversations under the same agreement, a ConversationId element is included. The values of AgreementId and ConversationId will remain constant for the lifetime of a particular conversational exchange and will appear in both request and response messages.

Example: SOAP request message as part of a conversational exchange
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:ConversationState xmlns:n="http://example.org/conversation">
      <n:AgreementId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:AgreementId>
      <n:ConversationId>uuid:02957815-38fh-39gp-0dj2-dm20fusy1n5j</n:ConversationId>
    </n:ConversationState>
  </env:Header>
  <env:Body>
    -----
  </env:Body>
</env:Envelope>
Example: SOAP response message as part of a conversational exchange
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:ConversationState xmlns:n="http://example.org/conversation">
      <n:AgreementId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:AgreementId>
      <n:ConversationId>uuid:02957815-38fh-39gp-0dj2-dm20fusy1n5j</n:ConversationId>
    </n:ConversationState>
  </env:Header>
  <env:Body>
    -----
  </env:Body>
</env:Envelope>

2.14.3 WS-Arch WG Specific

2.14.3.1 Requirements

  1. A Sender shall be able to specify information in a message for it's internal use. The sender shall send the same information for subsequent messages in a given conversation. The receiver is required to echo this information for messages in a given conversation. An example of this is a client-side conversation ID.

  2. A Receiver shall be able to specify information in a message for it's internal use. The receiver shall send the same information for subsequent messages in a given conversation. The sender is required to echo this information for messages in a given conversation. An example of this is a server-side conversation ID.

  3. A Sender and a Receiver shall have a specification of sequences of allowable messages. This is sometimes called choreography, orchestration, or workflow. An example of this is Robin Milner's pi calculus.

  4. A Sender and a receiver shall have a specification of the static characteristics of the interchange. The agreement might be specified in some or all of the messages exchanged.

2.14.3.2 Non-requirements

  1. starting/stopping conversations at the protocol level. This is an application feature.

  2. timing out conversations at the protocol level. This is an application feature.

2.14.3.3 Candidate Technologies

Sequencing aka choreography: WSCL, WSFL, XLang

Conversations: ebXML Message Service

Static characteristics: ebXML CPP/CPA, WSEL?

2.14.3.4 Priority, Effort

Messages containing information for sender/receiver: High priority, low effort

Sequencing of messages: High priority, High effort

Static characteristics: Medium priority, small to large effort

2.15 S061 Request with encrypted payload

2.15.1 Scenario Definition

A sender wishes to exchange data with a receiver and has agreed to encrypt the payload. The sending and receiving applications agree on the encryption methodology. Data is encrypted by the originating application and sent to the receiver via SOAP. The data reaches the receiving application untouched, and may then be decrypted in the agreed-upon manner.

2.15.2 Description

Figure 8 Request with encrypted payload

Scenario S6 describes two applications that wish to share encrypted data as an opaque body in a SOAP message. It places no requirements on the SOAP messaging layer. Figure 8 illustrates this scenario.

Example: Plaintext SOAP message
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <m:GetLastTradePrice xmln:m="some-URI">
      <m:symbol>IBM</m:symbol>
    </m:GetLastTradePrice>
  </env:Body>
</env:Envelope>

The following is the encrypted version of the above plain SOAP message. The body entry <m:GetLastTradePrice> is encrypted using a symmetric key identified by the key name "Symmetric Key" and replaced by the <xenc:EncryptedData> element with an id "encrypted-body-entry". A <sec:Encryption> header entry for this encrypted data is added to the SOAP header. Note that the <sec:EncryptedDataList> element in the header entry has a reference to the <xenc:EncryptedData> element. The symmetric key used for encryption is stored in the <xenc:EncryptedKey> element in the header entry in an encrypted form, that is, it is encrypted by John Smith's RSA public key.

Example: Encrypted SOAP message
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <sec:Encryption xmlns:sec="http://schemas.xmlsoap.org/soap/security/2000-12"
                       env:actor="some-URI"
                       env:mustUnderstand="true">
      <sec:EncryptedDataList>
        <sec:EncryptedDataReference URI="#encrypted-body-entry"/>
      </sec:EncryptedDataList>
      <xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
                            Id="EK"
                            CarriedKeyName="Symmetric Key"
                            Recipient="John Smith">
        <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
          <ds:KeyName>John Smith's RSA Key</ds:KeyName>
        </ds:KeyInfo>
        <xenc:CipherData>
          <xenc:CipherValue>ENCRYPTED 3DES KEY......</xenc:CipherValue>
        </xenc:CipherData>        
        <xenc:ReferenceList>
          <xenc:DataReference URI="#encrypted-body-entry"/>
        </xenc:ReferenceList>
      </xenc:EncryptedKey>
    </sec:Encryption>
  </env:Header>
  <env:Body>
    <xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
                           Id="encrypted-body-entry"
                           Type="http://www.w3.org/2001/04/xmlenc#Element">
    <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:RetrievalMethod URI="#EK" Type="http://www.w3.org/2001/04/xmlenc#EncryptedKey"/>
        <ds:KeyName>Symmetric Key</ds:KeyName>
      </ds:KeyInfo>
      <xenc:CipherData>
        <xenc:CipherValue>ENCRYPTED BODY ENTRY......</xenc:CipherValue>
      </xenc:CipherData>        
    </xenc:EncryptedData>
  </env:Body>
</env:Envelope>

2.15.3 WS-Arch WG Specific

2.15.3.1 Requirements

  1. Encrypt portions of the payload

  2. Point to Point

  3. Specification of c14n algorithm used. Perhaps in spec, or in WSD?

2.15.3.2 Non-requirements

  1. Intermediaries. Justification: While intermediaries will be very important, a first version of security would be greatly successful without

2.15.3.3 Candidate Technologies

SOAP-Security, WS-Security

2.15.3.4 Priority, Effort

High, Medium effort. Justification: XEnc Exists, emerging specifications are able to use Xenc in fairly small amounts of specese.

2.16 S062 Message header and payload encryption

2.16.1 Scenario Definition

Two trading partners engaged in a message exchange may agree to cryptographically sign and verify either the message header, the routing header(s) and/ or the payload. The sender or originating application may perform the signing of the payload. The sending message handler signs the message header. A routing header may be appended to the message header. The routing header may also be signed by a message service handler.

2.16.2 Description

Figure 11 Header and payload encryption

In scenario S6, two applications communicated using encrypted payloads. These opaque payloads had no impact on the SOAP processing layer. In this scenario, the action of signing and/or encrypting the headers or payload is the responsibility of the SOAP processing layer. Figure 11 illustrates how the encryption agreements are accessible to a Message Signing Handler on the SOAP Sender and a matching Message Verification Handler on the SOAP Receiver. An additional Message Routing Header may also be part of the SOAP message. This header may also be signed and verified if needed by the security requirements of the message exchange.

Editorial note: JBI20011211
Add example encrypted SOAP message

2.17 S063 Authentication

2.17.1 Scenario Definition

A web service client presents credentials or tokens to a web service.

2.17.2 Description

2.17.3 WS-Arch WG Specific

2.17.3.1 Requirements

  1. Shall support Username/password credential

  2. Shall support binary credentials, such as X.509 certificates

  3. Shall support authentication across trust domains.

  4. Shall define a trust model.

2.17.3.2 Non-requirements

2.17.3.3 Candidate Technologies

HTTP Authentication, WS-Security

2.17.3.4 Priority, Effort

High priority, low effort. There are numerous specifications available that provide this functionality, and they are fairly straightforward.

2.18 S064 Message Integrity

2.18.1 Scenario Definition

A sender and receiver may wish to be able to determine if a message has been modified in transit, and point-to-point encryption is not appropriate, perhaps because of intermediaries or system architecture choices.

2.18.2 Description

2.18.3 WS-Arch WG Specific

2.18.3.1 Requirements

  1. Sign arbitrary portions of a document

  2. Shall use Digital Signatures

2.18.3.2 Non-requirements

2.18.3.3 Candidate Technologies

SOAP Security, WS-Security

2.18.3.4 Priority, Effort

High priority, low effort: There are numerous specifications available that provide this functionality, and they are fairly straightforward.

2.19 S070 Asynchronous messaging

2.19.1 Scenario Definition

A sender sends a message asynchronously to a receiver expecting some response at a later time. The sender tags the request with an identifier allowing the response to be correlated with the originating request. The sender may also tag the message with an identifier for another service (other than the originating sender) which will be the recipient of the response.

2.19.2 Description

Figure 13 Asynchronous messaging

Scenario DS17 is the same as the basic request/response pattern described in scenario S3. The difference is that the request and response messages are separated in time and implemented as two unidirectional messages. The sending SOAP Application does not block and wait for the response to return. The sending SOAP Application is notified when a response is received by its SOAP Receiver. It then uses the correlation information within the received message to match the response to a message it sent some time earlier.

Figure 11 illustrates a possible implementation. In the request SOAP message, a Message Identifier Handler is responsible for generating a unique message identifier and inserting it into a SOAP Header. This forms part of the SOAP request message and is sent from SOAP Application 1 to the receiving SOAP Application 2. The request message is processed by a business application and a response message is assembled. This includes a SOAP Header built by a Message Correlation Handler which links the response message to its associated request.

Example: SOAP asynchronous request message containing a message identifier
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <n:MessageId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:MessageId>
    </n:MsgHeader>
  </env:Header>
  <env:Body>
      ........
  </env:Body>
</env:Envelope>
Example: SOAP asynchronous response message containing correlation to original request
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:MsgHeader xmlns:n="http://example.org/requestresponse">
      <n:MessageId>uuid:09233523-567b-2891-b623-9dke28yod7m9</n:MessageId>
      <n:ResponseTo>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</n:ResponseTo>
    </n:MsgHeader>
  </env:Header>
  <env:Body>
      ........
  </env:Body>
</env:Envelope>

2.19.3 WS-Arch WG Specific

2.19.3.1 Requirements

  1. . A sender shall be able to specify a URI for a receiver to send subsequent messages to, aka callback.

    1. This address can be contained in a message (dynamic)

    2. This address can be defined at an interface (static)

    3. This address can be specified in a 3rd party

2.19.3.2 Non-requirements

2.19.3.3 Candidate Technologies

Static: ebXML CPP/CPA

Third Party: ebXML Registry, UDDI

2.19.3.4 Priority, Effort

High. Low effort for simple callback URL.

2.20 S071 Asynch/Synchronous specificity

2.20.1 Scenario Definition

Capture the synchronicity of the operations

2.20.2 Description

To negotiate proper communication sequence WS provider has to be able to describe if certain operations can be handled asynchronously, must be handled asynchronously or synchronously and what is the expected execution time. This would allow process orchestration system to properly adjust the flow and not run into unexpected blocking.

2.20.3 WS-Arch WG Specific

2.20.3.1 Requirements

2.20.3.2 Non-requirements

2.20.3.3 Priority, Effort

2.21 S080 Transaction

2.21.1 Scenario Definition

Transaction contexts are shared between to systems

2.21.2 Description

2.21.3 WS-Arch WG Specific

2.21.3.1 Requirements

2.21.3.2 Non-requirements

  1. Two-phase commit

2.21.3.3 Candidate Technologies

OASIS BTP

2.21.3.4 Priority, Effort

Medium priority, high effort. Rationale: Transactions are typically quite complicated.

2.22 S090 Sending non-XML data

2.22.1 Scenario Definition

A digital camera wishes to transmit image data over a wireless link using SOAP to a remote server. The binary image data (non-XML) accompanies the message. The digital camera represents a situation in which connections from the receiver to the sender may not be permitted due to device limitations or firewalls.

2.22.2 Description

Figure 14 Sending non-XML data

Support for non-XML data has been described elsewhere. The SOAP with Attachments [2] note to the W3C has been adopted by the ebXML Message Services specification [1] as the basis for defining a message structure which can support non-XML data. Supporting non-XML data requires additional packaging of the message which can be provided by a MIME multipart structure and impacts the binding of a message to its underlying transport protocol. Figure 14 illustrates a unidirectional SOAP message path. A Message Manifest Handler is implemented which creates a set of references to the different parts of a multipart MIME package. Each part is referenced by its content identifier.

Figure 15 Using MIME packaging for non-XML data

Figure 15 illustrates how different parts of a message are packaged using MIME multipart. The outermost MIME envelope packages a set of individual MIME parts. The first MIME part contains a SOAP message which includes the Manifest Header block created by the Message Manifest Handler. The second and subsequent MIME parts contain payload(s) which may be XML documents or any other MIME content type such as image, audio or video data. The SOAP manifest header can contain elements that reference the separate MIME parts using their content identifiers. This may be achieved using XLink references as shown in the following example. The XLink role attribute may be used to further qualify the type of data contained within the payload.

Example: SOAP message containing a manifest for non-XML data
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <n:Manifest xmlns:n="http://example.org/manifest">
      <n:Reference n:id="image01" 
                      xlink:href="cid:payload-1"
                      xlink:role="http://example.org/image">
        <n:Description>My first holiday photograph</n:Description>
      </n:Reference>
      <n:Reference n:id="image02"
                      xlink:href="cid:payload-2"
                      xlink:role="http://example.org/image">
        <n:Description>My second holiday photograph</n:Description>
      </n:Reference>
    </n:Manifest>
  </env:Header>
  <env:Body>
    ........        
  </env:Body>
</env:Envelope>

2.22.3 WS-Arch WG Specific

2.22.3.1 Requirements

  1. Messages can contain binary data

2.22.3.2 Non-requirements

2.22.3.3 Candidate Technologies

SOAP with Attachments, DIME

2.22.3.4 Priority, Effort

High, medium. Probably biggest requirement issue is MIME based or not, so this probably won't be easy to resolve quickly.

2.23 S091 Incremental parsing/processing of SOAP messages

2.23.1 Scenario Definition

An SOAP sender generates a lengthy SOAP message that is incrementally transmitted and received by a SOAP receiver. The SOAP receiver employs a SOAP handler that can incrementally process the body as it is received (e.g., employing a SAX-style XML parser on the body as it arrives). Note that the entire message need not be present at one time at any point in its existence.

This would be particularly helpful for memory-limited processors. It is also very efficient for services which are consistent with incremental, real-time transformations of the data, direct archiving of received data, etc. It would also be useful in scenarios in which voluminous body data can be directly transduced into application data structures or events by a SOAP (module) processor. In particular, there is no need for the explicit construction of a DOM model of the data. Support for various data models might still be possible even with incremental processing if the models are incrementally constructible.

2.23.2 Description

Scenario S21 requires the incremental parsing and processing of a SOAP message by a receiver. This is a general scenario with memory-limited processor requirements forming a subset of the scenario. If the SOAP Body contains a large amount of data, then it may be processed incrementally by a SAX parser if the data is chunked as in the following example. The SAX parser will have a handler triggered by the BodyDataChunk element.

Example: Final SOAP response message containing sequencing and correlation to original request
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Header>
    <!--Set of headers processed before Body -->
  </env:Header>
  <env:Body>
    <b:BodyDataChunk xmlns:s="http://example.org/2001/06/chunking">
      <b:DataLength>1024</b:DataLength>
      <b:Data>kfkk34jkhfSomeBase64EncodedDatajdsgkjgjajgo34093589uvsjv.....jhfjhf350giqhf</b:Data>
    </b:BodyDataChunk>
 
    <!-- More BodyDataChunk elements -->
 
    <b:BodyDataChunk xmlns:s="http://example.org/2001/06/chunking">
      <b:DataLength>1024</b:DataLength>
      <b:Data>oqjrj45cmoLastLotOfBase64EncodedData12r9vnhofjhckzlmxjws.....skfjk23ogkkjhq</b:Data>
    </b:BodyDataChunk>
  </env:Body>
</env:Envelope>

If a SOAP request is being streamed and processed incrementally, then the matching response message may be streamed to the original sender. In this case, the design of the receiving application is critical with respect to timing and error handling.

  1. If errors are generated by the SOAP request Headers, then a SOAP Fault is inserted in the response and processing of the request message is terminated.

  2. The SOAP receiving application may treat each BodyDataChunk element as atomic. A positive or negative acknowledgement is streamed to the SOAP response depending on whether the BodyDataChunk element was successfully processed or not. The SOAP response message is terminated once the end of the SOAP request is reached.

  3. Alternatively, the SOAP receiving application may process each BodyDataChunk until either the end of the SOAP request is received or a fault occurs. In the case of a fault, a SOAP Body fault element is streamed to the SOAP response and processing of the SOAP request is terminated.

2.24 S092 Streaming Response

2.24.1 Scenario Definition

Specifying streaming with input or output

2.24.2 Description

A webcam is plugged in to a network. A user sends through the network an HTTP request to get the video. The webcam answers to this request by streaming the video to the user. The user sends another request to stop the streaming. I think WSDL should provide a way to express that it will use streaming at some point. Streaming might be used at two levels: - at the protocol level : the service may transmit the result by streaming - at the datatype level : the service may indicate that it will receive/send streaming as input/output..

2.24.3 WS-Arch WG Specific

2.24.3.1 Requirements

2.24.3.2 Non-requirements

2.24.3.3 Candidate Technologies

2.24.3.4 Priority, Effort

2.25 S200 Event notification

2.25.1 Scenario Definition

An application subscribes to notifications of certain named events from an event source. When such events occur, notifications are sent back to the originating application (first party notification) or to another application (third party notification). For example, an application can subscribe to notification of various aspects of a printer's status (e.g., running out of paper, ink etc.). The notifications of such events could be delivered to a management application.

2.25.2 Description

Figure 17 Publish and subscribe

Scenario S23 describes event notification using a publish subscribe mechanism. An implementation of this scenario uses an example of the request/response scenario S3 to register a subscription and fire-and-forget to multiple receivers scenario S2 for the notification. Figure 17 illustrates how a request/response message pattern can be used with a Subscription Request Handler to register an interest (or subscription) in some set of events. The registration is made with some subscription service. The success or otherwise of the registration is returned to the subscribing application using a Subscription Ack Handler which provides an acknowledgement to the subscribing application.

Delivery of an event noification to a set of subscribers may be implemented using the fire-and-forget to multiple receivers scenario S2. The subscription service provides the list of valid applications that have registered an interested in a particular event. This list may then be converted into a group address or distribution list to support the implementation of the fire-and-forget scenario.

A subscription request may include a list of events within the SOAP Body as in the following example.In this example, a subscription is registered with a stock price notification service. The subscribing application will be informed of company BigCo's stock price, volume traded and time whenever the price is greater than 100.

Example: SOAP event subscription request message
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <s:StockNotificationSubscription xmlns:s="http://example.org/2001/06/subscribe">
      <s:Notify>PRICE</s:Notify>
      <s:Notify>VOLUME</s:Notfy>
      <s:Notify>TIMESTAMP</s:Notfy>
      <s:When>
        <s:Company>BigCo</s:Company>
        <s:Price range="GreaterThan">100</s:Price>
      </s:When>
    </s:StockNotificationSubscription>
  </env:Body>
</env:Envelope>

An acknowledgement may include an identifier to the subscription as in the following example:

Example: SOAP event subscription acknowledgement response
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <s:StockNotificationSubscriptionAck xmlns:s="http://example.org/2001/06/subscribe">
      <s:SubscriptionId> uuid:40195729-sj20-pso3-1092-p20dj28rk104</s:SubscriptionId>
    </s:StockNotificationSubscriptionAck>
  </env:Body>
</env:Envelope>

The identification may be used in subsequent notifications to the application as a result of the subscription:

Example: SOAP event notification
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
  <env:Body>
    <n:StockNotification xmlns:n="http://example.org/2001/06/notification">
      <n:SubscriptionId> uuid:40195729-sj20-pso3-1092-p20dj28rk104</n:SubscriptionId>
      <n:Company>BigCo</n:Company>
      <n:Price>100.56</n:Price>
      <n:Volume>102345</n:Volume>
      <n:Timestamp>2001-03-09T12:22:30Z</n:Timestamp>
    </n:StockNotification>
  </env:Body>
</env:Envelope>

2.26 S201 Event Management Model

2.26.1 Scenario Definition

Capture event management model for web services

2.26.2 Description

2.26.3 WS-Arch WG Specific

2.26.3.1 Requirements

2.26.3.2 Non-requirements

2.26.3.3 Priority, Effort

2.27 S300 System Messages

2.27.1 Scenario Definition

A sender or other party sends messages to a receiver inquiring about the status of the service or message or to control the execution of the message

2.27.2 Description

A sender wishes to determine if a service is available. It sends a synchronous message querying the status of the service. Later, the sender sends an asynchronous message to the service. The sender then wishes to determine or control the status of the asynchronous message. It sends a synchronous message querying the status of the asynch message.

2.27.3 WS-Arch WG Specific

2.27.3.1 Requirements

  1. Shall be possible to "ping" availability of service

  2. Shall be possible to query message status

  3. Shall be possible to control message

2.27.3.2 Non-requirements

2.27.3.3 Candidate Technologies

ebXML Ping, Status messages

2.27.3.4 Priority, Effort

Medium to Low. Effort is from simple (like Ping) to complex.

2.28 S500 Service Metadata

2.28.1 Scenario Definition

Service providers can provide custom data

2.28.2 Description

A WS provider can decorate various elements of the service description with custom attributes. These attributes may be application specific and would be described by the WS provider in an additional documentation. Such custom attributes may be defined in a specific schema. WS provider may include such extra information as owner e-mail, link to SLA, security and session requirements for a particular message, etc.

A conversation between two trading partners may also be defined by shared configuration information such as an ebXML Collaboration Profile Agreement (CPA). A conversation agreement includes information such as expected response times, business process actions that each party undertakes to complete, security information and message content structures.

2.28.3 WS-Arch WG Specific

2.28.3.1 Requirements

  1. Information inline in the WSDL

  2. Information external to the WSDL

2.28.3.2 Non-requirements

2.28.3.3 Priority, Effort

Inline information already done. External information: Low priority, low to high effort

2.29 S501 Service Level attributes

2.29.1 Scenario Definition

Declaration of service level attributes

2.29.2 Description

Two web services, implementing the interface for "looking up for insurance providers", from different sources are offered in a registry. One of the two services actually performs extensive data validation on the data provided, for example making sure that the zip codes in the address provided are valid", while the other web service assumes that the data provided is valid and searches for insurance providers has already been validated and uses it to perform its search without any further validation. The interface was developed by an industry consortium that agreed to reflect the data validation capability of the services as a service-level attribute. Some intelligent registries may then actually allow search criteria that can be predicated on these service-level attributes or alternatively, the client application may check the value of the service level attribute itself at runtime to find out its value. The service-level attribute may be mapped to accessor methods which can be invoked either by the intelligent registry as part of executing the search query or by the client application itself.

2.29.3 WS-Arch WG Specific

2.29.3.1 Requirements

2.29.3.2 Non-requirements

2.29.3.3 Priority, Effort

2.30 S502 Operation Level attributes

2.30.1 Scenario Definition

Declaration of operational level attributes

2.30.2 Description

In an advanced architecture where distributed transactions are supported, a web service may want to declare some of its operations as transactional as opposed to the entire interface being transactional. A web service offering various financial related web services may be able to verify a buyer's credit in a non-transactional manner but may require the client application to start a transaction before invoking the operation to prepare an invoice. The target web service may have a declarator on the method specification that indicates that the operation for invoicing requires transaction

2.30.3 WS-Arch WG Specific

2.30.3.1 Requirements

2.30.3.2 Non-requirements

2.30.3.3 Priority, Effort

2.31 S503 Namespaces with data and interfaces

2.31.1 Scenario Definition

To maintain namespaces through service providers and clients

2.31.2 Description

. It has to be required that namespaces are not getting lost between service provider and the client. It should be part of WSDL compliance.

2.31.3 WS-Arch WG Specific

2.31.3.1 Requirements

2.31.3.2 Non-requirements

2.31.3.3 Priority, Effort

2.32 S504 Versioning

2.32.1 Scenario Definition

Specifying interface versioning

2.32.2 Description

A WS provider can describe versions of interfaces implemented by a service. WS client can bind to the necessary interface version. This way there is no ambiguity when WS proivider changes service interfaces and client has created a static proxy that uses previous version of interfaces. WS provider can deprecate and remove interfaces as desired, and the client would know that. Client would send a SOAP request that would not be accepted (as namespaces do not match), as opposed to client trying to send a SOAP request that could be accepted, but improperly executed.

2.32.3 WS-Arch WG Specific

2.32.3.1 Requirements

2.32.3.2 Non-requirements

2.32.3.3 Priority, Effort

2.33 S505 Classification system for operations

2.33.1 Scenario Definition

2.33.2 Description

Imagine a component framework in which components and their operations (building finally the component's functionality) should be described with WSDL. In the framework the components are using operations from each other dynamically: in the program code there is no "hard-wired" function call but instead a "semantic description/reference" of what kind of operation to use, which will be dissolved just in time before execution. With this "semantic description" a search for suitable operations could be started in a (logical) centralized registry (maybe with UDDI). The registry contains (WSDL) information of all currently available components/operations within the framework. Result of the search query are the concrete binding parameters (protocol, URL, operation signature, etc.) of the matching operations. Finding a suitable match _automatically_ (without manual/human interaction) will be done by searching in the registered WSDL files for the specified "semantic description". One half of this "semantic description" are the parameters defined with complex XML schema types. The other one should be the determination of the operation (i.e. its functionality). But only considering the operation name has the same drawbacks as comparing parameters only by their name (or even simple types like integer, string, etc.): only operations with exactly the same name as chosen from the operation's programmer are returned. So with introducing a kind of "type system" for operations (or maybe a classification) would bring the benefit that the result set of the above mentioned query could return operations with different names, but which are implementing the same functionality/behaviour. With this it would also be possible to exchange one component (respectively their operation/s) with another independently developed one, which has the same functionality but with (maybe only slightly) different operation name(s) - and this without further manual interaction.

2.33.3 WS-Arch WG Specific

2.33.3.1 Requirements

2.33.3.2 Non-requirements

2.33.3.3 Priority, Effort

2.34 S510 Quality of service

2.34.1 Scenario Definition

A SOAP sender (not necessarily the initial SOAP sender) wants the SOAP message to be handled with specific quality of service as it traverses the SOAP message path to include multiple SOAP Processing intermediaries. Information in the SOAP message is used to select appropriate QoS mechanisms (e.g., RSVP, Diffserv, MPLS, etc.). Selection of QoS may be constrained by QoS policies, Service Level Agreements (SLAs), Service Level Specifications (SLS).

2.34.2 Description

A SOAP header block is one possible approach to implementing this scenario. The SOAP 1.2 specification does not define this hypothetical SOAP Quality Of Service (QoS) block. An initial SOAP sender sends a SOAP message containing a QoS header block through one or more SOAP intermediaries to an ultimate SOAP receiver. The intermediary is targeted by the initial SOAP sender from within the SOAP message by inserting a role attribute within the QoS Block to be used at the SOAP intermediary as described in the SOAP processing model (Part 1, section 2.5). The SOAP specifications do not state how the role attribute is to be used by the SOAP sender. Potentially, it can be used in the context of the SOAP binding framework to provide a hint for message routing. However, message routing is not within the scope of the SOAP 1.2 specifications. The SOAP intermediary must examine the SOAP QoS Block, and determine how to invoke the QoS capabilities exposed via the SOAP binding. If the SOAP QoS Block is marked mustUnderstand, then the intermediary is expected to be QoS-aware. If it is not QoS-aware, then a SOAP fault is generated, as this mandatory header cannot be processed. If it is QoS-aware, but cannot honor the specific QoS parameters carried in the QoS Block, then any fault or other response to the sender or elsewhere (e.g., log file) is not defined in the SOAP specifications. The specification of the QoS extension, when defined, would need to describe error handling, negotiations, or other processing under all circumstances.

If the intermediary is QoS-aware, then presumably the information in the QoS Block is used when forwarding the SOAP message further along on its message path toward the ultimate SOAP receiver. In addition to the use of SOAP Blocks to extend the functionality of SOAP, this scenario may also require extensions to the HTTP binding, or a completely new binding. The Binding Framework allows for additional properties, outside the SOAP envelope, that may be required to invoke the lower layer QoS mechanisms. Additional properties (within the Binding Framework) may be required. For sake of discussion, lets assume that the SOAP node will send the SOAP message using HTTP, but traffic classification of this HTTP flow would be done using diffserv so particular per-hop behaviors can be used within the network en-route to the next SOAP node. Traffic classification for diffserv can be done by the SOAP node sending the SOAP message, or by network devices (assuming they know how to recognize the particular HTTP flow). If traffic classification is handled by a network device, perhaps communications would be needed between the SOAP node and the network device, for example, to provide the network device with the TCP/IP port numbers and IP addresses of the HTTP connection. This would presume some way to obtain this port and address information, which probably involves an API or properties that are beyond the scope of the SOAP 1.2 specifications.

For example, to state that a separate spec can define properties in accordance with the binding framework to extend the capability of the HTTP binding (or any other binding). In the case of SOAP RPC, a QoS extension at the ultimate SOAP receiver may attempt to insert a QoS Block in RPC response. The RPC response may succeed, but perhaps the desired QoS cannot be delivered on the return message path. It is not clear if a SOAP fault should be generated. Likewise, if a SOAP Intermediary on the return message path cannot honor the QoS Block (assumed to be marked mustUnderstand), is it permissible to convert the SOAP RPC response to a SOAP fault? A SOAP extension in the initial SOAP sender is needed to insert this SOAP QoS Block. The sender may need to use properties as defined by the SOAP binding framework to communicate QoS parameters to be used by the underlying network. Since a SOAP binding must define the rules for how the data is exchanged using the underlying protocol, a custom or supplemental binding may be required to support this QoS usage scenario. The HTTP binding described in the SOAP 1.2 specification does not explicitly support QoS properties. The SOAP 1.2 specification does not preclude extensions to this HTTP binding, which would provide the capability to define either QoS properties or a requirement to examine the SOAP envelope (i.e., SOAP QoS Block) to determine the QoS used for transmission. Alternatively, a completely new binding can be specified that includes QoS explicitly, rather than as an extension to an existing binding

2.35 S600 Address based Discovery

2.35.1 Scenario Definition

Given a particular service address, a sender wishes to determine the description of the service

2.35.2 Description

A Sender has the URL for a service. It sends a message to a the service requesting the WSD definition that is appropriate. This could be designed using standardized SOAP messages with particular parameters, or other designs

2.35.3 WS-Arch WG Specific

2.35.3.1 Requirements

  1. A sender and receiver shall be able to exchange WSD descriptions given just a URI for the receivers service.

2.35.3.2 Non-requirements

2.35.3.3 Candidate Technologies

WS-Inspection,

2.35.3.4 Priority, Effort

2.36 S601 Registry based discovery

2.36.1 Scenario Definition

People or Software use a registry to discover web services and the interface specifications.

2.36.2 Description

2.36.3 WS-Arch WG Specific

2.36.3.1 Requirements

  1. Service Providers can publish WSD of service(s)

  2. Service consumers can discover WSD of service(s)

  3. Service consumers can invoke Services based upon discovered service description

2.36.3.2 Non-requirements

2.36.3.3 Candidate Technologies

UDDI, ebXML Registry

2.36.3.4 Priority, Effort

Medium Priority, High effort. Justification: UDDI, ebXML Registry/Response are very significant efforts

2.37 S Template

2.37.1 Scenario Definition

2.37.2 Description

2.37.3 WS-Arch WG Specific

2.37.3.1 Requirements

2.37.3.2 Non-requirements

2.37.3.3 Candidate Technologies

2.37.3.4 Priority, Effort

3 Use cases

This section contains use cases giving more context to some of the individual usages scenarios listed in 2 Usage Scenarios.

Editorial note: HH2002-06-19
This section contains Roger's and Hugo's use cases. The format is different from the previous section. When security usage scenarios are added, we should probably add links to entries in 2 Usage Scenarios.

3.1 Travel agent use case

Editorial note: HH2002-06-19
This section needs some rework to give it more of a "spec look".

3.1.1 Description

A company (travel agent) wants to offer to people the ability to book complete vacation packages: plane/train/bus tickets, hotels, car rental, excursions, etc.

Service providers (airlines, bus companies, hotel chains, etc) are providing Web services to query their offerings and perform reservations.

Credit card companies are also providing services to guarantee payments made by consumers.

Due to the loosely coupled-nature of Web services, the travel agent doesn't need to have a priori agreements with service providers or credit card companies. This allows the travel agent to have access to more services, offering more options to its customers, the credit card companies to offer their services broadly and therefore make their customers happy, and the service providers can offer their services broadly and easily and therefore generating more business for themselves.

3.1.2 Scope

For this version of the usage scenario, we will limit ourselves to booking of vacation packages. We will assume that cancellation is not possible once a package has been purchased.

3.1.3 Stakeholders / Interests

Travel agent: provides a system to provide the user with options for his/her vacation; earns money by charging fees for each package bought.

Service providers: sell their services by making them available widely.

Credit card company: enable customers to use their credit cards in a very large number of cases; make profit with each money transaction.

Consumer: book vacation easily by choosing among a large variety of offers.

Only the user in the scenario is a human being. The travel agent service, airline, hotel and payment services that the travel agent service is interacting with, are machines.

3.1.4 Actors & Goals

Consumer: best combination of services and prices for his/her needs.

Travel agent: customer satisfaction, sell packages.

Service providers: sell services.

Credit company: qualify buyer, do the payment.

3.1.5 Usage scenarios

The following use cases describe how a user would make a reservation for a vacation package (flight and hotel room).

Here is a list of diagrams giving an overview of the scenario, with the introduction of a new hotel service:

An assumption for this usage scenario is that all the services are using common concepts (e.g. flight, economy class, room, etc). For the travel agent service to understand the airline services and to be able to send meaningful information to them, a travel industry ontology needs to exist and be used by the Web services taking part in this scenario. An ontology is a formal description of a set of concepts and their relationships to each other. By associating a name with each concept, an ontology defines a standard vocabulary that can be used to communicate those concepts.

It has to be noted that some additional technology is needed for this usage scenario:

  • context maintenance.

  • reliability: in order to make money, each step needs to happen.

  • trust mechanisms for the services to do business with each other.

  • description of orchestration of services: if a reservation of a flight involves interacting with a couple of Web services, the airline would document in a machine readable way how to interact with the two single services in order to get the desired result, including how to handle errors in the process fails before the operation is completed.

  • ...

Note that this usage scenario could be different in the following ways:

  • the user could have bought some travel agent software; the travel agent service could reside locally on his/her computer.

  • the user could write tools to interact directly with the airline and hotel services.

3.1.5.1 1. User requests availabilities about some travel dates
3.1.5.1.1 Goal / Context

The user gets the location of a travel agent service via an unspecified way (search engine, URI in an email, service directory, etc).

The user provides a destination and some dates to the travel agent service. The travel agent service inquires airlines about deals and presents them to the user.

3.1.5.1.2 Scenario / Steps
  1. The user is presented with a form to fill in order to provide the travel agent service with details about dates of his/her travel and the destination.

  2. The user submits the information to the service in order to get a list of flights corresponding to his/her schedule.

  3. The travel agent service finds a list of airlines.

  4. For each airline found:

    1. The travel agent service requests a description of how to communicate with the service found.

    2. The travel agent service requests a list of flights accommodating the user.

  5. The travel agent service presents the results of the queries to the user letting him choose the best option.

3.1.5.1.3 Extensions

If no flight can be found, the user should be presented with an error.

3.1.5.1.4 Technologies / Requirements

Discovery technology: used by the travel agent service to find the airlines services.

Description language: used by the airlines to describe their query services to the travel agent service.

Response to queries: XML documents that the travel agent service processes and merge together.

Ontologies: the data coming from different airline services and expressed with different XML vocabularies needs some semantics to be merged in a meaningful way.

3.1.5.2 2. User requests chooses flight and looks for hotels
3.1.5.2.1 Goal / Context

The user has been presented with options for flights to go to his/her destination. The user chooses a preferred flight. The service puts the seats on hold, and goes on with proposing lodging options to the user.

3.1.5.2.2 Scenario / Steps
  1. The user communicates his/her choice for the flight.

  2. The travel agent service requests the chosen airline to put the flight on hold:

    1. The travel agent service requests a description of how to put a seat on hold to the airline service.

    2. The travel agent service sends the request accordingly.

  3. The airline returns a confirmation number with an expiry date.

  4. The travel agent service finds a list of airlines.

  5. For each hotel found:

    1. The travel agent service requests a description of how to communicate with the service found.

    2. The travel agent service requests accommodation options for the period.

  6. The travel agent service looks for payment services available, and builds a list of options for the user.

  7. The travel agent service presents the results of the queries to the user letting him choose the best option, along with the payment options offered.

3.1.5.2.3 Extensions

If the seats chosen are not available anymore, the travel agent service presents the user with an error message and the user is presented with an updated list of available flights to choose from.

3.1.5.2.4 Technologies / Requirements

Description language: used by the airlines to describe their services to put tickets on hold to the travel agent service, by the hotels to describe their query services to the travel agent service.

Discovery technology: used by the travel agent service to find the hotels services.

Ontologies: the data coming from different accommodation services and expressed with different XML vocabularies needs some semantics to be merged in a meaningful way.

3.1.5.3 3. User books hotel room and flight
3.1.5.3.1 Goal / Context

The user has been presented with options for hotels to go to his/her destination and a means of payment. The user chooses a hotel option. The travel agent service contacts a bank for payment authorization. The service books the hotel and confirms the flight, using the payment authorization from the bank.

3.1.5.3.2 Scenario / Steps
  1. The user communicates his/her accommodation choice to the travel agent service.

  2. The travel agent service contacts the bank service that the user chose to confirm payment:

    1. The travel agent service requests a description of how to guarantee payment of the total amount.

    2. The travel agent service send the request accordingly.

    3. The response indicates success with an authorization number, signed by the payment authority.

  3. The travel agent service books the hotel room:

    1. The travel agent service requests a description of how to book a room to the chosen hotel service.

    2. The travel agent service sends a request in order to find out how to cancel the reservation should a problem occur later in the process.

    3. The travel agent service sends the request accordingly, communicating the payment service chosen and the signed authorization number from this service.

  4. The travel agent service confirms the flight reservation:

    1. The travel agent service requests a description of how to buy a ticket on hold to the airline service.

    2. The travel agent service sends a request in order to find out how to cancel the reservation should a problem occur later in the process.

    3. The travel agent service sends the request accordingly, communicating the payment service chosen and the signed authorization number from this service.

  5. The travel agent service charges a fee to the user:

    1. The travel agent service requests a description of how to request payment to the payment service.

    2. The travel agent service sends the request accordingly, along with the authorization number signed by the payment service.

  6. The service provides the user with various confirmation numbers and wishes the user a good vacation.

3.1.5.3.3 Extensions

If the payment service doesn't confirm the validity of the user's payment option, the user should be presented with an error.

If the hotel room cannot be booked, the user should be presented with an error and should get to choose from an updated list of options.

If the flight reservation cannot be confirmed, the hotel room reservation should be canceled and the user should be presented with an error and start the reservation process again.

3.1.5.3.4 Technologies / Requirements

Service description technology: used by the payment authority to describe its confirmation service, by the hotel to describe its room booking service, and by the airline to describe its service to buy tickets by confirming seats on hold.

Authentication technology: used by the payment authority to sign the payment authorization to be trusted by the hotel service, the airline service and the travel agent service.

Encryption technology: used by the payment service and the travel agent service to communicate the user's payment information confidentially.

Ontologies: the payment confirmation needs to be used in a way meaningful to the travel service, hotel and airline services; in other words, the output of one service needs to be used as the input to other services that might use different vocabularies.

3.1.5.4 Notes on the scenario

This scenario illustrates how a program, the travel agent service, can interact dynamically with airline services, hotel services, without a priori knowledge of them or of the way they work. Thanks to the ontologies used, the program can adapt to variations of formats that an airline service might be using and adapt to the introduction of new products.

However, there is a limit to what the travel agent service can understand. For example, it is likely to be able to understand the introduction of a new class of tickets, say class Z. However, if the restrictions on class Z tickets use concepts that it is not aware of (say that class Z tickets can only be bought more than 60 days in advance and with a valid international student identification), the developers of the travel agent service will need to implement the extra logic to make it understand this new type of restriction, including validating the student identification.

3.2 EDI-like purchasing

3.2.1 Description

A large company (BigCo) wants to purchase widgets from a small widget manufacturer (SmallCo) using web services to transmit the various documents (e.g. purchase orders and invoices) involved. There are web services set up at both BigCo and SmallCo that handle the document transmissions required to implement an industry-specific business process which has been defined by an industry-vertical standards body (e.g. ComProServ from PIDX, a protocol for obtaining oil field services). In addition to the documents involved in this business process there are payments sent through a different financial service.

BigCo and SmallCo set up a trading relationship in which web services provide functions similar to those offered in a proprietary setting by EDI VAN's (Value Added Networks) such as Ariba, CommerceOne or GE.

3.2.2 Scope

The focus of this use case is the technical infrastructure required to implement the business processes, not the business processes themselves. In this example we will assume that BigCo and SmallCo have already set up their trading relationship. How they found each other and made the agreement to trade with each other is beyond the scope of this example. Payments in this example are sent through financial institutions and involve electronic processes beyond the scope of this example (because it is beyond the scope of the EDI people whose experience forms the basis of this use case). Opinions may differ about what aspects of the requirements belong in Web Services "technical infrastructure" and which belong in "business process". For example, we think that unique ID and timedate stamping of the messages should be "infrastructure" but that sequencing of the messages belongs in "business process". These issues are discussed as they arise below.

3.2.3 Stakeholders / Interests

BigCo purchases widgets, both via EDI provided by a VAN (eg. Ariba, CommerceOne, GE) and via web services as described in this use case. BigCo uses big software packages internally. For example, financials and business information are handled by an ERP system (SAP, JDE, etc), and there is an eProcurement front end (perhaps from a different provider, eg. Ariba, SAP) that implements the purchasing logic. Connectivity and data transport within the company are provided by an EAI system (Tibco, WebMethods, BizTalk Server). BigCo's primary motivations in this activity are cost control, reliability and security. Automated processing is much cheaper than typing invoices in by hand and also can be more accurate.

SmallCo manufactures widgets and gets orders from BigCo occasionally (perhaps a few per month). SmallCo's primary motivation is to do business with BigCo and other companies of this sort, and messing with electronic procurement systems is part of what you need to do to get the sale. However, SmallCo needs to keep the cost down and cannot afford to purchase elaborate software systems to implement these processes. SmallCo uses a low-end bookkeeping system (e.g. QuickBooks, PeachTree Accounting) and does a lot of hand entry into this system. SmallCo has a web site hosted by a local ISP.

3.2.4 Actors & Goals

BigCo: A business analyst is responsible for the relationship between BigCo and SmallCo, an engineer initiates the request for purchase, the purchasing department handles the mechanics of the transaction.

SmallCo: Mom takes the order and tells Sonny to ship out N widgets, meanwhile telling Pop to enter the transaction into Quickbooks and generate an invoice against BigCo.

3.2.5 Use Cases

The following use cases first illustrate the steps involved in a typical purchasing transaction, then show some typical "fixing the screwups" operations.

3.2.5.1 1. Typical Widget Purchase
3.2.5.1.1 Goal / Context

An engineer needs to purchase widgets for a project, finds the SmallCo offering in a catalog and initiates the purchase.

3.2.5.1.2 Scenario / Steps

A typical transaction looks like this:

  1. Engineer finds SmallCo widget offering in an internal web catalog of goods and services.

  2. Engineer initiates a request for quote to SmallCo.

  3. SmallCo responds with a quote.

  4. Engineer initiates a purchase order that is sent to SmallCo.

  5. SmallCo receives the P.O. ships the widget and sends an invoice.

  6. BigCo receives the widget, checks that the received widget is really what was ordered, and initiates payment through a financial service.

  7. BigCo sends a payment advice to SmallCo.

There are lots of other messages that might be sent in a purchasing scenario. This is just sort of a bare-bones illustrative example.

The messages that go from BigCo to SmallCo are generated automatically by the software systems in BigCo. SmallCo, on the other hand, is using a shareware web services module that implements the web services necessary for these commercial transactions in a generic way but knows nothing about the industry-specific business protocols involved.

3.2.5.1.3 Extensions

Failure of the process at each step triggers appropriate actions, often involving flagging the transaction for attention by a person in the purchasing department of BigCo or raising an error condition in the web service facility of SmallCo.

3.2.5.1.4 Technologies / Requirements

The basic transactions take place via Asynchronous Messaging. However, each of the steps of this process must also be reliable. That is, there is a process in place by which when a message is sent the sender knows that it will either get through or create an error condition, and that there is a high probability of it getting through. Each message generates a confirmation of receipt message back to the sender, that is, Request with Acknowledgement. In addition, each message carries a unique identifier, a date-time stamp (showing the time at which the message was sent, not necessarily the delivery time), and information that allows the messages to be logically ordered. (These capabilities will be exercised in subsequent scenarios). The identification requirements may be part of Conversational Message Exchange, although this Usage Scenario has not yet included these capabilities explicitly.

We are requiring here that the messages be ordered but not sequenced, even though many of the VAN's on which this usage case is based do offer sequencing. Sequencing would imply that each message between two partners in a given direction has a sequential index and that no gaps are allowed. One could then, if desired, set up a process in which sequential receipt were enforced. That is, if BigCo gets message 22 from SmallCo and then receives message 24, BigCo would not accept message 24 (presumably holding it in some sort of buffer) until message 23 arrived, and probably would throw some sort of error if it did not arrive in some time period. We are not including this type of operation in the usage case because we feel that it is fairly unusual actually to make use of this logic. Moreover, if desired such sequencing could be made part of the payload and included in the business logic. The only reason we can think of to include sequencing in the enveloping mechanism would be to enforce sequencing across different types of business transaction, and we don't think that this is likely to be very useful. Would you want to hold up an invoice, for example, because a message involving HR had not arrived yet?

The usual security suspects (Accessibility, Authentication, Authorization, Confidentiality, Integrity and non-Repudiation) are all matters of concern. Non-Repudiation is of particular importance, although in practical terms less in terms of a legal process than simply the ability to say, "You got this invoice on March 24, and here is your signed confirmation of receipt". That is, by far the most common scenarios that require non-repudiation involve people in both companies trying, in good faith, to sort out what has gone wrong in some screwed up transaction. What is required in these cases is an unambiguous record, not rock-solid legal proof. Taking these issues to court is a very rare occurrence given an ongoing trading relationship between businesses. This is probably a less strong requirement than what is usually called "non-repudiation", but stronger than "auditing". Perhaps we can call this requirement "reconciliation". Various aspects of Reconciliation will be exercised in the use cases below.

Other aspects of security are also necessary. It must be possible for both BigCo and SmallCo to be sure that the messages they receive are actually from the company that they are supposed to be. That is, each company must be able to identify itself unambiguously (Authentication). In addition, there is the question of what actions the company is authorized to request from the web service. For example, BigCo needs to be able to query SmallCo's web service for a list of messages that have been sent between these two participants, but not for information about transactions with other companies that purchase widgets from SmallCo. Both companies need to be confident that the communications cannot be tampered with or observed by third parties, and that third parties cannot send communications pretending to be who they are not.

The SmallCo web service knows how to receive and send messages and will present these messages to users at SmallCo in a browser window. A SmallCo employee transfers information from the XML to their bookkeeping system via cut and paste. How does SmallCo generate the XML that goes into the messages that it sends? The web service knows how to generate the envelop (message ID, datetime, and so on), but not the message contents. To assist SmallCo's either BigCo or the industry standards body provides a web site that implements messages like "quote" and "invoice" in a web form into which a SmallCo person types information and which returns suitably formatted XML in the browser window.

3.2.5.2 2. Transaction Log Mismatch
3.2.5.2.1 Goal / Context

BigCo has instituted an automated reconciliation procedure to check on a monthly basis that messages have not been lost by comparing transaction logs from BigCo and SmallCo. In this scenario a discrepancy is found and addressed.

3.2.5.2.2 Scenario / Steps
  1. At the end of the month the Bigco web service automatically sends a request to the SmallCo web server for a list of the message ID's sent and received during that month.

  2. The SmallCo response is automatically checked against a list of messages processed by the purchasing system, and it is found that a whole bunch of messages show up on SmallCo's logs as sent to Bigco but not on BigCo's as received and processed.

  3. The BigCo web service raises an error condition that is sent to a person in the Purchasing Department who looks into the situation.

  4. It turns out that all the lost messages were from a particular weekend during which a server at BigCo was misconfigured and was trashing messages.

  5. BigCo sends a request to the SmallCo web server to resend the messages in question that have been lost.

3.2.5.2.3 Extensions

Somebody from BigCo calls up SmallCo, apologizes, and explains why they have not been responding in a timely manner.

3.2.5.2.4 Technologies / Requirements

Reconciliation: the SmallCo web service must be able to respond to (authorized) requests for information about what messages have been received and/or sent in a time period or between marker messages. The web service must be capable of resending messages on request.

3.2.5.3 3. SmallCo Incorrectly Thinks They Weren't Paid
3.2.5.3.1 Goal / Context

SmallCo thinks that it has not been paid because they did not get the payment advice. Well, they got it but didn't put it into their records so they think that they have not been paid. However, the payment was really made through the bank into their account. The objective here is to clean up the mess so everyone agrees what has happened.

3.2.5.3.2 Scenario / Steps
  1. SmallCo calls their contact in BigCo (a business analyst) and complains that they were not paid for a particular order. They give the business analyst the ID of the invoice message.

  2. The BigCo purchasing department pulls all the messages involved with this transaction (the transaction is labeled in the business process definition, not the web service envelop), and finds that payment was actually made and confirmed by the bank.

  3. BigCo sends copies of this information to SmallCo, including the message ID of the payment advice and identifying information for the bank payment. The bank payment information includes information that links it to the ID of this transaction (again, this is in the business process definition, not the web service envelop).

  4. SmallCo queries its web service for the payment advice message, checks its own bank statements, and eventually realizes that they really were paid and did not book it properly.

3.2.5.3.3 Extensions

SmallCo calls BigCo and says, "Oops. Looks OK now."

3.2.5.3.4 Technologies / Requirements

Reconciliation: the key here is to be able to retrieve messages by ID. The linkage of the messages into a transaction is beyond the scope of the web service itself and belongs in the definition of the business process.

3.2.5.4 4. SmallCo Really Wasn't Paid
3.2.5.4.1 Goal / Context

SmallCo sent an invoice and this time they really didn't get paid. After a while they call BigCo as in the previous scenario. The objective here is to get SmallCo paid.

3.2.5.4.2 Scenario / Steps
  1. SmallCo calls their contact in BigCo (a business analyst) and complains that they were not paid for a particular order. They give the business analyst the ID of the invoice message.

  2. The BigCo purchasing department pulls all the messages involved with this transaction (the transaction is labeled in the business process definition, not the web service envelop), and finds that payment really wasn't made. Somebody didn't approve it and the transaction died. (Of course, this is after a flurry of documents, letters, and phone calls back and forth, not to mention various emails within BigCo, many of them to people that have never heard of SmallCo or anything else that has anything to do with the problem at hand).

  3. Somebody at BigCo finally says, "Oops, we really didn't pay it". BigCo initiates payment.

3.2.5.4.3 Extensions

BigCo calls SmallCo and says, "Oops, sorry. My bad. The check is in the mail."

3.2.5.4.4 Technologies / Requirements

The requirements are really the same as for the last scenario. We just wanted to illustrate that there are all sorts of ways the business process can get screwed up, no matter what technical processes are in place, and that the fault may lie on either side of the transaction.

4 References

4.1 Informative References

1
Message Service Specification, ebXML TRP Version 1.0 (See http://www.ebxml.org/specs/ebMS.pdf.)
2
SOAP Messages with Attachments (See http://www.w3.org/TR/SOAP-attachments.)
3
XML Protocol (SOAP) Requirements (See http://www.w3.org/TR/2001/WD-SOAP-reqs-20010319/#N2082.)
4
Web Services Routing Protocol (WS-Routing) (See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsrvspev/html/ws-routing.asp.)
5
Web Services Architecture Charter (See http://www.w3.org/2002/01/ws-arch-charter.)
6
Web Services Architecture Discussion Archive (See http://lists.w3.org/Archives/Public/www-ws-arch/.)
7
Web Services Architecture Comments Archive (See http://lists.w3.org/Archives/Public/ws-arch-comments/.)
1
XML Protocol Usage Scenarios (See http://www.w3.org/TR/2001/WD-xmlp-scenarios-20011217/.)

A Part 1 Change Log (Non-Normative)

A.1 Web Services Architecture Usage Scenarios Changes

20020619HHImported Hugo Haas's travel agent use case and Roger Cutler's EDI-like Purchasing use case.
20020420-20020501DBOConverted to WS Arch document, added wsd usage scenarios, did personal edits on various scenarios to make more generic, re-organized numbering, added numerous scenarios (security, asynchrony, transactions, discovery), created template, put in first swag at requirements, priorities, candidate technologies