1. CGI input
Only one CGI field (sent by the calling page to our script 'ecatreq') is interpreted. This field must be named 'CBLENCODED' (the name is not case-sensitive). The value (contents) of the field is the full XML request.
This field name is negotiable. If for some reason a vendor needs to send the field named something other than CBLENCODED it can easily be special-cased, however, it will require a code change on our end.
Despite the formatting of the examples later in this document, it is not necessary to put any newlines/line breaks into the XML request; you may find it is easier to send the raw XML if it does not contain any.
Our XML parser makes a few rigid assumptions. Two of them are of concern to the sender:
a. We ignore <non-paired tags/>. All tags are assumed to come in pairs, a start tag always has a matching end tag, with the actual information between them.
b. We only read tag names, not their attributes. That is, in a tag of the form <name attrib=value>, we ignore everything inside the brackets after the tag name.
2. XML generics
The XML request has three overall sections: The OrderRequestHeader contains general information about the buyer and seller and about the order as a whole, the OrderRequestSummary contains information about the total number and cost of items being ordered, and the OrderRequestDetail contains the line items - information about the actual items being purchased/requested.
There is always an outer tagset <OrderRequest>. This is always the outermost enclosing tag of the XML request.
A valid XML request will therefore have outer tags like this:
<OrderRequest>
<OrderRequestHeader>
(tags/subheadings enclosing general information)
</OrderRequestHeader>
<OrderRequestSummary>
(tags/subheadings enclosing totals information)
</OrderRequestSummary>
<OrderRequestDetail>
(tags/subheadings enclosing line item information)
</OrderRequestDetail>
</OrderRequest>
3. OrderRequestHeader fields
a. Vendor Name. We need to be informed of the exact text of the vendor name you choose to supply here, as we match this against a string elsewhere in the code to identify you.
b. Tracking Number. This is a unique identifier for each order generated by the vendor. We don't care how the vendor generates these, so long as every order we receive from the vendor has a different one.
c. Delivery Information. We check for the following fields:
- the purchaser's name
- the purchaser's MIT building
- the purchaser's room/office number
- a supplemental line of street/address information
- a city
- a state
- a zip code
Almost all MIT orders are delivered to a central, known, "loading dock" address which need not be specified; generally the building/room number suffices for delivery. The additional information is for cases where it does not.
d. Order Date. This is the date the order was placed. The date should be provided in YYYYMMDD format.
4. OrderRequestSummary fields
a. Item Count. This is the total number of line items to come.
b. Item Total. This is the total monetary value of the order.
5. OrderRequestDetail fields
The line item fields described below are contained in a ListOf iteration, where several enclosing tags of the same name are enclosed in an outer tagset of the format ListOfName, where Name is the repeated tag within.
<ListOfItemDetail>
<ItemDetail>
(data for first line item)
</ItemDetail>
<ItemDetail>
(data for second line item)
</ItemDetail>
</ListOfItemDetail>
This is the only case where a non-unique XML tag hierarchy may be used.
Note: The ListOf syntax is required where shown below, even if there is only one set of tags within (i.e. the example below only has a single "line item" but still needs <ListOfItemDetail>). This is also the case with Price data; you are required to have an enclosing <ListOfPrice>, even though for our purposes there will always be one and only one block of price info per line item.
The "False item" (SellerLineItemNum) noted below in the example block is used by one of our vendors for "line items" which are significant to them (they contain additional product details) but which are not useful to us. If this field is present and non-empty for a given line item, the entire line item will be ignored. Any line item which does not have a BuyerLineItemNum will also be ignored.
For the item description, the first thirty characters will be used as our "short description" and the entire text, including the first thirty, will be used as our "long description."
6. XML example block
Locations where the actual data would go are shown by placeholders in parentheses. Although there is only one "line item" given, there could be many more; please see the comments on the repeating ItemDetail above.
Line breaks are for clarity only.
<OrderRequest>
<OrderRequestHeader>
<OrderRequestNumber>
<SellerOrderRequestNumber>(Tracking number)</SellerOrderRequestNumber>
</OrderRequestNumber>
<OrderRequestIssueDate>(Order date)</OrderRequestIssueDate>
<OrderRequestParty>
<SellerParty>
<Party>
<PartyID>
<Identifier>
<Agency>
<AgencyDescription>(Vendor name)</AgencyDescription>
</Agency>
</Identifier>
</PartyID>
</Party>
</SellerParty>
<ShipToParty>
<Party>
<NameAddress>
<Name1>(Purchaser's name)</Name1>
<Building>(Building)</Building>
<RoomNumber>(Room number)</RoomNumber>
<StreetSupplement1>(Additional address line)</StreetSupplement1>
<City>(City)</City>
<Region>
<RegionCoded>(State)</RegionCoded>
</Region>
<PostalCode>(Zip code)</PostalCode>
</NameAddress>
</Party>
</ShipToParty>
</OrderRequestParty>
</OrderRequestHeader>
<OrderRequestSummary>
<OrderSummary>
<NumberOfLines>(Item count)</NumberOfLines>
<TotalAmount>
<MonetaryValue>
<MonetaryAmount>(Item total)</MonetaryAmount>
</MonetaryValue>
</TotalAmount>
</OrderSummary>
</OrderRequestSummary>
<OrderRequestDetail>
<OrderDetail>
<ListOfItemDetail>
<ItemDetail>
<BaseItemDetail>
<LineItemNum>
<BuyerLineItemNum>(Item num)</BuyerLineItemNum>
<SellerLineItemNum>(False item - see comments)</SellerLineItemNum>
</LineItemNum>
<TotalQuantity>
<Quantity>
<QuantityValue>(Quantity)</QuantityValue>
<UOMCoded>(Unit of measurement)</UOMCoded>
</Quantity>
</TotalQuantity>
<ItemIdentifiers>
<ItemDescription>(Item description - see comments)</ItemDescription>
<PartNumbers>
<SellerPartNumber>
<PartNum>
<PartID>(Vendor's part number)</PartID>
</PartNum>
</SellerPartNumber>
</PartNumbers>
</ItemIdentifiers>
</BaseItemDetail>
<PricingDetail>
<ListOfPrice>
<Price>
<UnitPrice>
<UnitPriceValue>(Price)</UnitPriceValue>
</UnitPrice>
</Price>
</ListOfPrice>
</PricingDetail>
</ItemDetail>
</ListOfItemDetail>
</OrderDetail>
</OrderRequestDetail>
</OrderRequest>