W3C

Web Services Usage Scenario: EDI-like Purchasing

19 June 2002

This version:
???? (XML version and HTML version)
Previous versions:
http://lists.w3.org/Archives/Public/www-ws-arch/2002May/att-0323/02-WS-EDI_Use_Case.htm
Editor:
Roger Cutler, ChevronTexaco <RogerCutler@ChevronTexaco.com>

Abstract

This document develops a Use Case similar to current EDI practices in order to generate requirements for the Web Services Architecture Working Group. It draws on experience gained in EDI to focus on issues that have been found to be important in real-life implementations of eBusiness transactions.

I used as a template the Travel Reservation Use Case prepared by Hugo Haas, which itself was based on a methodology defined by a breakout session of the April 2001 face-to-face meeting. The use case developed here might be viewed as similar to what one might find if one drilled down in detail into the B2B interactions involved in the Travel Reservation Use Case. For example, an interaction between the Travel Agent and a hotel might look similar to the scenarios discussed below. One might actually consider combining the use cases so the interactions described here are part of the Travel Reservation Use Case, but the result would probably be too bulky and complex for one document.

Status of this Document

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

It is a work in progress. Please send comments to the www-ws-arch publicly archived mailing list.

Table of Contents

1 Description
2 Scope
3 Stakeholders / Interests
4 Actors & Goals
5 Use Cases
5.1 1. Typical Widget Purchase
5.1.1 Goal / Context
5.1.2 Scenario / Steps
5.1.3 Extensions
5.1.4 Technologies / Requirements
5.2 2. Transaction Log Mismatch
5.2.1 Goal / Context
5.2.2 Scenario / Steps
5.2.3 Extensions
5.2.4 Technologies / Requirements
5.3 3. SmallCo Incorrectly Thinks They Weren't Paid
5.3.1 Goal / Context
5.3.2 Scenario / Steps
5.3.3 Extensions
5.3.4 Technologies / Requirements
5.4 4. SmallCo Really Wasn't Paid
5.4.1 Goal / Context
5.4.2 Scenario / Steps
5.4.3 Extensions
5.4.4 Technologies / Requirements

Appendix

A Acknowledgements


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.

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 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.

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.

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.

5.1 1. Typical Widget Purchase

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.

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.

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.

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.

5.2 2. Transaction Log Mismatch

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.

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.

5.2.3 Extensions

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

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.

5.3 3. SmallCo Incorrectly Thinks They Weren't Paid

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.

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.

5.3.3 Extensions

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

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.

5.4 4. SmallCo Really Wasn't Paid

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.

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.

5.4.3 Extensions

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

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.

A Acknowledgements

Thanks to Hugo Haas for his help with getting this document into into XML format.