The majority of cXML documents are sent server-to-server via HTTP(S) POST requests where the POST body is the cXML. The only exception is the shopping cart (
PunchOutOrderMessage) which is transmitted from the shoppers browser to their eProcurement system as part of an HTML form.
Example cXML HTTP POST Request
POST /cxml HTTP/1.1 Host: www.example.com Content-Type: text/xml; charset="UTF-8" Content-Length: 284 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.041/cXML.dtd"> <cXML payloadID="firstname.lastname@example.org" timestamp="2018-04-07T16:16:53-05:00"> <Header> </Header> <Request deploymentMode="production"> </Request> </cXML>
cXML Document Structure
The first line in a cXML document must be:
<?xml version="1.0" encoding="UTF-8"?>. Encodings other than UTF-8 may be supported but should be avoided when possible.
The second line must be the DOCTYPE line which will vary depending on the DTD being used:
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.041/cXML.dtd">.
cXML element must follow the DOCTYPE line and include the
cXML[@payloadID] must be a unique number, used for logging purposes to identify documents that might have been lost or had problems. This value should not change for retry attempts. For transactional documents, the payloadID should be saved in the application generating the document and the application receiving the document. The recommended format for the value is
<unix_timestamp>.<process_id>.<5_random_digits>@<hostname>. For example:
timestamp attribute must be the ISO 8601 date/time of when the document was generated. For example:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.041/cXML.dtd"> <cXML payloadID="email@example.com" timestamp="2018-04-07T16:16:53-05:00"> <Header> <!-- Credentials go here --> </Header> <!-- Message, Request, or Response element goes here --> </cXML>
Request elements include a
deploymentMode attribute that should be set to "test" or "production". It is important to set this attribute correctly as some systems will handle requests differently depending on this value.
Most cXML documents contain a Header element which can include 3 container elements for credentials:
Sender. The cXML standard allows the credentials to identify buyers and suppliers using different domains (eg DUNS, NetworkId). In practice, a simplified version of the standard is typically used which is summarized below. Refer to the cXML User Guide for a detailed explanation of the
Credential[@domain] attribute should be set to
NetworkId unless an actual DUNS number is being used, in which case it should be set to
Create a data model for storing cXML connections in a database table or file. New connections should be created for each buying organization accessing the PunchOut site. Some buying organizations may require multiple connections to access different catalogs.
A short description of the connection
A unique username for the buyer
A hash of the password using a modern hashing algorithm
Outbound Test URL
URL to send test documents to
Outbound Prod URL
URL to send production documents to
Associate the connection with a buying organization or catalog
Receiving cXML Documents
When a cXML request is received, search for a connection with a
Sender/Credential/Identity that matches the username and a
Sender/Credential/SharedSecret that matches the password. If no connection is found, repeat the process using the
From/Credential/Identity to match against the username where the
Sender/Credential/SharedSecret matches the password. This process will be compatible with the majority of eProcurement systems.
Sending cXML Documents
When sending cXML documents to an eProcurement system (order confirmations, ship notices, invoices, etc), the username should be used to populate the
To/Credential/Identity field and the password should populate the
Sender/Credential/Identity should be populated with an identifier representing the name of the supplier. Test documents should be sent to the "Outbound Test URL" and production documents should be sent to the "Outbound Prod URL". In both cases, the
deploymentMode attribute should be set correctly.
Sample cXML Credentials
<Header> <From> <Credential domain="NetworkId"> <Identity>buyer_id</Identity> </Credential> </From> <To> <Credential domain="DUNS"> <Identity>supplier_id</Identity> </Credential> </To> <Sender> <Credential domain="NetworkId"> <Identity>sender_id</Identity> <SharedSecret>password</SharedSecret> </Credential> <UserAgent>Application Name v1.2.3</UserAgent> </Sender> </Header>