Web service Usage Scenario:
EDI-like Purchasing

This documents attempts to put together a scenario involving a set of Web services to serve as an useful example for Web services and to generate requirements for the Web Services Architecture Working Group.

I used as a template the document prepared by Hugo Haas to show a travel reservation scenario.


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 involved with implementing 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.


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.

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.

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.

Use Cases

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

1. Typical Widget Purchase

Goal / Context

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

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.


Failure of the process at each step triggers appropriate actions, often involving flagging the transaction for attention by a person in the purchasing department.

Technologies / Requirements

Each of the steps of this process must take place via reliable messaging.  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.  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).

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.

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.

2. Transaction Log Mismatch

Goal / Context

BigCo has instituted an automated 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.

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.


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

Technologies / Requirements

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. SmallCo Incorrectly Thinks They Weren't Paid

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.

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.


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

Technologies / Requirements

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 (we think).

4. SmallCo Really Wasn't Paid

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.

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.


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

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.


Roger Cutler, RogerCutler@ChevronTexaco.com

Last modified: 2002-05-20 16:28:00 -0500