Supplier Catalog PO cXML Technical Specification

Updated June 06, 2024 10:15

Article Contents

Overview

Interface Responsibilities

Process Flow

Failure Conditions

Notes and Limitations

Transaction Data Elements

Data Format Examples

Configuration Requirements and Consideration

References

Overview

The purpose of this document is to detail the responsibilities, processing flow, and communication details agreed upon by ESM Solutions and Third Parties for transmitting Purchase Order data.

The Process Flow section describes the lifecycle of a purchase across the two systems.

The Interface Responsibilities section delineates the functionality required under the agreement for each company to fulfill their interface obligations.

The sections thereafter describe the technical aspects of the communication mechanism.

Interface Responsibilities

ESM Solutions

Provide a mechanism for communicating Purchase Order data, via 32-bit SSL web posts in XML format to the third-party order entry system.
Received third-party purchase order acknowledgements.
Provide an automated retry mechanism to account for internet timeouts and communication outages.

Third-Party

Provide a web-enabled mechanism to accept and process ESM Solutions Purchase Order transaction data.
Provide real-time web responses detail either the success or failure of each transaction.

Process Flow

Diagram

Flow Steps

User completes actions within the ESM Purchase application which generates the release of a Purchase Order.
The ESM Solutions server communicates the data to the third party via an Internet web post with defined XML using cXML standardized methods.
The third-party synchronously responds to the web post with either a success or failure message. Failures will be accompanied with an appropriate error message. The definition of failure is detailed in the next section of this document.
In the event of an error, ESM Solutions corrects the date and retransmits or cancels the transaction, dependent on the situation.

Failure Conditions

Definition

A failure during this process is defined in any of the following scenarios:

Improper formatting
Invalid customer identifier
Supplier processing failure

Any issue that occurs outside of the above scope will not be considered a failure and the transaction will be accepted as valid and be considered a 'manual data issue'. In this instance the supplier will be required to communicate directly with the customer to resolve outside of this integration process.

Example Failure Conditions

Invalid or unrecognized customer identifier
Invalid XML format

Example Manual Data Issues

Unrecognized Building ID
Unrecognized Product ID
Invalid price
Duplicate Purchase Orders

Notes and Limitations

The XML samples in this document are standard cXML format. They contain all the fields supported by the integration. However, ESM Solutions has the capability to reformat each with supplier-specific style sheets to match the expected formats of existing order processing mechanisms.
The Data Element Definitions section contains all dynamic fields supported by the interface. However, any “static” (i.e. the same on every transaction) fields can be implemented as part of the custom integration process.
Within ESM Purchase system, users are allowed to aggregate requisitions (carts) across purchase orders. This means that a single requisition may be split up, and its line-items may finally appear on several different purchase orders (along with line items from several different requisitions).
To facilitate tracking and desktop delivery, ESM Purchase system allows users to have more than one purchase order line item for the same product.
Users in ESM Purchase have the capability to override prices on requisition items, but the supplier may choose to use current negotiated item price, tax, and shipping values if those sent on purchase orders are incorrect.
For the sake of generic version support and minimization of network “chatter”, it is strongly recommended that XML-processing URLs do not perform any client redirects.
All XML data transmissions will be implemented as server-to-server posts of streamed XML documents. Browser-based XML posts and form-level/query string-level XML are not supported.
ESM Solutions requires HTTPS (128-bit encryption) support for all cross-system web posts.

Transaction Data Elements

Purchase Order Elements

Purchase Order Elements
XML Element Type	Data Definition	Cardinality	Description
/Header/From/Credential @domain = "NetworklD" /Identity (aka VendorsCustomerlD)	Text (255)	One per transaction	Supplier's Identifier for the Customer
/Request/OrderRequest/OrderRequestHeader @orderID	Text (20)	One per transaction	Customer's Purchase Order Number
/Request/OrderRequest/OrderRequestHeader @OrderDate	YYYY-MM-DD	One per transaction	Purchase Order Date
/Request/OrderRequest/OrderRequestHeader/Total	Money	One per transaction	Total dollar amount for PO
/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/DeliverTo	Text (71)	More than one per transaction	Customer delivery building contact name
/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/Phone	Text (20)	One per transaction	Customer delivery building contact phone
/Request/OrderRequest/OrderRequestHeader/ShipTo @addressID	Text (15)	One per transaction	Customer's ID for Building**
/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress @name	Text (50)	One per transaction	Customer delivery building's name
/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Street	Text (50)	Multiple per transaction	Customer delivery building's address (Street1, Street2)
/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/City	Text (50)	One per transaction	Customer delivery building's address (City)
/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/State	Text (2)	One per transaction	Customer delivery building's address (State)
/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Code	Text (10)	One per transaction	Customer delivery building's address (Postal Code)
/Request/OrderRequest/OrderRequestHeader/BillTo/Address/Phone	Text (20)	One per transaction	Customer Billing contact phone
/Request/OrderRequest/OrderRequestHeader/BillTo/AddressID	Text (15)	One per transaction	Customer's ID for Billing Building**
/Request/OrderRequest/OrderRequestHeader/BillTo/Address/Name	Text (50)	One per transaction	Customer billing building's name
/Request/OrderRequest/OrderRequestHeader/BillTo/Address/PostalAddress/Street	Text (50)	Multiple per transaction	Customer billing building's address (Street 1, Street 2)
/Request/OrderRequest/OrderRequestHeader/BillTo/Address/PostalAddress/City	Text (50)	One per transaction	Customer billing building's address (City)
/Request/OrderRequest/ItemOut/ItemDetail/ManufacturerPartID	Text (30)	One per item on PO	Manufacturer Part Number
/Request/OrderRequest/ItemOut/ItemDetail/UnitOfMeasure	Text (20)	One per item on PO	Item's unit-of-measure
/Request/OrderRequest/ItemOut/Contact	Text (25)	One per item on PO	Desktop Deliver-to person's name
/Request/OrderRequest/ItemOut/Comments	Text (3000)	One per item on PO	User comments or instructions

