cXML Overview

Receiving/Sending cXML

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="1539050765.83749@example.com" 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">.

The cXML element must follow the DOCTYPE line and include the payloadID and timestamp attributes.

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: 1539050765.512.83749@example.com

The timestamp attribute must be the ISO 8601 date/time of when the document was generated. For example: 2018-04-07T16:16:53-05:00

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.041/cXML.dtd">
<cXML payloadID="1539050765.512.83749@example.com" timestamp="2018-04-07T16:16:53-05:00">
  <Header>
    <!-- Credentials go here -->
  </Header>
  <!-- Message, Request, or Response element goes here -->
</cXML>

Deployment Mode

The Message and 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.

Credentials

Most cXML documents contain a Header element which can include 3 container elements for credentials: From, To, and 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 Header / Credential elements.

Credential[@domain]

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

eCommerce Implementation

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.

Field Description

Description

A short description of the connection

Username

A unique username for the buyer

Password Hash

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

Account

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/SharedSecret. The From/Credential/Identity and 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>

Next Steps

Share