*Supplier-required values that may be hard-coded by ESM Solutions are not included in the field definitions.

**Building Ids are defined and maintained solely by the customer. If the Supplier utilizes these values, the communication of any additions or changes of Ids to the Supplier will be the responsibility of the Customer. Transmission of an ID that is blank or unrecognized by the Supplier is not a valid failure condition for a transaction – It is the supplier’s responsibility to resolve the inconsistency directly with the customer

Purchase Order Response Elements

Purchase Order Response Elements
XML Element Type	Data Definition	Cardinality	Description
/Response/Status @code	Text (3)	One per Transaction	HTTP Status code
/Response/Status @text	Text (5000)	One per Transaction	Status Description

Data Format Examples

This section contains sample transactions in default formats. Stylesheet transformations and some custom code can be applied to conform with supplier format requirements. Please note that any static data (i.e. data that is the same across all transactions) not supported in the Data Element Definitions section can be implemented by the stylesheet transformation. The SenderCredential node is an example of this.

Sample XML Purchase Order

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.1.009/cXML.dtd">

<From>

</Credential>

</From>

<To>

</Credential>

</To>

<SharedSecret>Welcome</SharedSecret>

</Credential>

<UserAgent>Ariba Network V1.1</UserAgent>

</Sender>

</Header>

<Total>

</Total>

<Name xml:lang="en">Smithfield Elementary School</Name>

<DeliverTo>Sue Ellen</DeliverTo>

<Street>2 Walnut Grove</Street>

<Street>Suite 190</Street>

<City>Horsham</City>

<Country isoCountryCode="US">United States</Country>

</PostalAddress>

<Email name="default">sellen@eschoolmall.com</Email>

</TelephoneNumber>

</Phone>

</Address>

</ShipTo>

<Name xml:lang="en">Business Office</Name>

<Street>2 Walnut Grove</Street>

<Street>Suite 190</Street>

<City>Horsham</City>

<Country isoCountryCode="US">United States</Country>

</PostalAddress>

</TelephoneNumber>

</Phone>

</Address>

</BillTo>

<Description xml:lang="en-US">Shipping</Description>

</Shipping>

<Tax>

<Description xml:lang="en-US">State Tax</Description>

</Tax>

</Payment>

<Comments>Please Deliver During Normal Business hours</Comments>

</OrderRequestHeader>

</ItemID>

</UnitPrice>

<Description xml:lang="en">HP vp6310 Digital Projector-U.S. - English localization</Description>

<Classification domain="UNSPSC">unknown</Classification>

</ItemDetail>

</Contact>

<Comments>These are individual line item notes</Comments>

</ItemOut>

</ItemID>

</UnitPrice>

<Description xml:lang="en">HP Total Education Service</Description>

<Classification domain="UNSPSC">unknown</Classification>

</ItemDetail>

<Name xml:lang="en-US">Computer Lab</Name>

</Contact>

</ItemOut>

</OrderRequest>

</Request>

</cXML>

Sample Purchase Order Acknowledgement (successful)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.1.010/cXML.dtd">

</Response>

</cXML>

Sample Purchase Order Acknowledgement (unsuccessful)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.1.010/cXML.dtd">

</Response>

</cXML>

Configuration Requirements and Consideration

Implementation Configuration Requirements

A test Customer ID is needed prior to unit testing.
A shared secret should be provided if applicable.
A PO XML target address (test) is needed before any test orders are sent.
Acceptable version of cXML for the integration

Implementation Configuration Considerations

Are line item deliver to’s / desktop delivery information supported on supplier side of integration?
Is delivery date supported or ignored?
Are individual line item notes/comments supported?
Are PO Comments supported?
Is the supplier capable of handling P-Card payment data?
How are orders, which are received successfully, but fail supplier internal validation for one reason or another handled on the supplier side?

References

(1) cXML Specification - https://cxml.org/

PO cXML Integration Specification.pdf
(400 KB)

Article Contents

Overview

Interface Responsibilities

ESM Solutions

Third-Party

Process Flow

Diagram

Flow Steps

Failure Conditions

Definition

Example Failure Conditions

Example Manual Data Issues

Notes and Limitations

Transaction Data Elements

Purchase Order Elements

Purchase Order Response Elements

Data Format Examples

Sample XML Purchase Order

Sample Purchase Order Acknowledgement (successful)

Sample Purchase Order Acknowledgement (unsuccessful)

Configuration Requirements and Consideration

Implementation Configuration Requirements

Implementation Configuration Considerations

References

Articles in this section