cXMLUsersGuide PDF
cXMLUsersGuide PDF
cXMLUsersGuide PDF
Guide
VERSION 1.2.014
O C T O B E R, 2 0 0 5
cXML License Agreement
1. Openness. cXML is designed and intended to be an open standard to facilitate electronic commerce. You are
welcome to use and adopt this standard, and to submit comments, recommendations, and suggestions to
cXML.org. Once submitted, your comments go through an approval process - and your comments may
ultimately be incorporated into cXML.
2. License. Subject to the terms and conditions herein, Licensor hereby grants to you a perpetual,
nonexclusive, royalty-free, worldwide right and license to use the Specification under the Licensor intellectual
property necessary to implement the Specification to (a) use, copy, publish, and distribute (including but not
limited to distribution as part of a separate computer program) the unmodified Specification, and (b) to
implement and use the Specification, including the cXML tags and schema guidelines included in the
Specification for the purpose of creating, distributing, selling or otherwise transferring computer programs that
adhere to such guidelines. If you use, publish, or distribute the unmodified Specification, you may call it
“cXML”.
3. Restrictions. Your rights under this License will terminate automatically without notice from Licensor if you
fail to comply with any terms of this License.
Licensor expressly reserves all other rights it may have in the material and subject matter of the Specification,
and you acknowledge and agree that Licensor owns all right, title, and interest in and to the Specification,
however, Licensor does not own the computer programs or related documentation you create, nor does
Licensor own the underlying XML or non-Ariba intellectual property from which cXML has been derived.
You agree to not assert any intellectual property rights that would be necessarily infringed by implementation
or other use of the Specification against Licensor or any other entity with respect to such implementation or
other use of the Specification; provided that your agreement to not assert shall cease to apply to any entity
including Licensor (except where Licensor or another entity is asserting intellectual property rights against
you as part of an assertion that you have breached this Agreement) that asserts against you that its intellectual
property rights are infringed by your implementation or other use of the Specification. If you publish, copy or
distribute the Specification, then this License must be attached. If you submit any comments or suggestions to
Licensor, and Licensor modifies the Specification based on your input, Licensor shall own the modified
version of the Specification.
4. No Warranty. YOU ACKNOWLEDGE AND AGREE THAT ANY USE OF THE SPECIFICATION BY
YOU IS AT YOUR OWN RISK. THE SPECIFICATION IS PROVIDED FOR USE “AS IS” WITHOUT
WARRANTY OF ANY KIND. LICENSOR AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES OF
ANY KIND, INCLUDING BUT NOT LIMITED TO ANY EXPRESS WARRANTIES, STATUTORY
WARRANTIES, AND ANY IMPLIED WARRANTIES OF: MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON-INFRINGEMNT. YOUR SOLE AND EXCLUSIVE REMEDY
RELATING TO YOUR USE OF THE SPECIFICATION SHALL BE TO DISCONTINUE USING THE
SPECIFICATION.
7. This License shall be deemed to have been made in, and shall be construed pursuant to the laws of the State
of California and the federal U.S. laws applicable therein, excluding its conflict of laws provisions. Any legal
action or proceeding relating to this License shall be instituted in a state or federal court in San Francisco,
Santa Clara or San Mateo County, California, and each party hereby consents to personal jurisdiction in such
counties. If for any reason a court of competent jurisdiction finds any provision, or portion thereof, to be
unenforceable, the remainder of this License shall continue in full force and effect.
8. You assume the entire risk resulting from your use of the Specification.
9. Complete Agreement. This License is the complete and exclusive statement, and an absolute integration of
the mutual understanding of the parties and supersedes and cancels all previous written and oral agreements
and communications relating to the subject matter of this License. You acknowledge that any material breach
by you of the provisions of the License will cause irreparable damage to Licensor and that a remedy at law will
be inadequate. Therefore, in addition to any and all other legal or equitable remedies, Licensor will be entitled
to seek injunctive relief necessary to remediate the breach of this License. Ariba, Inc. shall be deemed the
Licensor.
10. Notices. Any notice directed to Licensor must be sent in writing to [email protected].
7-19-04
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Audience and Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Which Chapters to Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Typography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Chapter 1
Introduction to cXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
cXML, an XML Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
cXML Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
PunchOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Purchase Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Types of Applications that Use cXML . . . . . . . . . . . . . . . . . . . . . . . . 22
Procurement Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Commerce Network Hubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
PunchOut Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Order-Receiving Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Content Delivery Strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
cXML DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Getting cXML DTDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Caching DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Profile Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
ProfileRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
ProfileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Service Status Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
XML Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Chapter 2
cXML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Protocol Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Request-Response Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
cXML Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
cXML Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Wrapping Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
cXML Envelope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
One-Way (Asynchronous) Model . . . . . . . . . . . . . . . . . . . . . . . . 50
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Transport Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Service Status Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Basic Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Type Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Base Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Chapter 3
Profile Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Introduction to the Profile Transaction . . . . . . . . . . . . . . . . . . . . . . . . 59
ProfileRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
ProfileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Option Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
From Buyer to Supplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
From Buyer to the Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
From a Network Hub to Supplier . . . . . . . . . . . . . . . . . . . . . . . . 67
From a Network Hub to Service Provider . . . . . . . . . . . . . . . . . . 69
From a Network Hub to Buyer . . . . . . . . . . . . . . . . . . . . . . . . . . 69
From Service Provider to Buyer . . . . . . . . . . . . . . . . . . . . . . . . . 70
Chapter 4
PunchOut Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
PunchOut Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Buying Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Suppliers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
PunchOut Event Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Steps 1 & 2: PunchOut Request . . . . . . . . . . . . . . . . . . . . . . . . . 75
Step 3: Product Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Step 4: Check Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Step 5: Transmittal of Purchase Order. . . . . . . . . . . . . . . . . . . . . 78
PunchOut Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
PunchOut Index Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
PunchOutSetupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
PunchOutSetupResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
PunchOutOrderMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Modifications to the Supplier’s Web Pages . . . . . . . . . . . . . . . . . . . . 89
Launch Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Start Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Sender Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Order Receiver Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
PunchOut Website Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Implementation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Buyer and Supplier Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Personalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
PunchOut Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Sourcing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
PunchOutSetupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
PunchOutSetupResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
PunchOutOrderMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Direct PunchOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Authentication Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
ProfileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Chapter 5
Purchase Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Purchase Order Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
OrderRequest Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
OrderRequestHeader Element . . . . . . . . . . . . . . . . . . . . . . . . . . 118
ItemOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Response to an OrderRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Accepting Order Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Chapter 6
Path Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Overview of Path Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Path Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Router Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Copy Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Adding Nodes to PunchOutOrderMessage. . . . . . . . . . . . . . . . . . . . 160
Path Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Creating OrderRequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Path Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Other Routable Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
PunchOutSetupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
ConfirmationRequest and ShipNoticeRequest . . . . . . . . . . . . . 164
CopyRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Chapter 7
Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Overview of Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
PaymentRemittance DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Payment Document Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . 168
PaymentProposalRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
PayableInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
PaymentMethod. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
PaymentPartner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Contact. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
GrossAmount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
DiscountAmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
AdjustAmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
NetAmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
PaymentRemittanceRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
PaymentRemittanceRequestHeader. . . . . . . . . . . . . . . . . . . . . . 178
PaymentRemittanceSummary . . . . . . . . . . . . . . . . . . . . . . . . . . 180
RemittanceDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
PaymentRemittanceStatusUpdateRequest . . . . . . . . . . . . . . . . . . . . 183
DocumentReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
PaymentRemittanceStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Example Payment Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
PaymentProposalRequest Example . . . . . . . . . . . . . . . . . . . . . . 185
PaymentRemittanceRequest Example . . . . . . . . . . . . . . . . . . . . 186
PaymentRemittanceStatusUpdateRequest Example . . . . . . . . . 189
Chapter 8
TimeCard Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
TimeCard Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Supplier to Buyer Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Buyer to Supplier Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
TimeCard Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
OrderInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Contractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
ReportedTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
SubmitterInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
ApprovalInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
DocumentReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
TimeCard Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Chapter 9
Master Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Overview of Master Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
MasterAgreementRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
MasterAgreementRequestHeader Element . . . . . . . . . . . . . . . . 203
AgreementItemOut Element . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Chapter 10
Later Status Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Overview of Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
StatusUpdateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
DocumentReference Element . . . . . . . . . . . . . . . . . . . . . . . . . . 207
PaymentStatus Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
SourcingStatus Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
InvoiceStatus Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
ConfirmationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
OrderReference Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
ConfirmationHeader Element . . . . . . . . . . . . . . . . . . . . . . . . . . 213
ConfirmationItem Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
ShipNoticeRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
ShipNoticeHeader Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
ServiceLevel Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Route Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
CarrierIdentitifier Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
ShipmentIdentifier Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
PackageIdentification Element . . . . . . . . . . . . . . . . . . . . . . . . . 232
ShipNoticePortion Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
ShipNoticeItem Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
OrderReference Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Chapter 11
Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Overview of Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Early InvoiceRequest Document . . . . . . . . . . . . . . . . . . . . . . . . 238
Debit and Credit Amounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Shipping Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Types of Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Invoice DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
InvoiceDetailRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
InvoiceDetailRequestHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
InvoiceDetailOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
InvoiceDetailHeaderOrder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
InvoiceDetailSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Invoice Status Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Example Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Standard Header Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Standard Detail Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Service Invoice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Marketplace Invoice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Chapter 12
Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Catalog Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Supplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
TypeProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
TypeAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
PrimitiveType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Subscription Management Definitions . . . . . . . . . . . . . . . . . . . . . . . 287
Supplier Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Catalog Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Catalog Upload Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
CatalogUploadRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Chapter 13
Get Pending/Data Download Transaction . . . . . . . . . . . 303
Introduction to Get Pending/Data Download Transaction . . . . . . . . 303
GetPendingRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
GetPendingResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
No Documents Waiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Documents Waiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
DataRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
DataResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Chapter 14
Provider PunchOut Transaction . . . . . . . . . . . . . . . . . . . 311
Message Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
ProviderSetupRequest Document . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
ProviderSetupResponse Document. . . . . . . . . . . . . . . . . . . . . . . . . . 316
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
ProviderDoneMessage Document . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
OriginatorCookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
ReturnData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
ReturnValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Chapter 15
Alternative Authentication Methods . . . . . . . . . . . . . . . . 323
Message Authentication Code (MAC) . . . . . . . . . . . . . . . . . . . . . . . 323
Overview of MACs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Computation Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Creation and Expiration Dates. . . . . . . . . . . . . . . . . . . . . . . . . . 324
Computation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
ProfileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
CredentialMac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Auth Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
AuthRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
AuthResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Chapter 16
cXML Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . 333
Digital Signature Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Options for Signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Signing cXML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
cXML Digital Signatures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Error Status Codes for Digital Signatures . . . . . . . . . . . . . . . . . 337
Digital Signature Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Appendix A
New Features in cXML 1.2.014 . . . . . . . . . . . . . . . . . . . . .341
Scheduled Payment Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
InvoiceIDInfo Added to StatusUpdateRequest. . . . . . . . . . . . . . . . . 341
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Preface
This document describes how to use cXML (commerce eXtensible Markup
Language) for communication of data related to electronic commerce.
Preface
cXML is an open versatile language for the transaction requirements of:
Preface
• Buyers
• Suppliers
• E-commerce service providers
Preface
This document does not describe how to use specific procurement applications or
commerce network hubs.
Preface
Typography
cXML elements and attributes are denoted with a monotype font. cXML element and
attribute names are case-sensitive. Both are a combination of lower and uppercase,
with elements beginning with an uppercase letter, and attributes beginning with a
lowercase letter. For example, MyElement is a cXML element, and myAttribute is a
cXML attribute.
The following table describes the typographic conventions used in this book:
1 Introduction to
cXML
This chapter introduces cXML (commerce eXtensible Markup Language) for
electronic-commerce transactions.
1 Introduction to
• cXML Capabilities
cXML
• Types of Applications that Use cXML
• Content Delivery Strategy
• cXML DTDs
• Profile Transaction
1 Introduction to
• XML Utilities
cXML
cXML, an XML Implementation
XML (eXtensible Markup Language) is a meta-markup language used to create
syntaxes for languages. It is also a standard for passing data between applications,
particularly those that communicate across the Internet.
1 Introduction to
XML documents contain data in the form of tag/value pairs, for example:
cXML
<DeliverTo>Joe Smith</DeliverTo>
The DTDs for cXML are files available on the www.cXML.org website. For more
information, see “Getting cXML DTDs” on page 25.
cXML Capabilities
cXML allows buying organizations, suppliers, service providers, and intermediaries
to communicate using a single, standard, open language.
cXML transactions consist of documents, which are simple text files containing
values enclosed by predefined tags. Most types of cXML documents are analogous to
hardcopy documents traditionally used in business.
• Catalogs
• PunchOut
• Purchase Orders
Catalogs
Catalogs are files that convey product and service content to buying organizations.
They describe the products and services offered by a supplier and their prices, and
they are the main communication channel from suppliers to their customers.
Suppliers create catalogs so that organizations that use procurement applications can
see their product and service offerings and buy from them. Procurement applications
read catalogs and store them internally in their databases. After a buying organization
1 Introduction to
cXML
approves a catalog, that content is visible to users, who can choose items and add
them to purchase requisitions.
1 Introduction to
cXML
Sending product and service
1 Introduction to
content to a buying organization
cXML
Suppliers can create catalogs for any product or service, regardless of how it is
measured, priced, or delivered.
For each item in a catalog, basic information is required, and optional information
enables advanced catalog features, such as multi-language descriptions.
1 Introduction to
PunchOut
cXML
PunchOut is an easy-to-implement protocol for interactive sessions managed across
the Internet. Using real-time, synchronous cXML messages, PunchOut enables
communication between applications, providing seamless user interaction at remote
sites.
1 Introduction to
• Procurement PunchOut
cXML
• PunchOut Chaining
• Provider PunchOut
Procurement PunchOut
Suppliers that have e-commerce websites can modify them to support PunchOut.
PunchOut sites communicate with procurement systems over the Internet by using
cXML.
For more information: For PunchOut sites, procurement applications display a button instead of product or
pricing details. When users click this button, their Web browsers display pages from
Chapter 4, “PunchOut the supplier’s local website. Depending on how the supplier implements these pages,
Transaction.”
users can browse product options, specify configurations, and select delivery meth-
ods. When users are done selecting items, they click a button that returns the order
information to the procurement application. The fully configured products and their
prices appear within users’ purchase requisitions.
Suppliers’ websites can offer previously agreed-upon contract products and prices.
PunchOut Chaining
PunchOut chaining is Procurement PunchOut that involves more than one PunchOut.
cXML Path Routing enables this functionality.
cXML Path Routing allows the order and other subsequent messages to return to the
marketplaces and suppliers involved in producing the quote. Path Routing notifies all
parties about the final order, and any subsequent PunchOut specifies to the
procurement application how to split orders on behalf of the marketplace.
1 Introduction to
cXML
Provider PunchOut
1 Introduction to
Purchase Orders
cXML
Buying organizations send purchase orders to suppliers to request fulfillment of a
contract.
For more information:
Chapter 5, “Purchase
Orders.”
1 Introduction to
cXML
Purchase order communicated
1 Introduction to
to a supplier
cXML
cXML is better for communicating purchase orders than other formats (such as ANSI
X12 EDI 850), because it is flexible, inexpensive to implement, and it supports the
widest array of data and attachments.
1 Introduction to
cXML
1 Introduction to
cXML
Procurement Applications
Procurement applications, such as Ariba Buyer and Ariba Marketplace, Network
Edition, use cXML for external transactions.
Ariba Buyer is an enterprise application hosted by large organizations for use by their
employees over an intranet.
These applications allow communities of users to buy contract products and services
from vendors approved by their purchasing managers. Managers in the communities
first approve requested purchases, and approved purchase orders are transmitted to
suppliers through several possible channels, including cXML over the Internet.
Commerce network hubs can act as intermediaries that authenticate and route
requests and responses to and from diverse organizations. Communication between
these organizations can occur entirely through cXML over the Internet.
PunchOut Catalogs
As described in the previous section, PunchOut catalogs are interactive catalogs,
available at supplier websites. PunchOut catalogs are made possible by Web server
applications, written in a programming language such as ASP (Active Server Pages),
JavaScript, or CGI (Common Gateway Interface), that manage buyers’ PunchOut
sessions.
1 Introduction to
cXML
PunchOut catalogs accept PunchOut requests from procurement applications, identify
For more information:
the buying organization, and display the appropriate products and prices in HTML
Chapter 4, “PunchOut format. Users then select items, configure them, and select options if appropriate.
Transaction.”
At the end of the PunchOut session, the PunchOut site sends descriptions of the users’
selections, in cXML format, to the procurement applications.
1 Introduction to
Order-Receiving Systems
cXML
Order-receiving systems are applications at supplier sites that accept and process
purchase orders sent by buying organizations. Order-receiving systems can be any
For more information: automated system, such as inventory management systems, order-fulfillment systems,
or order-processing systems.
Chapter 5, “Purchase
Orders.”
Because it is simple to extract information from cXML purchase orders, it is
1 Introduction to
relatively easy to create the adapters that enable existing order-receiving systems to
accept them.
cXML
Content Delivery Strategy
Procurement applications present product and service content to users. Suppliers want
to control the way their customers view their products or services, because
1 Introduction to
presentation is critical to their sales process. Buying organizations want to make
content easily accessible and searchable to ensure high contract compliance.
cXML
Buying organizations and suppliers can choose from multiple methods for delivering
product and service content. The particular method to use is determined by agreement
between a buying organization and a supplier, and the nature of the products or
services traded.
1 Introduction to
cXML
1 Introduction to
cXML
The following table lists example categories of commonly procured products and
services, and their preferred content delivery methods.
Buying organizations can either store content locally within the organization, or they
can access it remotely on the Internet, through PunchOut. cXML catalogs support
both storage strategies.
As this table indicates, PunchOut offers a flexible framework upon which suppliers,
depending on their commodity or customer, can provide customized content. The
objective of this content strategy is to allow buyers and suppliers to exchange catalog
data by the method that makes the most sense.
cXML DTDs
Because cXML is an XML language, a set of Document Type Definitions (DTDs)
thoroughly define it. These DTDs are text files that describes the precise syntax and
order of cXML elements. DTDs enable applications to validate the cXML they read
or write.
The header of each cXML document contains the URL to the DTD that defines the
document. cXML applications can retrieve the DTD and use it to validate the
document.
For the most robust transaction handling, validate all cXML documents received. If
you detect errors, issue the appropriate error code so the sender can retransmit. cXML
applications are not required to validate cXML documents received, although it is
recommended. However, all cXML documents must be valid and must refer to the
cXML DTDs described in the following section.
1 Introduction to
cXML
Getting cXML DTDs
DTDs for all versions of cXML are available on cXML.org. The various kinds of
cXML documents are defined in multiple DTDs to reduce DTD size, which enables
faster validation in some parsers.
Document DTD
1 Introduction to
Basic cXML http://xml.cXML.org/schemas/cXML/<version>/cXML.dtd
documents
cXML
Confirmation http://xml.cXML.org/schemas/cXML/<version>/Fulfill.dtd
and Ship Notice
Invoice http://xml.cXML.org/schemas/cXML/<version>/InvoiceDetail.dtd
Type Definition http://xml.cXML.org/schemas/cXML/<version>/Catalog.dtd
Payment http://xml.cXML.org/schemas/cXML/<version>/PaymentRemittance.dtd
Remittance
1 Introduction to
where <version> is the full cXML version number, such as 1.2.014.
cXML
cXML applications use these DTDs to validate all incoming and outgoing documents.
Caching DTDs
For best performance, cXML applications should cache DTDs locally. After cXML
1 Introduction to
DTD files are published, they never change, so you can cache them indefinitely. (Each
new version of the DTDs has a new URL). When cXML applications parse a cXML
cXML
document, they should look at the SYSTEM identifier in the document header and
retrieve that DTD if it has not already been stored locally.
Caching DTDs locally offers the advantages of faster document validation and less
dependence on the cXML.org site.
1 Introduction to
retrieve DTDs as they receive new documents. In these environments, you must
manually retrieve the DTDs, store them locally, and instruct your applications to look
cXML
for them locally, not at cXML.org. However, generated cXML documents must point
to the DTDs at cXML.org, not the local DTDs. 1 Introduction to
cXML
Profile Transaction
The Profile transaction communicates basic information about what transactions a
particular cXML server can receive. All cXML servers must support this transaction.
It is intended for back-end integrations between applications, making the capabilities
of cXML servers available to client systems.
Note: All cXML 1.1 and higher servers must accept the Profile transaction.
ProfileRequest
The ProfileRequest document has no content. It simply routes to the specified cXML
server.
ProfileResponse
The server responds with a ProfileResponse document, which lists the cXML
transactions it supports, their locations, and any named options with a string value.
XML Utilities
Utilities for editing and validating XML files are available for free and for purchase
on the Web. The following listing describes a few of these utilities:
• Internet Explorer from Microsoft. An XML-aware Web browser that can validate
XML files against DTDs.
www.microsoft.com/windows/ie/default.htm
1 Introduction to
cXML
• Turbo XML from TIBCO Software. An Integrated Development Environment
(IDE) for creating, validating, converting and managing XML assets.
www.tibco.com/software/business_integration/turboxml.jsp
• XML Spy from Altova. A tool for maintaining DTDs and XML files with a grid,
source and browser view.
1 Introduction to
www.altova.com
cXML
• XMLwriter from Wattle Software. A graphical XML authoring tool designed to
manage XML projects.
www.xmlwriter.net
1 Introduction to
www.xml.com
cXML
1 Introduction to
cXML
1 Introduction to
cXML
1 Introduction to
cXML
2 cXML Basics
This chapter describes the basic protocol and data formats of cXML. It contains
information needed to implement all transactions.
• Protocol Specification
2 cXML Basics
• Basic Elements
Protocol Specification
There are two communication models for cXML transactions: Request-Response and
One-Way. Because these two models strictly specify the operations, they enable
2 cXML Basics
simple implementation. Both models are required, because there are situations when
one model would not be appropriate.
Request-Response Model
Request-Response transactions can be performed only over an HTTP or HTTPS
connection. The following figure illustrates the steps in a Request-Response
interaction between parties A and B:
2 cXML Basics
A B
Request
One HTTP B Performs
POST/Response Request A Request-Response
Response
Transaction
2 cXML Basics
2. Site A uses a POST operation to send the cXML document through the
HTTP connection. Site A then waits for a response.
4. Site B’s resource identified in step 3 reads the cXML document contents and
maps the Request to the appropriate handler for that request.
5. Site B’s handler for the cXML Request performs the work that the Request
specifies and generates a cXML Response document.
6. Site B sends the cXML Response to Site A through the HTTP connection
established in step 1.
7. Site A reads the cXML Response and returns it to the process that initiated
the Request.
To simplify the work in the above steps, cXML documents are divided into two
distinct parts:
Both of these elements are carried in a parent envelope element. The following
example shows the structure of a cXML Request document:
<cXML>
<Header>
Header information
</Header>
<Request>
Request information
</Request>
</cXML>
2 cXML Basics
The following example shows the structure of a cXML Response document:
<cXML>
<Response>
Response information
</Response>
</cXML>
2 cXML Basics
The Response structure does not use a Header element. It is not necessary, because the
Response always travels in the same HTTP connection as the Request.
cXML Conventions
cXML uses elements to describe discrete items, which are properties in traditional
business documents. Elements also describe information with obvious subdivisions
and relationships between those subdivisions, such as an addresses, which are
2 cXML Basics
composed of street, city, and country.
Element and attribute names are case-sensitive and use whole words with capitals (not
hyphens) separating the words. Element names begin with an uppercase letter;
attribute names begin with a lowercase letter, for example:
2 cXML Basics
Attributes: payloadID, lineNumber, domain
If optional elements have no content (they are null), leave them out entirely. Avoid
empty or whitespace elements, because missing values can affect some parsers.
In DTD files and in this document, symbols are used to indicate how many times an
element can occur in a transaction. A ‘+’ means the element can occur one or more
times, a ‘?’ means the element can occur 0 or once, and a ‘*’ means the element can
occur 0 or more times.
2 cXML Basics
cXML Document
The cXML element is the body of a cXML document. A document might begin as
follows:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
2 cXML Basics
<cXML xml:lang="en-US"
payloadID=”[email protected]"
timestamp="2002-01-09T01:36:05-08:00">
The first characters in cXML documents must be <? or <!. Documents must not start
with white space or tabs. For example, the HTML form that contains a
PunchOutOrderMessage document must not insert any character between the opening
quote and the left angle bracket.
The second line in cXML documents must contain the DOCTYPE document type
declaration. This is the only external entity that can appear in cXML documents. This
line references the cXML DTD. See “cXML DTDs” on page 24 for more information
about cXML DTDs.
cXML documents can have any one of the following top-level elements: cXML,
Supplier, Contract,
and Index. The cXML element is for “transactional” data. The other
elements describe static content.
Wrapping Layers
cXML documents are usually transmitted through HTTP with the HTTP header
specifying a MIME (Multipurpose Internet Mail Extensions) media type of text/xml
and a charset parameter matching the encoding in the cXML document.
Because HTTP is eight-bit clean, any character encoding supported by the receiving
parser can be used without a content-transfer encoding such as base64 or quoted-
printable. All XML parsers support the UTF-8 (Universal Transformation Format)
encoding, which includes all Unicode characters, including all of US-ASCII.
Therefore, applications should use UTF-8 when transmitting cXML documents.
Note: According to IETF RFC 2376 “XML Media Types,” the MIME
charset parameter overrides any encoding specified in the XML declaration.
Further, the default encoding for the text/xml media type is us-ascii, not UTF-8
as mentioned in Section 4.3.3 of the XML Specification. For clarity, cXML
documents should include an explicit encoding in the XML declaration.
MIME envelopes should use a matching charset parameter for the text/xml.
You can also use the application/xml media type, which does not override
the XML declaration or affect the recipient's decoding notes, and which does
not require the charset parameter.
An HTTP transmission of a cXML document might include the following MIME and
HTTP headers:
POST /cXML HTTP/1.0
Content-type: text/xml; charset="UTF-8"
Content-length: 1862
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
User-Agent: Java1.1
Host: localhost:8080
2 cXML Basics
Connection: Keep-Alive
Attachments
2 cXML Basics
The cXML protocol supports the attachment of external files of any type to cXML
documents. For example, buyers sometimes need to clarify purchase orders with
supporting memos, drawings, or faxes. Another example is the CatalogUploadRequest
document, which includes catalog files as attachments.
Files referenced by cXML documents can reside either on a server accessible by the
receiver or within an envelope that also includes the cXML documents themselves. To
attach external files to a cXML document in a single envelope, use Multipurpose
Internet Mail Extensions (MIME). The cXML document contains references to
2 cXML Basics
external parts sent within a multipart MIME envelope.
Including Attachments
A cXML requirement for this envelope (over the requirements described in IETF
RFC 2046 “Multipurpose Internet Mail Extensions Part Two: Media Types”) is the
inclusion of Content-ID headers with each attached file.
2 cXML Basics
The contained URL must begin with cid:, which is the identifier for the referenced
attachment within the larger transmission. The cid: identifier must match the Content-
ID header of one (and only one) part of the MIME transmission containing the
document being forwarded.
The following example shows the required skeleton of a cXML document with an
attached JPEG image (without the HTTP headers shown above):
POST /cXML HTTP/1.0
2 cXML Basics
Content-type: multipart/mixed; boundary=something unique
--something unique
Content-type: text/xml; charset="UTF-8"
…
--something unique
Content-type: image/jpeg
Content-ID: <[email protected]>
…
--something unique--
This skeleton is also all that a receiving MIME parser must be able to process.
Applications that make use of the media type described in RFC 2387 “The MIME
Multipart/Related Content-type” will get much more information if the skeleton is
enhanced:
POST /cXML HTTP/1.0
Content-type: multipart/related; boundary=something unique;
type="text/xml"; start=<[email protected]>
--something unique
Content-type: text/xml; charset="UTF-8"
Content-ID: <[email protected]>
Receiving MIME parsers that do not understand the multipart/related media type must
treat the two examples above identically. Each part of the MIME transmission can
additionally have a Content-transfer-encoding and use that encoding. This addition is
not necessary for HTTP transmission. Content-description and Content-disposition
headers are optional within the cXML protocol, although they provide useful
documentation.
Attachment Examples
2 cXML Basics
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML timestamp="2000-12-28T16:56:03-08:00" payloadID="[email protected]">
<Header>
<From>
<Credential domain="DUNS">
<Identity>123456789</Identity>
</Credential>
</From>
2 cXML Basics
<To>
<Credential domain="NetworkID">
<Identity>AN01000000001</Identity>
</Credential>
</To>
<Sender>
<Credential domain="DUNS">
<Identity>123456789</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
2 cXML Basics
</Sender>
</Header>
<Request>
<CatalogUploadRequest operation="new">
<CatalogName xml:lang="en">Winter Prices</CatalogName>
<Description xml:lang="en">premiere-level prices</Description>
<Attachment>
ID of MIME attachment <URL>cid:[email protected]</URL>
</Attachment>
</CatalogUploadRequest>
2 cXML Basics
</Request>
</cXML>
--kdflkajfdksadjfk
Second MIME body Content-type: text/plain; charset=US-ASCII
part header Content-Disposition: attachment; filename=PremiereCatalog.cif
Content-ID: <[email protected]>
Content-length: 364
CIF_I_V3.0
LOADMODE: F
2 cXML Basics
CODEFORMAT: UNSPSC
CURRENCY: USD
SUPPLIERID_DOMAIN: DUNS
ITEMCOUNT: 3
TIMESTAMP: 2001-01-15 15:25:04
DATA
942888710,34A11,C11,"Eames Chair",11116767,400.00,EA,3,"Fast MFG",,,400.00
942888710,56A12,C12,"Eames Ottoman",11116767,100.00,EA,3,"Fast MFG",,,100.00
942888710,78A13,C13,"Folding Chair",11116767,25.95,EA,3,"Fast MFG",,,25.95
ENDOFDATA
2 cXML Basics
Surround IDs in Content-ID or Content-Type headers with angle brackets (< >), but omit
these brackets when referring to IDs in URL elements. Similarly, prepend message IDs
with cid: in URL elements, but not in MIME headers.
Special characters in cid URLs must be hex encoded (in %hh format).
Use the Attachment element when attaching text files, PDFs, images, or other such
documents to a cXML document. When attaching another cXML document, use
cXMLAttachment, regardless of whether that cXML document contains attachments
itself. The cXMLAttachment element serves to alert the receiving system that additional
cXML processing might be required to handle the attachment.
--outer-boundary
Content-Type: text/xml; charset=UTF-8
Content-ID: <[email protected]>
[Other headers]
2 cXML Basics
</Sender>
</Header>
<Request deploymentMode="production">
<CopyRequest>
<cXMLAttachment>
<Attachment>
<URL>cid:[email protected]</URL>
</Attachment>
2 cXML Basics
</cXMLAttachment>
</CopyRequest>
</Request>
</cXML>
--outer-boundary
Content-Type: Multipart/Related; boundary=inner-boundary
Content-ID: <[email protected]>
[Other headers]
2 cXML Basics
--inner-boundary
Content-Type: text/xml; charset=UTF-8
Content-ID: <[email protected]>
[Other headers]
[Forwarded cXML]
--inner-boundary
[Attachment 1 of the forwarded cXML]
2 cXML Basics
--inner-boundary
[Attachment 2 of the forwarded cXML]
--inner-boundary--
--outer-boundary--
For more information about the MIME standard, see the following websites:
2 cXML Basics
www.hunnysoft.com/mime
www.ietf.org/rfc/rfc1341.txt
www.ietf.org/rfc/rfc2046.txt
www.ietf.org/rfc/rfc2387.txt
For more information about attaching external files to purchase orders, see
“Attachment” on page 124.
2 cXML Basics
cXML Envelope
The cXML element is the root of cXML documents, and it contains all other elements.
The cXML element is present in every cXML transaction. The following example
shows a fully specified cXML element:
<cXML xml:lang="en-US"
[email protected]
timestamp="1999-03-31T18:39:09-08:00">
The xml:lang attribute also appears with most free text elements (such as Description and
Comments). While the XML specification allows the locale for an element to default to
that specified for any parent element, such defaults result in inefficient queries of the
2 cXML Basics
document tree. cXML attempts to keep the locale identifiers together with the
affected strings. The most descriptive and specific locale known should be specified
in this attribute.
The xml:lang attributes appearing throughout the cXML protocol have no effect on
formatted data such as numbers, dates, and times. As described for the timestamp
attribute in the following section, for the timestamp attribute, such discrete values are
2 cXML Basics
formatted according to their data types. Longer strings (and referenced Web pages)
not intended for machine processing might contain a locale-specific numeric or date
format that matches a nearby xml:lang attribute.
The timestamp attribute, and all other dates and times in cXML, must be formatted in
the restricted subset of ISO 8601. This is described in the Word Wide Web
Consortium (W3C) Note entitled “Date and Time Formats” available at
2 cXML Basics
www.w3.org/TR/NOTE-datetime-970915.html.
Timestamps require a minimum of a complete date plus hours, minutes, and seconds.
Fractions of a second are optional. This protocol requires times expressed in local
time with a time-zone offset from UTC (Coordinated Universal Time, also known as
Greenwich Mean Time). The “Z” time zone designator is not allowed.
For example, 2002-04-14T13:36:00-08:00 corresponds to April 14, 2002, 1:36 p.m., U.S.
Pacific Standard Time.
2 cXML Basics
Further references for the date, time, and other data type formats used by cXML are:
2 cXML Basics
Special Characters
In cXML, as in XML, not all characters can be typed from the keyboard, such as the
registered trademark symbol (®). Others, such as < and &, have special meaning to
XML. These characters must be encoded using character entities.
2 cXML Basics
Entity Character
< <
> >
& &
" “
' ‘
For characters outside of the encoding you use, use the Unicode number of the
character (decimal or hexadecimal), preceded by pound (#). For example, ® and
® represent a registered trademark symbol, ®.
For example,
<Description xml:lang="en-US">The best prices for software®</Description>
could be encoded as
<Description xml:lang="en-US">The best prices for software ®</Description>
Single (')or double (")quotation marks must be escaped only within attribute values
that are quoted using that delimiter. It is recommended that you use only single quotes
to delimit attributes, unless the content will never contain quotes.
• Otherwise, fill the values in the document using UTF-8 encoding. UTF-8
should be used for all documents sent by HTTP Post directly, or embedded
in a cXML-base64 hidden field. UTF-8 includes all of US-ASCII.
3. XML escape attribute values and element content as you create the cXML
document. Characters that must be escaped are &, ', < and >.
2 cXML Basics
The following steps are required if you are transmitting the document in a
PunchOutOrderMessage.
2 cXML Basics
b. Further (for the cxml-urlencoded field), escape all ampersands that
appear in contexts significant to HTML with &. To be safe, you can
escape all ampersands. For example, escape & as &amp; and
' as &apos;. Escape the trademark symbol ® as &#174;.
5. Embed the document in the HTML form with double quotes around the
2 cXML Basics
string value. For example, to send a Money element with an attribute having
the value ®®'"""&<>> and containing the value ®®''"""&<>>", the XML document
might appear as:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>
<Money alternateAmount='®®'"""&<>>'>
®®''"""&<>></Money>
2 cXML Basics
which should be encoded as follows:
<!-- Recommendation for cXML-urlencoding: Uses double quotes to delimit the -->
<!-- field value and single quotes for the contained attributes. -->
<Input type="Hidden" name="cXML-urlencoded" value="<?xml version='1.0'
encoding='UTF-8'?>
<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>
<Money alternateAmount='&#174;&#xAE;&apos;"&#34;
&quot;&amp;&lt;>&gt;'>&#174;&#xAE;'&apos;
"&#34;&quot;&amp;&lt;>&gt;</Money>">
2 cXML Basics
<!-- Best choice: Base64 encode the value. Don't have to worry about what -->
<!-- the browser interprets. -->
<Input type="Hidden" name="cXML-
base64"value="PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4K
PCFET0NUWVBFIE1vbmV5IFNZU1RFTSAnU3BlY2lhbENoYXJzLmR0ZCc+CjxNb
25leSBhbHRlcm5hdGVBbW91bnQ9JyYjMTc0OyYjeEFFOyZhcG9zOyImIzM0OyZxd
W90OyZhbXA7Jmx0Oz4mZ3Q7Jz4KJiMxNzQ7JiN4QUU7JyZhcG9zOyImIzM0OyZx
dW90OyZhbXA7Jmx0Oz4mZ3Q7PC9Nb25leT4K">
2 cXML Basics
Header
The Header element contains addressing and authentication information. The Header
element is the same regardless of the specific Request or Response within the body of
the cXML message. Applications need the requestor's identity, but not validation that
the information provided for identity is correct.
2 cXML Basics
The From and To elements are synonymous with From and To in SMTP mail messages;
they are the logical source and destination of the messages. Sender is the party that
opens the HTTP connection and sends the cXML document.
Sender contains the Credential element, which allows the receiving party to authenticate
the sending party. This credential allows strong authentication without requiring a
public-key end-to-end digital certificate infrastructure. Only a user name and
2 cXML Basics
password need to be issued by the receiving party to allow the sending party to
perform Requests.
When the document is initially sent, Sender and From are the same, However, if the
cXML document travels through e-commerce network hubs, the Sender element
changes to indicate current sending party.
From
2 cXML Basics
This element identifies the originator of the cXML request.
To
Sender
2 cXML Basics
This element allows the receiving party to identify and authenticate the party that
opened the HTTP connection. It contains a stronger authentication Credential than the
ones in the From or To elements, because the receiving party must authenticate who is
asking it to perform work.
UserAgent
A textual string representing the UserAgent who is conducting the cXML conversation.
2 cXML Basics
This should be a unique per-product string, and ideally, per-version. Analogous to
UserAgent for HTTP conversations.
Credential
SharedSecret
The SharedSecret element is used when the Sender has a password that the requester
recognizes.
CredentialMac
The CredentialMac element is used for the Message Authentication Code (MAC)
authentication method. This authentication method is used in situations where the
sender must prove to the receiver that it has been authenticated by shared secret by a
trusted third party. For example, a direct PunchOut request can travel directly from a
buyer to a supplier without going through a network commerce hub, because it
contains a MAC (generated by the network commerce hub) that allows the supplier to
authenticate it.
The trusted third party computes the MAC and transfers it to the sender through the
Profile transaction. The MAC is opaque to the sender (it is secure and non-reversible).
To see how the MAC is transmitted from the trusted third party to the sender, see
“ProfileResponse” on page 60.
The receiver computes the MAC using the same inputs as the trusted third party and
compares it with the MAC received in the cXML document. If the two values match,
the document is authentic.
2 cXML Basics
To learn how to compute the MAC value, see “Message Authentication Code (MAC)”
on page 323.
2 cXML Basics
Identifies for the MAC algorithm used on the data. The only
algorithm
supported value is “HMAC-SHA1-96”.
creationDate Specifies the date and time the MAC was generated.
Specifies the date and time after which this MAC is no longer
valid. Receivers must reject MACs that are received after the
expirationDate expirationDate. Receivers can optionally reject unexpired
MACs. For example, a receiver might reject MACs that are
scheduled to expire in less than an hour.
2 cXML Basics
The following example shows a Credential element that contains a CredentialMac
element:
<Sender>
<Credential domain=”NetworkId”>
<Identity>AN9900000100</Identity>
<CredentialMac type=”FromSenderCredentials”
algorithm=”HMAC-SHA1-96”
creationDate=”2003-01-15T08:42:46-0800”
2 cXML Basics
expirationDate=”2003-01-15T11:42:46-0800”>
MnXkusp8Jj0lw3mf
</CredentialMac>
<UserAgent>Procurement Application 8.1</UserAgent>
</Credential>
</Sender>
Multiple Credentials
2 cXML Basics
The From, To, and Sender elements can each optionally contain multiple Credential
elements. The purpose of supplying multiple credentials is to identify a single
organization using different domains. For example, an organization might be
identified by including both a DUNS number and a NetworkId number.
The receiver should validate all credentials with domains it recognizes and it should
reject the document if any credentials with recognized domains do not match an
organization it knows. It should also reject the document if any two credentials in the
same From, To, or Sender section appear to refer to different entities.
2 cXML Basics
The receiver should reject the document if there are multiple credentials in a To, From,
or Sender section that use different values but use the same domain.
Request
Clients send requests for operations. Only one Request element is allowed for each
cXML envelope element, which simplifies the server implementations, because no de-
multiplexing needs to occur when reading cXML documents. The Request element
can contain virtually any type of XML data.
Response
Servers send responses to inform clients of the results of operations. Because the
result of some requests might not have any data, the Response element can optionally
contain nothing but a Status element. A Response element can also contain any
application-level data. During PunchOut for example, the application-level data is
contained in a PunchOutSetupResponse element.
2 cXML Basics
Response has the following attribute:
This attribute can be used to call out an element and all its
children as a target for a digital signing. For more information
Id
about digital signatures, see Chapter 16, “cXML Digital
Signatures.”
2 cXML Basics
Status
This element conveys the success, transient failure, or permanent failure of a request
operation.
2 cXML Basics
The text of the status. This text aids user readability in logs, and
text
is a canonical string for the error in English.
The language of the data in the Status element. Optional for
xml:lang
compatibility with cXML 1.0. Might be required in future
(optional)
versions of cXML.
The attributes of the Status element indicate what happened to the request. For
example:
2 cXML Basics
<Status xml:lang="en-US" code="200” text="OK"> </Status>
The content of the Status element can be any data needed by the requestor and should
describe the error. For a cXML 200/OK status code, there might be no data. However,
for a cXML 500/Internal Server Error status code, or other similar code, it is strongly
recommended that the actual XML parse error or application error be presented. This
error allows better one-sided debugging and interoperability testing. For example:
<Status code="406" text="Not Acceptable">cXML did not validate. Big Problem!</Status>
2 cXML Basics
The following table describes the cXML status code ranges:
Range Meaning
2xx Success
4xx Permanent error. Client should not retry. The error prevents the request
from being accepted.
5xx Transient error. Typically a transport error. Client should retry. The
recommended number of retries is 10, with a frequency of one hour. At a
2 cXML Basics
Because cXML is layered above HTTP in most cases, many errors (such as HTTP
404/Not Found) are handled by the transport. All transport errors should be treated as
transient and the client should retry, as if a cXML 500 range status code had been
received. All HTTP replies that don’t include valid cXML content, including HTTP
404/Not found and HTTP 500/Internal Server Error status codes, are considered
transport errors. Other common transport problems include timeouts, TCP errors
(such as “connection refused”), and DNS errors (such as “host unknown”). Validation
errors in parsing a Request document would normally result in a cXML permanent
error in the 400 range, preferably 406/Not Acceptable.
2 cXML Basics
Status Text Meaning
400 Bad Request Request unacceptable to the server, although it parsed
correctly.
401 Unauthorized Credentials provided in the Request (the Sender element)
were not recognized by the server.
402 Payment This Request must include a complete Payment element.
Required
2 cXML Basics
403 Forbidden The user has insufficient privileges to execute this
Request.
406 Not Acceptable Request unacceptable to the server, likely due to a
parsing failure.
409 Conflict The current state of the server or its internal data
prevented the (update) operation request. An identical
Request is unlikely to succeed in the future, but only after
another operation has executed, if at all.
412 Precondition A precondition of the Request (for example, a PunchOut
2 cXML Basics
Failed session appropriate for a PunchOutSetupRequest edit)
was not met. This status normally implies the client
ignored some portion of a previous transmission from a
server (for example, the operationAllowed attribute of a
PunchOutOrderMessageHeader).
417 Expectation Request implied a resource condition that was not met.
Failed One example might be a SupplierDataRequest asking for
information about a supplier unknown to the server. This
status might imply lost information at the client or server.
450 Not The server does not implement the particular Request.
2 cXML Basics
Implemented For example, PunchOutSetupRequest or the requested
operation might not be supported. This status normally
implies the client has ignored the server’s profile.
475 Signature The receiver is unwilling to accept the document
Required because it does not have a digital signature.
476 Signature The receiver is unable to validate the signature, possibly
Verification because the document was altered in transit, or the
Failed receiver does not support one or more algorithms used
in the signature.
2 cXML Basics
477 Signature The signature is technically valid, but is not acceptable
Unacceptable to the receiver for some other reason. The signature
policies or certificate policies may be unacceptable, the
type of certificate used may be unacceptable, or there
may be some other problem.
2 cXML Basics
For status codes related to catalog uploading, see “Response” on page 299.
When receiving unrecognized codes, cXML clients must handle them according to
their class. Therefore, older clients should treat all new 2xx codes as 200 (success),
4xx codes as 400 (permanent failure), and 5xx codes as 500 (transient error). This
behavior allows for both further expansions of the cXML protocol and server-specific
codes without loss of interoperability.
A B
One-Way Message
Message (Asynchronous)
2. A sends the document using the known transport. A does not (and cannot)
actively wait for a response to come back from B.
2 cXML Basics
3. B receives the cXML document and decodes it out of the transport stream.
In the One-Way model, A and B do not have an explicit Request-Response cycle. For
example, between One-Way messages, messages from other parties might arrive and
other conversations could take place.
2 cXML Basics
To fully specify a one-way transaction, the transport used for the message must also
be documented. For the cXML transactions that use the one-way approach, the
transport and encoding are specified. A common example of a transaction that uses
one-way is the PunchOutOrderMessage.
2 cXML Basics
<Header>
Header information here…
</Header>
<Message>
Message information here…
</Message>
</cXML>
The Header element is treated exactly as it is in the Request-Response case. The cXML
element is also identical to the one described on page 38. The easiest way to tell the
2 cXML Basics
difference between a one-way message and a Request-Response message is the
presence of a Message element (instead of a Request or Response element). The
following section discusses the Message element in more detail.
The Header element in a one-way message should not contain shared secret
information in the sender credential. Authentication is done using the BuyerCookie.
This is different from Request-Response Header.
2 cXML Basics
Message
This element carries all the body level information in a cXML message. It can contain
an optional Status element, identical to that found in a Response element—it would be
used in messages that are logical responses to request messages.
2 cXML Basics
The inReplyTo attribute can also reference the payloadID of an earlier Request or Response
document. When a Request-Response transaction initiates a “conversation” through
multiple one-way interactions, the first message can include the payloadID of the most
recent relevant Request or Response that went in the other direction. For example, a
Message containing a PunchOutOrderMessage might include an inReplyTo attribute
containing the payloadID of the PunchOutSetupRequest that started the PunchOut session.
The BuyerCookie included in the PunchOut documents performs a similar function to
that of the inReplyTo attribute.
Transport Options
There are two commonly used transports for one-way messages: HTTP and URL-
Form-Encoding. These are just two of the well-defined transports today; more could
become supported in the future.
HTTP
URL-Form-Encoding
2 cXML Basics
Remote websites do not directly send cXML PunchOutOrderMessage documents to
procurement applications; instead, they encode them as hidden HTML Form fields
and post them to the URL specified in the BrowserFormPost element of the
PunchOutSetupRequest. When the user clicks a Check Out button on the website after
shopping, the website sends the data to the procurement application as an HTML
Form Submit. The following diagram illustrates what happens:
2 cXML Basics
1 Remote
Web Internet Website
Browser
2 cXML Basics
User clicks Submit
button, Form is cXML message
sent to URL
specified by Originating 3
Originating System
System
Form is decoded,
cXML message
extracted and
passed to
2 cXML Basics
Originating System
as a new cXML
Request
Form Packing
2 cXML Basics
Remote websites assign each PunchOutOrderMessage document to a hidden field on the
Form named cXML-urlencoded or cXML-base64. They assign the HTML Form element a
METHOD of POST and an ACTION consisting of the URL passed in the
BrowserFormPost element of the PunchOutSetupRequest. For example:
<FORM METHOD=POST
ACTION="http://workchairs.com:1616/punchoutexit">
<INPUT TYPE=HIDDEN NAME="cXML-urlencoded"
VALUE="Entire URL-Encoded PunchOutOrderMessage document">
<INPUT TYPE=SUBMIT VALUE="Proceed">
2 cXML Basics
</FORM>
Additional HTML tags on the page might contain the above fragment to describe the
contents of the shopping basket in detail.
Note: When Web servers send the cXML-urlencoded field, it is not yet URL
encoded. This encoding is required only when the form is submitted by Web
browsers (when users click Check Out in the above example). Web browsers
themselves meet this requirement. The Web server must HTML-encode only
the field value, escaping quotation marks and other special characters, so the
form displays properly for the user.
cXML-urlencoded
The cXML-urlencoded field is URL encoded (per the HTTP specification) by the Web
browser, not by the Web server or the supplier. This is because the encoding is
required only when the form is submitted by a Web browser, such as when a user
clicks Check Out in the previous example. However, the Web server must HTML-
encode the field value, escaping quotation marks and other special characters, so that
the form will display correctly.
For cXML-urlencoded data, the receiving parser cannot assume a charset parameter
beyond the default for media type text/xml. No character encoding information for the
posted data is carried in an HTTP POST. The receiving Web server cannot determine
the encoding of the HTML page containing the hidden field. The cXML document
forwarded in this fashion must therefore use us-ascii character encoding. Any
characters (including those “URI encoded” as “%XX”) found in the XML source
document must be in the “us-ascii” set. Other Unicode symbols can be encoded using
character entities in that source document.
cXML-Base64
2 cXML Basics
Base64-encoding from the remote website through the browser and to the receiving
Web server at the client maintains the original character encoding of a cXML
document. Though no charset parameter arrives with the posted information, the
decoded document (after the transfer encoding is removed) can be treated as the
media type application/xml. This encoding allows the receiving parser to honor any
encoding attribute specified in the XML declaration. For this field (as for any application/
xml documents), the default character encoding is UTF-8.
2 cXML Basics
Either of these hidden fields (cXML-urlencoded or cXML-base64) must appear in the data
posted to the procurement application. Though recipients should first look for
cXML-base64 in the data, it is wasteful to send both fields.
2 cXML Basics
Form POST processor would first look for the cXML-base64 variable, extract the value
and base64-decode its contents. If that field does not exist in the data, the Form POST
processor would look for the cXML-urlencoded variable, extract the URL-encoded
cXML message and URL-decode it. The decoded content of the field is then
processed as if it had been received through a normal HTTP Request/Response cycle.
The implied media type of the document after decoding varies, with different possible
character encodings:
2 cXML Basics
• The cXML-urlencoded variable is of media type text/xml with no charset attribute. It is
thus restricted to the us-ascii character encoding. The receiving parser must ignore
any encoding attribute in the XML declaration of the cXML document because the
browser might have changed the encoding.
• The cXML-base64 variable is of media type application/xml and thus might have any
character encoding (indicated by the encoding attribute of the contained XML
declaration, if any). The default character encoding is UTF-8, as for any application/xml
documents.
2 cXML Basics
The primary difference between this transaction and a normal Request-Response
transaction is that there is no response that can be generated, because there is no
HTTP connection through which to send it.
dynamically generated cXML Response document. A service can be any HTTP URL
at which cXML Request documents are received.
Basic Elements
The following entities and elements are used throughout the cXML specification.
Most of the definitions listed here are basic vocabulary with which the higher-order
business documents are described. The common type entities and the common
elements representing low-level objects are defined here.
Type Entities
Most of these definitions are from the XML-Data note submission to the World Wide
Web Consortium (W3C). A few higher-level type entities that are also defined here
are not from XML-Data. These types are also discussed in “cXML Envelope” on page
38.
isoLangCode
isoCountryCode
xmlLangCode
2 cXML Basics
Unlike the full XML recommendation, IANA or private language codes should not be
used in cXML. IANA and private subcodes are allowed, though they should come
after a valid ISO 3166 Country Code.
2 cXML Basics
always recommended. By convention, the language code is lowercase and the country
code is uppercase. This is not required for correct matching of the codes.
UnitOfMeasure
UnitOfMeasure describes
how the product is packaged or shipped. It must conform to
UN/CEFACT Unit of Measure Common Codes. For a list of UN/CEFACT codes, see
www.unetrades.net.
2 cXML Basics
URL
Base Elements
These elements, used throughout the specification, range from generic ones such as
Name and Extrinsic to specific ones such as Money. For information about the base
2 cXML Basics
TermReference element, see page 152.
Money
2 cXML Basics
<Money currency="USD">12.34</Money>
The optional alternateCurrency and alternateAmount attributes are used together to specify
an amount in an alternate currency. These can be used to support dual-currency
requirements such as the euro. For example:
<Money currency="USD" alternateCurrency=”EUR” alternateAmount=”14.28”>12.34
</Money>
2 cXML Basics
Note: You can optionally use commas as thousands separators. Do not use
commas as decimal separators.
Country
CountryCode
Contains the International ITU dial code for the country code. It can be entered onto a
telephone keypad after the escape code to reach the country. Used by the Phone and
Fax elements.
Contact
The Contact element contains information about any contact important to the current
transaction. For example:
<Contact>
<Name xml:lang="en-US">Mr. Smart E. Pants</Name>
<Email>[email protected]</Email>
<Phone name="Office">
…
</Phone>
</Contact>
3 Profile Transaction
The Profile transaction retrieves cXML server capabilities, including the supported
cXML version, transactions, and options on those transactions. The ProfileRequest and
ProfileResponse documents must be supported by all cXML 1.1 and higher server
implementations.
3 Profile Transaction
This chapter describes:
3 Profile Transaction
Introduction to the Profile Transaction
The Profile transaction enables one party to query another for cXML capabilities.
These parties include suppliers, buyers, commerce network hubs, service providers,
and marketplaces. To inquire about server capabilities, send a ProfileRequest document.
The server returns a ProfileResponse document containing the server information.
3 Profile Transaction
The Profile transaction is the only transaction that all cXML servers must support. It
is intended for back-end integration between applications, making the capabilities of
cXML servers available to client systems.
The ProfileResponse should list all Requests supported at a particular website, not
necessarily all those supported by the organization. Suppliers that can receive
OrderRequest documents and send various messages or initiate Request/Response
transactions describe their OrderRequest support in the profile transaction. The data
returned by a ProfileRequest can be cached and used for a period of time, as determined
3 Profile Transaction
The Profile transaction can also be used to simply “ping” a server within the cXML
protocol.
The Profile transaction can also retrieve the locations for follow-up documents. This
use replaces the Followup element used in OrderRequest documents. To obtain
information about where to send any document, send a ProfileRequest document to the
server.
ProfileRequest
This element has no content. It is simply routed to the appropriate cXML server using
the Header. The server responds with a single ProfileResponse as described below. The
only dynamic portions of this response are the payloadId and timestamp attributes of the
cXML element itself. In this particular case, servers are not required to provide
responses in multiple locales.
ProfileResponse
This element contains a list of supported transactions, their locations, and any
supported options. The following is a possible ProfileResponse:
<ProfileResponse effectiveDate="2001-03-03T12:13:14-05:00">
<Option name="Locale">1</Option>
…
<Transaction requestName="PunchOutSetupRequest">
3 Profile Transaction
<URL>http://www.workchairs.com/cXML/PunchOut.asp</URL>
<Option name="operationAllowed">create inspect</Option>
<Option name="dynamic pricing">0</Option>
…
</Transaction>
…
</ProfileResponse>
3 Profile Transaction
A more likely ProfileResponse from a current supplier might be:
<ProfileResponse effectiveDate="2000-01-01T05:24:29-08:00"
lastRefresh="2001-09-08T05:24:29-08:00">
<Transaction requestName="OrderRequest">
<URL>http://workchairs.com/cgi/orders.cgi</URL>
<Option name=”service”>workchairs.orders</Option>
</Transaction>
<Transaction requestName="PunchOutSetupRequest">
3 Profile Transaction
<URL>http://workchairs.com/cgi/PunchOut.cgi</URL>
<Option name=”service”>workchairs.signin</Option>
</Transaction>
</ProfileResponse>
3 Profile Transaction
Indicates when the profile cache was last refreshed. When an
lastRefresh application receives a ProfileResponse from a profile caching
server, it will know the age of the data in the cache.
Option Element
The Option element contains the value for a defined option for either the overall
service or a specific transaction. Option has the following attribute:
3 Profile Transaction
The name of this option. This attribute should not be viewed
directly (because the profile is intended for machine
consumption). The client system must understand this before
name receiving a ProfileResponse document.
Currently defined values for name are service, attachments,
changes, and requestNames.
3 Profile Transaction
MAC Options
For example:
<ProfileResponse>
<Option name="CredentialMac.type">FromSenderCredentials</Option>
<Option name="CredentialMac.algorithm">HMAC-SHA1-96</Option>
<Option name="CredentialMac.creationDate">2003-01-17T17:39:09-08:00</Option>
<Option name="CredentialMac.expirationDate">2003-01-17T23:39:09-08:00</Option>
<Option name="CredentialMac.value">67mURtR6VI6YnIsK</Option>
If the server supports direct PunchOut, additional Option elements should appear for
PunchOutSetupRequest in the ProfileResponse. For more information, see
“PunchOutSetupRequest Options” on page 63.
For more information about MACs, see “Message Authentication Code (MAC)” on
page 323.
Service
The Profile transaction can return multiple variations of a single transaction type.
<Transaction requestName=”ProviderSetupRequest”>
<URL>http://service.hub.com/console</URL>
<Option name="service">console</Option>
3 Profile Transaction
</Transaction>
If there is only one location for a particular type of transaction, then the Option element
is not needed.
When looking for a particular transaction type and Option name=”service” is provided,
3 Profile Transaction
use the transaction that matches the desired service. If there is no such Option name
and option value match, use the first transaction with no option name and value.
Each variation of a transaction must uniquely identify its particular location. In the
case of ProviderSetupRequest, the unique identifier is “service”. These unique identifiers
use the Option element in the Transaction element. The Option element contains the
unique identifier’s name. The value for the Option element is the unique identifier’s
value.
3 Profile Transaction
PunchOutSetupRequest Options
3 Profile Transaction
<Option name="Direct.URL">https://asp.workchairs.com/directPunchout</Option>
In addition, this option instructs the trusted third party to generate a Message
Authentication Code for the server. There are additional Option elements that should
3 Profile Transaction
appear within the ProfileResponse element for profiles sent by trusted third parties,
see “MAC Options” on page 62. For information about MAC authentication, see
“Message Authentication Code (MAC)” on page 323.
• To indicate that the server supports the digital certificate authentication method:
<Option name="Direct.AuthenticationMethod.Certificate">Yes</Option>
This option indicates that the server sends AuthRequest documents to validate
3 Profile Transaction
PunchOut requests. For information about the Auth transaction, see “Auth
Transaction” on page 328.
For more information about direct PunchOut, see “Direct PunchOut” on page 111.
OrderRequest Options
The default for both options is No. Documents with attachments or changes set to No
should be handled identically to documents that do not mention the option.
For more information about cXML document attachments, see “Wrapping Layers” on
page 32.
SessionStatusRequest Options
Transaction
The description of a transaction supported by this service. The Profile definition
currently indicates the locations to which to send specific requests. Future versions of
cXML might add more Option definitions and extend the Profile information to include
more information about supported requests.
3 Profile Transaction
Transaction has the following attribute:
3 Profile Transaction
Scenarios
ProfileRequest documents can be sent by several possible entities to obtain server
capabilities and information from suppliers, buyers, commerce network hubs, service
providers, and marketplaces. The possible combinations of these parties and the kinds
of transaction information that can be returned are described in the following
scenarios.
3 Profile Transaction
From Buyer to Supplier
A ProfileRequest document is sent from a buyer to a supplier through a commerce
network hub. The network commerce hub queries a supplier periodically, and caches
the information to use in ProfileResponse documents sent to buyers.
3 Profile Transaction
Buyer Network Supplier
Profile Response Profile Response
The supplier returns in the ProfileResponse the transactions that it supports. For
example:
• OrderRequest
• PunchOutSetupRequest
3 Profile Transaction
The ProfileResponse sent to the buyer can include capabilities offered by the network on
behalf of that supplier.
Profile Request
Buyer Network
Profile Response
The network returns in the ProfileResponse the transactions that it supports. For
example:
• SupplierDataRequest
• SubscriptionListRequest
• SubscriptionContentRequest
• GetPendingRequest
• OrderStatusSetupRequest
• SupplierListRequest
• ProviderSetupRequest
• SessionStatusSetupRequest
3 Profile Transaction
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="9949494" xml:lang="en-US"
timestamp="2002-02-04T18:39:49-08:00">
<Response>
<Status code="200" text="OK"/>
<ProfileResponse effectiveDate="2002-01-01T05:24:29-08:00">
3 Profile Transaction
<Transaction requestName="OrderStatusSetupRequest">
<URL>https://superduper.com/a/OrderStatusSetup</URL>
</Transaction>
<Transaction requestName="GetPendingRequest">
<URL>https://superduper.com/a/GetPending</URL>
</Transaction>
<Transaction requestName="SubscriptionListRequest">
<URL>https://superduper.com/b/SubscriptionList</URL>
</Transaction>
<Transaction requestName="SubscriptionContentRequest">
3 Profile Transaction
<URL>https://superduper.com/b/SubscriptionContent</URL>
</Transaction>
<Transaction requestName="SupplierListRequest">
<URL>https://superduper.com/c/SupplierList</URL>
</Transaction>
<Transaction requestName="SupplierDataRequest">
<URL>https://superduper.com/c/SupplierData</URL>
</Transaction>
<Transaction requestName="ProviderSetupRequest">
<URL>https://superduper.com/d/ProviderSetup</URL>
3 Profile Transaction
</Transaction>
<Transaction requestName="SessionStatusRequest">
<URL>https://superduper.com/d/SessionStatus</URL>
<Option name="requestNames">OrderStatusSetupRequest</Option>
</Transaction>
</ProfileResponse>
</Response>
</cXML>
3 Profile Transaction
From a Network Hub to Supplier
A ProfileRequest is sent from a network commerce hub to a supplier. The network
commerce hub queries a supplier periodically, and caches the information to use in
ProfileResponse documents sent to buying organizations about a particular supplier.
Profile Request
Network Supplier
Profile Response
3 Profile Transaction
The supplier returns in the ProfileResponse document the transactions that it supports.
For example:
• OrderRequest
• PunchOutSetupRequest
3 Profile Transaction
<Option name="changes">yes</Option>
</Transaction>
</ProfileResponse>
</Response>
</cXML>
3 Profile Transaction
From a Network Hub to Service Provider
A ProfileRequest is sent from a network commerce hub to service provider partners.
Routing service providers need to specify if one or two ProfileReponses will be
returned, because profile information can be returned for both the service provider
and downstream supplier accounts.
Profile Request
Network Provider
3 Profile Transaction
Profile Response
The service provider returns in the ProfileResponse document the transactions that it
supports. For example:
• ProviderSetupRequest
• SessionStatus
• OrderRequest
3 Profile Transaction
From a Network Hub to Buyer
A ProfileRequest is sent from a network commerce hub to a buyer. The network
commerce hub queries a buyer periodically, and caches the information. Later, this
information about the buyer is used in ProfileResponse documents sent to service
providers and suppliers.
3 Profile Transaction
Profile Request
Network Buyer
Profile Response
Buyers return in the ProfileResponse document the transactions that they support. For
example:
• StatusUpdateRequest
3 Profile Transaction
• InvoiceDetailRequest
The network commerce hub returns in the ProfileResponse document to the service
provider the transactions that it supports on behalf of a buyer. For example:
• StatusUpdateRequest
• InvoiceDetailRequest
4 PunchOut
Transaction
PunchOut enables users of procurement applications to access supplier contracts for
products or services that reside at the supplier’s website. It eliminates the need for the
suppliers to send whole catalogs to buying organizations. Instead, suppliers send just
short index files that name their storefronts, product categories, or products.
This chapter shows how suppliers can modify a website to support PunchOut. It
4 PunchOut
Transaction
describes:
• PunchOut Requirements
• PunchOut Event Sequence
• PunchOut Documents
• Modifications to the Supplier’s Web Pages
• PunchOut Website Suggestions
4 PunchOut
Transaction
• PunchOut Transaction
• Direct PunchOut
PunchOut Requirements
Before buying organizations configure their procurement applications for PunchOut,
4 PunchOut
Transaction
or suppliers implement PunchOut websites, both parties must evaluate the benefits
and requirements of PunchOut.
Buying Organizations
Setup and testing of cXML-compatible procurement applications with a PunchOut-
enabled supplier can be completed in less than one day.
4 PunchOut
Transaction
Therefore, PunchOut is a good solution for buying organizations of all sizes and
levels of technical expertise. The decision to use PunchOut should be based on the
business practices and types of commodities purchased. (See “Content Delivery
Strategy” on page 23 for a list of commodities that are well suited for PunchOut.)
Business Issues
Buying organizations should consider the following questions when deciding whether
to use static catalog content such as an Index or Contract documents, or PunchOut:
If the answer to any of the above questions is yes, PunchOut might be appropriate for
the buying organization.
Technical Issues
4 PunchOut
Transaction
Suppliers
The term supplier in the context of PunchOut encompasses more than the traditional
definition of the term. The PunchOut protocol was designed as a flexible framework
capable of transmitting data about virtually any kind of product or service from any
kind of supplier, distributor, aggregator, or manufacturer.
4 PunchOut
Transaction
• Computers direct from a manufacturer or reseller
• Chemicals and reagents from an aggregator
• Office supplies from a distributor
• Contract services from a temp agency
The supplier might already have a transactive website capable of hosting content and
4 PunchOut
Transaction
receiving purchase orders. Given this capability, the supplier needs to consider both
the supplier’s business practices and technical resources in deciding whether to
implement PunchOut.
Business Issues
• Does the supplier currently sell the supplier’s products or services through the
4 PunchOut
Transaction
Internet? If so, do they offer customer-specific content (contract pricing) through
their website?
• Does the supplier’s products and services fall into one of the PunchOut categories
as described in the chart in “Content Delivery Strategy” on page 23? To review,
these categories include:
Highly configurable products (such as computers)
Large number of line items (such as books)
4 PunchOut
Transaction
Unique product attributes (such as chemicals)
Normalized data (such as MRO Supplies)
Rapidly changing or expanding items (such as temperary services or books)
• Does the supplier prefer to receive purchase orders and/or payment through their
website?
If the answer to any of the above questions is yes, PunchOut might be appropriate for
the supplier’s organization.
4 PunchOut
Transaction
Technical Issues
Work Estimate
The following table lists estimates of work required for cXML PunchOut integration
based on estimates from suppliers:
Understanding XML
4 PunchOut
Transaction
The basic tools to process XML documents are XML parsers. These parsers are freely
available from Microsoft and other companies (for example, an XML parser is
standard in Microsoft Internet Explorer 5). For a list of XML tools, see “XML
Utilities” on page 26.
4 PunchOut
Transaction
A PunchOut session is composed of several distinct steps.
4 PunchOut
Transaction
opens a new browser window and logs them into their accounts at the supplier’s
website.
Procurement Application
Application
1. Requisitioner selects
4 PunchOut
Transaction
supplier for PunchOut.
Procurement application
makes request to
e-commerce network hub.
E-commerce Hub
PunchOut
PunchOut
Dispatcher
Dispatcher 2. E-commerce network
4 PunchOut
Transaction
hub authenticates
buying organization and
opens secure HTTP
session with supplier.
How does it work? When a user clicks a PunchOut item, the procurement application
sends a cXML PunchOutSetupRequest document to a network e-commerce hub. Acting
as the trusted third party, the hub accepts the request, verifies the buying organization,
and passes the request to the supplier’s PunchOut website.
4 PunchOut
Transaction
Note: All cXML documents sent through the Internet can travel through
SSL (Secure Socket Layer) 3.0-encrypted HTTPS connections.
The purpose of this request is to notify the supplier’s website of the buyer’s identity,
and to communicate the operation to be performed. Supported operations include the
following:
The procurement application opens a new browser window, which displays a session
logged into an account on the supplier’s website. This account can be specific to a
region, a company, a department, or a user.
Direct PunchOut is an alternative method for initiating PunchOut sessions, where the
PunchOut site, not a network commerce hub, authenticates the PunchOut request. For
more information, see “Direct PunchOut” on page 111.
3. Requisitioner uses
supplier site to find and
configure products.
Depending on the product or customer, these features might include the following:
4 PunchOut
Transaction
• Configurator tools for building customized products (for example, computers,
organic compounds, or personalized products)
• Search engines for finding desired products from large catalogs.
• Views of normalized data for comparing products based on price, features, or
availability (for example, MRO products)
• Views of attributes unique to a particular commodity (for example, printed
4 PunchOut
Transaction
materials, chemical and reagents, or services)
• Real-time pricing, inventory, and availability checking
• Automatic tax and freight calculations based on ship-to destination, size, or
quantity of items (not necessary to calculate during the PunchOut session)
How does it work? After the procurement application directs users to the supplier’s
website, the shopping experience is the same as if they had logged on to the supplier’s
website directly. Thus, none of the previously listed features and services require
4 PunchOut
Transaction
modification.
4 PunchOut
Transaction
The following figure illustrates the check-out steps:
Procurement
Procurement Application
Application
4 PunchOut
Transaction
E-commerce
E-commerce Hub
Hub
PunchOut
PunchOut
Dispatcher
Dispatcher
4. Requisitioner checks
out of your site.
4 PunchOut
Transaction
How does it work? When users click the supplier’s “Check Out” button, they submit
an HTML form back to their procurement application. One form field consists of a
cXML PunchOutOrderMessage containing product details and prices. The supplier can
also send hidden supplier cookies, which can later associate items with a specific
shopping session.
Effectively, the supplier has provided a quote for the requested items—the supplier
has not yet received a purchase order, so the supplier cannot yet book the order.
If users, including approvers, later need to edit any of the items in a purchase
requisition, the supplier can allow them to “re-PunchOut” to the supplier’s website.
The procurement application sends back the contents of the original shopping cart to
the supplier’s website, and users make any changes there. Upon check out, the
supplier’s website returns the items to the purchase requisition.
The supplier’s website is the information source for all PunchOut items. Changes to
the quantity or the addition of new items to the requisition might alter tax or shipping
charges, which would require recalculation at the supplier’s website. Thus, any
changes to the original items need to be made at the supplier’s website, not in the
procurement application, therefore the need to re-PunchOut. A re-PunchOut is simply
a PunchOutSetupRequest with “edit” as its operation.
4 PunchOut
Transaction
The following figure illustrates purchase order transmittal:
Procurement
Procurement Application
Application
4 PunchOut
Transaction
E-commerce
E-commerce Hub
Hub
Order
Order
5. When request is fully
Dispatcher
Dispatcher approved, order is sent to
supplier through
e-commerce network hub.
4 PunchOut
Transaction
How does it work? The procurement application sends all purchase orders to the
e-commerce hub in cXML format. The hub then routes them to the supplier, using the
supplier’s preferred order-routing method. When the supplier acknowledges the
receipt of a purchase order, the supplier has effectively booked the order.
For PunchOut-enabled suppliers, the best order routing method is cXML for the
4 PunchOut
following reasons:
Transaction
• cXML purchase orders allow embedded supplier cookie information to be
transmitted back to the supplier. Because the supplier cookie is of data type “any”,
it does not easily map to other order routing methods such as fax, e-mail, or EDI.
4 PunchOut
Purchase orders are discussed in detail in Chapter 5, “Purchase Orders.”
Transaction
4 PunchOut
Transaction
PunchOut Documents
There are four types of cXML documents:
All but the PunchOut Index Catalog are considered PunchOut session documents
because they are used to transmit data between a supplier’s PunchOut site and the
buyer during a PunchOut session.
SupplierID identifies
the supplier organization. The supplier can use any identification
domain, but the recommended ones are D-U-N-S (Dun & Bradstreet Universal
Naming System) and NetworkId. For more information about D-U-N-S numbers, see
www.dnb.com.
4 PunchOut
Transaction
Description specifies the text that the procurement application displays in product
catalogs. The supplier can provide the description in multiple languages, and the
procurement application displays the appropriate one for the user’s locale.
Classification specifies the commodity grouping of the line item to the buyer. All the
supplier’s products and services must be mapped and standardized to the UNSPSC
schema. For PunchOut index catalogs, the Classification determines the location of
the PunchOut item within catalogs displayed to users. For a list of UNSPSC codes,
4 PunchOut
Transaction
see www.unspsc.org.
Create these catalogs and publish them on an e-commerce hub to the supplier’s
customers. The catalog manager within buying organizations downloads them and
stores them for use with procurement applications.
4 PunchOut
Transaction
Users see the contents of the supplier’s PunchOut index catalogs alongside regular,
static catalog items.
• Store-level catalogs list one PunchOut item for all of the supplier’s products and
services. Users must search the supplier site to find the desired item.
4 PunchOut
Transaction
• Aisle-level catalogs list multiple PunchOut items corresponding to related products
and services.
• Product-level catalogs list only one product or service. Users do not need to search.
To determine how broad to make PunchOut items, consider the supplier’s business
model, the makeup of the supplier’s product and service offerings, and the structure of
the supplier’s PunchOut website.
4 PunchOut
Transaction
The more search and configuration tools the supplier has on the supplier’s website,
the more broad they can make the PunchOut items in the supplier’s index catalogs.
PunchOutSetupRequest
To initiate a PunchOut session, the user selects the supplier’s PunchOut item. The
procurement application generates a PunchOutSetupRequest document and sends it to
an e-commerce hub, which forwards it to the supplier’s PunchOut website.
4 PunchOut
Transaction
4 PunchOut
Transaction
Item selected by user <SelectedItem>
<ItemID>
<SupplierPartID>5555</SupplierPartID>
</ItemID>
</SelectedItem>
</PunchOutSetupRequest>
</Request>
</cXML>
4 PunchOut
Transaction
The payloadID and timestamp attributes near the beginning are used by cXML clients to
track documents and to detect duplicate documents.
The From, To, and Sender elements allow receiving systems to identify and authorize
parties. The From and To elements in a document do not change. However, as the
document travels to its destination, intermediate nodes (such as Ariba Supplier
Network) change the Sender element.
4 PunchOut
Transaction
Network commerce hubs can change credential domains in the From and To elements,
if that change results in more reliable identification. So for example, the From
credential domain might change from CustomDomain to DUNS.
The operation attribute specifies the type of session the buyer initiates. It can create, edit,
inspect, or source.
4 PunchOut
Transaction
• create sessions generate new shopping carts, which correspond to new purchase
requisitions.
• edit sessions reopen previously created shopping carts or RFQs for modification.
The procurement application sends line-item data as part of the
PunchOutSetupRequest. The PunchOut website can use this data to re-instantiate the
shopping cart created during the original session.
• inspect sessions reopen previously created shopping carts or RFQs for viewing only.
As with the edit operation, the procurement application sends line-item data as part
4 PunchOut
Transaction
of the PunchOutSetupRequest. However, after re-instantiating the shopping cart, the
PunchOut website does not allow modification of its contents.
• source sessions generate a RFQ for a sourcing application.
timestamp="2002-08-15T08:45:35-07:00">
<Header>
<From>
<Credential domain="DUNS">
<Identity>65652314</Identity>
</Credential>
</From>
<To>
<Credential domain="DUNS">
<Identity>83528721</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN200001</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Procure 2.1</UserAgent>
</Sender>
</Header>
<Request>
<PunchOutSetupRequest operation="edit">
<BuyerCookie>1CX3L4843PPZO</BuyerCookie>
<Extrinsic name="UserEmail">jsmith</Extrinsic>
<Extrinsic name="UniqueName">John_Smith</Extrinsic>
<Extrinsic name="CostCenter">610</Extrinsic>
<BrowserFormPost>
<URL>https://bigbuyer.com:2600/punchout?client=NAwliuo</URL>
</BrowserFormPost>
<SupplierSetup>
<URL>http://www.workchairs.com/punchout.asp</URL>
</SupplierSetup>
<ItemOut quantity="2">
<ItemID>
<SupplierPartID>220-6338</SupplierPartID>
<SupplierPartAuxiliaryID>E000028901
</SupplierPartAuxiliaryID>
</ItemID>
</ItemOut>
</PunchOutSetupRequest>
</Request>
</cXML>
If the user initiated the edit session by selecting a catalog item, the
PunchOutSetupRequest would contain a SelectedItem element, like a create session.
4 PunchOut
Transaction
1. The hub receives the PunchOutSetupRequest document from the user.
2. The hub verifies the buyer's ID (From and Shared Secret) with that buyer’s e-
commerce account. It also identifies the requested supplier (To).
3. The hub looks up the supplier’s shared secret from the supplier’s account and
inserts it (Shared Secret) into the Sender element.
4 PunchOut
Transaction
4. The hub finds the URL of the supplier’s PunchOut website in the supplier’s
account and sends the PunchOutSetupRequest document to it.
5. The supplier’s website receives the cXML document and knows that it is
authenticated because it contains the supplier’s own shared secret.
6. The supplier’s website uses information in the From element to identify the
requester at the company level (for example, acme.com).
4 PunchOut
7. The supplier can use the Contact and extrinsic data in the body of the request
Transaction
to uniquely identify the user (for example, John Smith in Finance at
acme.com).
4 PunchOut
Transaction
Direct PunchOut is an alternative method for initiating PunchOut sessions, where the
PunchOut site, not a network commerce hub, authenticates the PunchOut request. For
more information, see “Direct PunchOut” on page 111.
In previous cXML releases, theSupplierSetup element provided the only way to specify
the URL of the supplier’s PunchOut website. Beginning with cXML 1.1, the e-
4 PunchOut
Transaction
commerce hub already knows the URL of the supplier’s PunchOut website.
Also, starting with cXML 1.1, procurement applications can use the SelectedItem
element to specify store-, aisle-, or product-level PunchOut.
The SupplierSetup element has been deprecated. However, the supplier’s PunchOut
website must handle both methods until all PunchOut websites and procurement
applications recognize and send the SelectedItem element.
4 PunchOut
Transaction
In addition, the PunchOutSetupRequest might also contain extrinsic data, data that the
supplier can use to further identify users, such as:
PunchOutSetupResponse
After receiving a PunchOutSetupRequest, the supplier’s website sends a
PunchOutSetupResponse. The PunchOutSetupResponse document serves two functions:
It contains a URL element that specifies the Start Page URL to pass to the user’s Web
browser for the interactive browsing session. This URL must contain enough state
information to bind to a session context on the supplier’s website, such as the identity
of the requester and the contents of the BuyerCookie element. Due to URL length
restrictions in many applications, this URL should refer to the state information rather
than including it all.
4 PunchOut
Transaction
<cXML xml:lang="en-US" payloadID="933694607739" timestamp="2002-08-15T08:46:00-
07:00">
<Response>
<Status code="200" text="success"></Status>
<PunchOutSetupResponse>
<StartPage>
<URL>
http://xml.workchairs.com/retrieve?reqUrl=20626;Initial=TRUE
</URL>
4 PunchOut
Transaction
</StartPage>
</PunchOutSetupResponse>
</Response>
</cXML>
PunchOutOrderMessage
After the user selects items on the supplier’s website, configures them, and clicks the
4 PunchOut
Transaction
supplier’s “Check Out” button, the supplier’s website sends a
PunchOutOrderMessage document to communicate the contents of the shopping
basket to the buyer’s procurement application. This document can contain much more
data than the other documents, because it needs to be able to fully express the contents
of any conceivable shopping basket. This document does not strictly follow the
Request/Response paradigm; its use will be explained in detail.
4 PunchOut
Transaction
<?xml version="1.0"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="933695160894" timestamp="2002-08-15T08:47:00-
07:00">
<Header>
<From>
<Credential domain="DUNS">
<Identity>83528721</Identity>
</Credential>
</From>
4 PunchOut
Transaction
<To>
<Credential domain="DUNS">
<Identity>65652314</Identity>
</Credential>
</To>
<Sender>
<Credential domain="workchairs.com">
<Identity>website 1</Identity>
</Credential>
<UserAgent>Workchairs cXML Application</UserAgent>
4 PunchOut
Transaction
</Sender>
</Header>
<Message>
<PunchOutOrderMessage>
<BuyerCookie>1CX3L4843PPZO</BuyerCookie>
<PunchOutOrderMessageHeader operationAllowed="edit">
<Total>
<Money currency="USD">763.20</Money>
</Total>
</PunchOutOrderMessageHeader>
<ItemIn quantity="3">
<ItemID>
<SupplierPartID>5555</SupplierPartID>
<SupplierPartAuxiliaryID>E000028901
</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">763.20</Money>
</UnitPrice>
<Description xml:lang="en">
<ShortName>Excelsior Desk Chair</ShortName>
Leather Reclining Desk Chair with Padded Arms
</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">5136030000
</Classification>
<LeadTime>12</LeadTime>
</ItemDetail>
</ItemIn>
</PunchOutOrderMessage>
</Message>
</cXML>
SupplierPartAuxiliaryID acts as a supplier cookie. This field allows the supplier to transmit
additional data, such as quote number or another cXML document. The procurement
application passes it back to the supplier in any subsequent PunchOut edit or inspect
sessions, and in the resulting cXML purchase order. The supplier can use the supplier
cookie to associate items in a purchase requisition with the corresponding items in a
shopping cart at the supplier’s website.
4 PunchOut
Transaction
UnitOfMeasure describeshow the product is packaged or shipped. For more
information, see “UnitOfMeasure” on page 57.
4 PunchOut
Transaction
Modifications to the Supplier’s Web Pages
To receive or send the three cXML PunchOut session documents,
PunchOutSetupRequest, PunchOutSetupResponse, and PunchOutOrderMessage, the
supplier might need to modify or create four pages on the supplier’s website:
4 PunchOut
• Launch Page
Transaction
• Start Page
• Sender Page
• Order Receiver Page
To illustrate how the supplier might implement these pages, this chapter uses simple
Active Server Page (ASP) code samples and the Microsoft Internet Explorer 5 XML
Parser. Actual implementation of these pages will vary depending on the supplier
4 PunchOut
Transaction
development environment (for example, CGI, JavaScript, or WebObjects).
Launch Page
The Launch Page receives all authenticated PunchOutSetupRequest documents from the
e-commerce hub. It reads the HTTP stream sent from the hub and validates the cXML
request embedded within that stream against the cXML DTD (in the case of ASP,
using method calls to the Internet Explorer 5 XML parser). After validation, the
4 PunchOut
Transaction
supplier’s Launch Page extracts elements from the document in order to:
The supplier’s Launch Page should store the following data for use by the supplier’s
Start Page:
4 PunchOut
Transaction
• Identity of the language of the user (xml:lang) so the supplier can provide localized
content
• Type of the request (create, edit, or inspect)
• Any extrinsic data that further identifies the user and the user location
Following is a sample Launch Page. This code does not use an XML tool to
dynamically generate the PunchOutSetupResponse, but instead uses a static XML
template into which line item data is filled. This code is intended for illustrative
purposes only.
<script language=JScript RUNAT=Server>
function elementValue(xml, elem)
{
var begidx;
var endidx;
var retStr;
begidx = xml.indexOf(elem);
if (begidx > 0) {
endidx = xml.indexOf('</',begidx);
if (endidx > 0)
retStr = xml.slice(begidx+elem.length,
endidx);
return retStr;
}
return null;
}
function timestamp( dt )
{
var str;
var milli;
str = dt.getFullYear() + "-" + twoChar( 1 + dt.getMonth() ) + "-";
str += twoChar( dt.getDate() ) + "T" + twoChar( dt.getHours() ) + ":";
str += twoChar( dt.getMinutes() ) + ":" + twoChar( dt.getSeconds() ) + ".";
milli = dt.getMilliseconds();
4 PunchOut
Transaction
milli = milli.toString();
if ( 3 == milli.length ) {
str += milli;
} else {
str += "0" + twoChar( milli );
}
str += "-08:00";
return str;
}
4 PunchOut
Transaction
function genProlog( cXMLvers, randStr )
{
var dt;
var str;
var vers, sysID;
var nowNum, timeStr;
vers = "1.2.014";
sysID = "http://xml.cXML.org/schemas/cXML/" + vers + "/cXML.dtd";
dt = new Date();
4 PunchOut
Transaction
nowNum = dt.getTime();
timeStr = timestamp( dt );
str = '<?xml encoding="UTF-8"?>\n';
str += '<!DOCTYPE cXML SYSTEM "' + sysID + '">\n';
str += '<cXML payloadID="' + nowNum + ".";
str += randStr + '@' + Request.ServerVariables("LOCAL_ADDR");
str += '" timestamp="' + timeStr + '">';
return str;
}
4 PunchOut
</script>
Transaction
<%
REM Create data needed in prolog.
Randomize
randStr = Int( 100000001 * Rnd )
prologStr = genProlog( "1.0", randStr )
Response.ContentType = "text/xml"
Response.Charset = "UTF-8"
%>
<%
4 PunchOut
Transaction
REM This receives the PunchOutSetup request coming from the e-commerce hub.
REM It takes the ORMSURL and buyercookie, attaches them to the Start Page URL,
REM and sends the response back to the requester.
REM punchoutredirect.asp?bc=2133hfefe&url="http://workchairs/com/..&redirect="
Dim ret
Dim punch
Dim statusText
Dim statusCode
Dim cookie
Dim url
4 PunchOut
Transaction
Dim xmlstr
Dim fromUser
Dim toUser
cookie = ""
url = ""
xmlstr = ""
dir = ""
path = Request.ServerVariables("PATH_INFO")
dir = Left(path, InstrRev(path, "/"))
if IsEmpty(dir) then
dir = "/"
end if
The supplier’s Launch Page should return a StartPage URL that is unique for that
PunchOut session. In addition, this URL should be valid for only a limited amount of
time. By deactivating this URL, the supplier makes it more difficult for unauthorized
users to access the supplier’s Start Page.
4 PunchOut
Transaction
Remember to implement functionality for subsequent edit and inspect sessions. Users
cannot change order details for PunchOut items (such as quantity) within their
procurement application. They must re-PunchOut with an edit session. For the greatest
benefit to users, inspect sessions that occur after the supplier receives the order should
display order status.
Start Page
4 PunchOut
Transaction
The supplier’s Start Page logs the requester into an account on the supplier’s website.
From the supplier’s Start Page, users begin their shopping experience. This page
might already exist at the supplier’s website, so modify it to query user name and
password information from the PunchOutSetupRequest document.
Allow only authorized users into the supplier’s Start Page. If the supplier waits until
the check-out step to authenticate them, their confidential pricing or terms are not
protected.
4 PunchOut
Transaction
If the supplier uses HTTP browser cookies to track user preferences and sessions,
they should be destroyed after the PunchOutOrderMessage is sent to buyers. Destroying
these cookies prevents the possibility of offering privileged features to unauthorized
users.
Sender Page
4 PunchOut
Transaction
The Sender Page sends the contents of the user’s shopping cart to the user. As
described earlier, after users fill their shopping carts, they click the supplier’s “Check
Out” button.
Below is a simple ASP implementation of this feature. This code does not use an
XML tool to dynamically generate the PunchOutOrderMessage, but instead uses a static
XML template into which line item data is filled. This code is intended for
illustrative purposes only.
4 PunchOut
Transaction
This is a portion of a supplier’s website product page:
<!--#include file="punchoutitem.inc"-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from
url=(0093)https://secure1.shore.net/wbird/cgi/vsc.cgi/wbird/houses/urban.htm?L+wbird+w
adt4101+928011405 -->
<TABLE border=0>
<TBODY>
4 PunchOut
Transaction
<TR>
<TD><IMG src="UrbanHouses_files/uhjm.gif"> </TD>
The following listing is the include file (punchoutitem.inc) referenced in the previous
example:
<%
REM This asp is included in items.asp, which specifies the item parameters, formats
REM a cXML document, and allows the user to proceed with a checkout of the item.
function CreateCXML(toUser, fromUser, buyerCookie, unitPrice, supPartId, desc)
%>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM
"http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="<%= Now &"@"&
Request.ServerVariables("LOCAL_ADDR")%>" timestamp="<%= Now
%>">
<Header>
<From>
<Credential domain="hub.com">
<Identity><%= toUser%></Identity>
</Credential>
</From>
<To>
<Credential domain="hub.com">
<Identity><%= fromUser%></Identity>
</Credential>
</To>
<Sender>
<Credential domain="hub.com">
<Identity><%= toUser%></Identity>
</Credential>
<UserAgent>PunchoutSite</UserAgent>
</Sender>
</Header>
<Message>
<PunchOutOrderMessage>
4 PunchOut
Transaction
<BuyerCookie><%= buyerCookie%></BuyerCookie>
<PunchOutOrderMessageHeader
operationAllowed="edit">
<Total>
<Money currency="USD"><%=
unitPrice%></Money>
</Total>
</PunchOutOrderMessageHeader>
<ItemIn quantity="1">
4 PunchOut
Transaction
<ItemID>
<SupplierPartID><%= supPartId%></SupplierPartID>
<SupplierPartAuxiliaryID><%= supPartAuxId%>
</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD"><%= unitPrice%>
</Money>
</UnitPrice>
4 PunchOut
Transaction
<Description xml:lang="en"><%= desc%>
</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification
domain="SupplierPartID"><%= supPartId%>
</Classification>
</ItemDetail>
</ItemIn>
</PunchOutOrderMessage>
4 PunchOut
</Message>
Transaction
</cXML>
<% end function
toUser = Session("toUser")
fromUser = Session("fromUser")
buyerCookie = Session("buyercookie")
4 PunchOut
Transaction
url = Session("urlToPost")
if not IsEmpty(buyerCookie) then
%>
<FORM METHOD=POST ACTION=<%= url%>>
<INPUT TYPE=HIDDEN NAME="cxml-urlencoded" VALUE="<% CreateCXML
toUser, fromUser, buyerCookie, unitPrice, supPartId, supPartAuxId, desc%>">
<INPUT TYPE=SUBMIT value=BUY>
</FORM>
<%else%>
</p>
4 PunchOut
Transaction
<%
end if
end function
%>
The AddBuyButton function contains the FORM POST that sends the URL-encoded
PunchOutOrderMessage back to the user.
This encoding permits the supplier to design a checkout Web page that contains the
cXML document. When users click the supplier’s “Check Out” button, the supplier’s
website presents the data, invisible to users, to the procurement application as an
HTML Form Submit.
Cancelling PunchOut
The supplier might want to add a “Cancel” button to their pages so that users can
cancel their PunchOut session. The “Cancel” button sends an empty
PunchOutOrderMessage that tells the procurement application that no items will be
returned, and to delete existing PunchOut items from the requisition. The supplier can
also use it to perform any housekeeping needed by the supplier’s website, such as
clearing the shopping cart and closing the user session.
4 PunchOut
Transaction
Order Receiver Page
The Order Receiver Page accepts cXML purchase orders sent by buying
organizations. It could be similar to the Launch Page discussed above. For
information about receiving purchase orders, see Chapter 5, “Purchase Orders.”
4 PunchOut
Transaction
PunchOut Website Suggestions
This section provides suggestions and information you should consider when
planning the implementation of a PunchOut website.
Implementation Guidelines
Follow these guidelines when developing the supplier’s PunchOut website:
4 PunchOut
Transaction
• Study the cXML User’s Guide (this document).
• Use an XML parser and validate documents against the cXML DTD.
• Use the xml:lang= property to identify users’ languages so the supplier can provide
localized content.
• Use the From credential to identify buying organizations.
4 PunchOut
• Send a unique, temporary URL for the session on redirect.
Transaction
• Do not persist browser cookies.
• Do not overburden the supplier’s customers with extrinsic data requirements.
• For each line item, use UNUOM (United Nations Units of Measure) and UNSPSC
(Universal Standard Products and Services Classification).
• Provide real value to the supplier’s customers. Display product availability, order
status, and special promotions.
4 PunchOut
Transaction
• Checkout should be easy and intuitive. Ideally, users should need to click only three
buttons to buy.
• Code for subsequent edit and inspect sessions. Users cannot change order details
for PunchOut items (such as quantity) within their procurement application. They
must re-PunchOut with an edit session.
• For the greatest benefit to users, inspect sessions should display order status.
• Test the supplier’s PunchOut website. Allow time for testing with the supplier’s
4 PunchOut
Transaction
• The supplier should return the BuyerCookie element they receive. It should not be
changed.
• Make use of the supplier cookie (SupplierPartAuxiliaryID).
Personalization
The header of the PunchOutSetupRequest always identifies the buying organization, but
the request might also contain Contact and Extrinsic data (such as user’s cost center,
user’s location, or product category) that the supplier can use to determine the
dynamic URL to serve to the user.
Although not all buying organizations send this extrinsic data, it can enable the
supplier to customize the supplier’s Web store beyond the simple organization level.
For example, the supplier could provide a separate Web store for each cost center
within the buying organization (or each product category or each user).
The supplier could also store and display the user’s previous quotes. The supplier
could allow users to reuse quotes, check the status of orders, and create reports on
past activity. To avoid security problems, store quote history only at the per-user level.
4 PunchOut
Transaction
A key consideration during planning is the amount of effort required to implement a
highly dynamic and customized PunchOut website. The supplier needs to balance
between customization and complexity—a complex website takes longer to
implement and maintain, but it could offer more value to users. It is recommended
that the supplier start with a simple PunchOut website and enhance it over time.
4 PunchOut
Transaction
PunchOut Transaction
The PunchOut message definitions are request/response messages within the Request
and Response elements. All of the following messages must be implemented by
suppliers to support PunchOut.
4 PunchOut
Transaction
procurement application, send setup information, and receive a response indicating
where to go to initiate an HTML browsing session on the remote website.
The order of cXML message flow in the PunchOut transaction is shown in the
following diagram:
1. PunchOutSetupRequest
Network
4 PunchOut
Transaction
2. PunchOutSetupResponse
PROCUREMENT SUPPLIER
3. PunchOutOrderMessage
APPLICATION
Sourcing
4 PunchOut
Transaction
PunchOut can also be used for sourcing. A user can PunchOut from a procurement
application to a sourcing application to initiate a RFQ (Request For Quote) session.
The sourcing application will return a PunchOutSetupResponse with the URL of the
start page of the sourcing application. With the URL, the end user goes to the
sourcing application to provide more configuration information for RFQ.
4 PunchOut
Transaction
PunchOutSetupRequest
The PunchOutSetupRequest document contains a Header element and a
PunchOutSetupRequest element.
Header
From
To
4 PunchOut
Transaction
Sender
UserAgent
4 PunchOut
Transaction
An unique identifier for application sending the PunchOutSetupRequest. Consists of
the software company name, product name, and version. Version details can appear in
parentheses.
PunchOutSetupRequest
4 PunchOut
Transaction
4 PunchOut
Transaction
4 PunchOut
Transaction
The following example shows a PunchOutSetupRequest:
<PunchOutSetupRequest operation="create">
<BuyerCookie>34234234ADFSDF234234</BuyerCookie>
<Extrinsic name="UserEmail">betty</Extrinsic>
<Extrinsic name="UniqueName">BettyBuyer</Extrinsic>
<Extrinsic name="CostCenter">Marketing</Extrinsic>
<BrowserFormPost>
<URL>http://orms.acme.com:1616/punchoutexit</URL>
</BrowserFormPost>
4 PunchOut
Transaction
<SelectedItem>
<ItemID>
<SupplierPartID>54543</SupplierPartID>
</ItemID>
</SelectedItem>
<SupplierSetup>
<URL>http://workchairs.com/cxml</URL>
</SupplierSetup>
<ShipTo>
<Address addressID="1000467">
<Name xml:lang="en">1000467</Name>
<PostalAddress>
<DeliverTo>Betty Buyer</DeliverTo>
<Street>123 Main Street</Street>
<City>Sunnyvale</City>
<State>CA</State>
<PostalCode>94089</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
</Address>
</ShipTo>
</PunchOutSetupRequest>
An ItemOut list describes an existing shopping cart (items from a previous PunchOut
session). The inspect operation initiates a read-only PunchOut session (enforced by
both the client and the server) to view details about the listed items. The edit operation
also starts from the previous shopping cart (described using the ItemOut list), but
allows changes. Support for the edit operation implies inspect support (see
“PunchOutOrderMessageHeader” on page 107 and “Empty Shopping Carts” on page
108). This list can also describe items to be sourced. For more information, see
“Sourcing” on page 99.
4 PunchOut
Transaction
The Credential of the supplier is used to obtain the PunchOut location from the E-
commerce network hub where suppliers can store the URLs of their PunchOut
websites. E-commerce network hubs receive the PunchOutSetupRequest document, read
the supplier’s ID, find the URL of the PunchOut website from the supplier’s account
information, and send the PunchOutSetupRequest document to that URL. The
e-commerce network hub, not the buyer, specifies the URL of the PunchOut website,
which is more flexible. The URL specified in the SupplierSetup element of the
PunchOutSetupRequest has been deprecated; cXML servers will ignore this element in
4 PunchOut
Transaction
the future.
BuyerCookie
This element transmits information that is opaque to the remote website, but it must
be returned to the originator for all subsequent PunchOut operations. This element
allows the procurement application to match multiple outstanding PunchOut requests.
BuyerCookie is unique per PunchOut session.
4 PunchOut
Transaction
BrowserFormPost
This element is the destination for the data in the PunchOutOrderMessage. It contains a
URL element whose use will be further explained in the PunchOutOrderMessage
definition. If the URL-Form-Encoded method is not being used, this element does not
have to be included.
Extrinsic
4 PunchOut
Transaction
This optional element contains any additional data that the requestor wants to pass to
the external website. The cXML specification does not define the content of Extrinsic
elements—it is something that each requestor and remote website must agree on and
implement.
4 PunchOut
implementations. In the following context, the new data further describes the user
Transaction
initiating the PunchOut request.
<Extrinsic name="department">Marketing</Extrinsic>
The following example passes the user initiating the PunchOut and their department.
<Extrinsic name=”CostCenter"">450</Extrinsic>
<Extrinsic name=”User”>jsmith</Extrinsic>"
4 PunchOut
Transaction
With cXML 1.1 and higher, the Contact element obsoletes the “Cost Center” and
“User” extrinsics.
The Extrinsic element can also appear in the OrderRequestHeader, ItemDetail, SpendDetail,
and ContractItem elements. These contexts are described further elsewhere in this
document.
SelectedItem
For the contents of the SelectedItem element, procurement applications use the ItemID
(SupplierPartID and SupplierPartAuxiliaryID) from the PunchOut index catalog. No catalog
changes are required.
Procurement applications should initially send both the new SelectedItem element and
the old PunchOut URL in the PunchOutSetupRequest. E-commerce network hubs use
the old URL only for suppliers that have not yet stored their PunchOut URL
destinations.
For edit and inspect operations, SelectedItem should appear only if the user chose to
return to the supplier’s website while viewing new information in the local catalog
rather than items in an existing requisition. In either case, the current shopping cart
must appear in the ItemOut list.
4 PunchOut
Transaction
SupplierSetup
This optional element specifies the URL to which to post the PunchOutSetupRequest.
This element is not needed if the e-commerce network hub knows the supplier’s
PunchOut URL.
ShipTo
4 PunchOut
Transaction
This optional element specifies the Ship To address for the item. Suppliers might want
to use this information to formulate delivery time or price estimates.
PunchOutSetupResponse
After the remote website has received a PunchOutSetupRequest, it responds with a
PunchOutSetupResponse, as shown below:
4 PunchOut
Transaction
<PunchOutSetupResponse>
<StartPage>
<URL>
http://premier.workchairs.com/store?23423SDFSDF23
</URL>
</StartPage>
</PunchOutSetupResponse>
StartPage
4 PunchOut
Transaction
This element contains a URL element that specifies the URL to pass to the browser to
initiate the PunchOut browsing session requested in the PunchOutSetupRequest. This
URL must contain enough state information to bind to a session context on the remote
website, such as the requestor identity and the appropriate BuyerCookie element.
At this point, the user who initiated the PunchOutSetupRequest browses the external
website, and selects items to be transferred back to the procurement application
through a PunchOutOrderMessage.
4 PunchOut
Transaction
PunchOutOrderMessage
This element sends the contents of the remote shopping basket or sourcing RFQ to the
originator of a PunchOutSetupRequest. It can contain much more data than the other
messages because it must be able to fully express the contents of any conceivable
shopping basket on the external website. This message does not strictly follow the
Request/Response model.
4 PunchOut
Transaction
The remote website generates a PunchOutOrderMessage when the user checks out.
This message communicates the contents of the remote shopping basket to the
procurement application; for example:
<PunchOutOrderMessage>
<BuyerCookie>34234234ADFSDF234234</BuyerCookie>
<PunchOutOrderMessageHeader operationAllowed="create">
<Total>
<Money currency="USD">100.23</Money>
</Total>
</PunchOutOrderMessageHeader>
<ItemIn quantity="1">
<ItemID>
<SupplierPartID>1234</SupplierPartID>
<SupplierPartAuxiliaryID>
additional data about this item
</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">10.23</Money>
</UnitPrice>
<Description xml:lang="en">
Learn ASP in a Week!
</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="SPSC">12345</Classification>
<LeadTime>1</LeadTime>
</ItemDetail>
</ItemIn>
</PunchOutOrderMessage>
BuyerCookie
This element is the same element that was passed in the original
PunchOutSetupRequest. It must be returned here to allow the procurement
application to match the PunchOutOrderMessage with an earlier
PunchOutSetupRequest.
4 PunchOut
Transaction
PunchOutOrderMessageHeader
This element contains information about the entire shopping basket contents being
transferred. The only required element is Total, which is the overall cost of the items
being added to the requisition, excluding tax and shipping charges.
Additional elements that are allowed are Shipping and Tax, which are the amount and
description of any shipping or tax charges computed on the remote website.
4 PunchOut
Transaction
ShipTo is also optional, and it specifies the Ship-To addressing information the user
selected on the remote site or that was passed in the original PunchOutSetupRequest.
All monetary amounts are in a Money element that always specifies currency in a
standardized format.
The SourcingStatus element is optional, and relays updated information about a sourced
4 PunchOut
Transaction
RFQ. The content of the element could be a textual description of the update, such as
the actual status update string displayed to the user.
4 PunchOut
Transaction
The operationAllowed attribute controls whether the user can initiate later PunchOut
sessions containing data from this PunchOutOrderMessage:
4 PunchOut
Transaction
• operationAllowed="edit": allows subsequent PunchOut sessions to both inspect and
change these items.
The quoteStatus attribute is used for an sourced RFQ or any other long-running
operation. The PunchOutOrderMessage will contain the results of an end user session
in the sourcing application and contains either status update information for a
particular RFQ, a new RFQ, or an update to a completed RFQ.
4 PunchOut
Transaction
• If the operation in the original PunchOutSetupRequest was inspect, the item list of
the PunchOutOrderMessage must be ignored by the procurement application. The
supplier site should return no ItemIn elements in this case.
• If a PunchOutOrderMessage contains no ItemIn elements and the operation was
create, no items should be added to the requisition because the supplier site or the
user has cancelled the PunchOut session without creating a shopping cart.
• If the operation was edit and the PunchOutOrderMessage contains no ItemIn
elements, existing items from this PunchOut session must be deleted from the
requisition in the procurement application.
The Status code “204/No Content” indicates the end of a session without change to
the shopping cart. Again, the PunchOutOrderMessage (which is always needed for
the BuyerCookie) should not contain ItemIn elements. This code would be handled
identically to the other “empty” cases detailed above unless the operation was edit. In
that case, the user cancelled the session without making any change and no change
should be made to the requisition in the procurement application.
ItemIn
This element adds an item from a shopping basket to a requisition in the procurement
application. It can contain a variety of elements, only two of which are required:
ItemID and ItemDetail.
4 PunchOut
Transaction
The optional elements are ShipTo, Shipping, and Tax, which are the same elements as
those specified in PunchOutOrderMessage, above. In addition, ItemIn can contain the
optional SpendDetail, which can contain the optional TravelDetail, FeeDetail, LaborDetail, and
Extrinsic elements. TravelDetail provides detailed information about travel and expense
line items, FeeDetail provides information about fees not defined elsewhere, and
LaborDetail provides detailed information about temporary labor line items. For more
information, see “TravelDetail” on page 130, “FeeDetail” on page 151, “LaborDetail”
on page 151, and “Extrinsic” on page 126.
4 PunchOut
Transaction
The ItemIn and ItemOut structures match one-to-one, except for the Distribution and
Comments elements and requisitionID and requestedDeliveryDate attributes available in the
ItemOut element. The procurement application can convert directly between ItemIn and
ItemOut lists when initiating an inspect or edit operation. Suppliers can convert one to
the other (dropping the listed extensions available in the ItemOut element) when
executing an edit operation. The procurement application can perform the direct
conversion and add additional shipping and distribution information and comments
when initiating an OrderRequest transaction. ItemDetail data (with the possible exception
4 PunchOut
Transaction
of Extrinsic elements) contained within ItemIn elements must not be removed when
converting from ItemIn to ItemOut.
ItemID
This element uniquely identifies the item to the remote website. It is the only element
required to return to the remote website to re-identity the item in later PunchOut
sessions.
4 PunchOut
Transaction
ItemID contains two elements: SupplierPartID and SupplierPartAuxiliaryID. Only
SupplierPartID is required. SupplierPartAuxiliaryID helps the remote website transport
complex configuration or bill-of-goods information to re-identify the item when it is
presented to the remote website in the future.
4 PunchOut
Transaction
additional XML elements is insufficient.
ItemDetail
This element contains descriptive information about the item that procurement
applications present to users. The contents of an ItemDetail element can be quite
complex, but the minimum requirements are simple: UnitPrice, Description,
UnitOfMeasure, and Classification. Optional elements include a ManufacturerPartID, a
ManufacturerName, a URL, a LeadTime, and any number of Extrinsic elements.
4 PunchOut
Transaction
In the context of an ItemIn element, the Extrinsic elements contained within an ItemDetail
function identically to those found within an Index (specifically an IndexItemAdd).
The optional LeadTime element describes the number of days needed for the buyer to
receive the product. For example:
<LeadTime>14</LeadTime>
Note that in an IndexItemAdd element, duplicate LeadTime information might come from
both ItemDetail, where it is optional, and IndexItemDetail, where it is mandatory. If the
LeadTime elements are defined in both cases, then they should be identical.
Description
This element describes the item in a textual form. Because this text might exceed the
limits of a short table of line items (or other constrained user interface) and random
truncations could occur, the Description element contains an optional ShortName
element.
For example:
<Description xml:lang="en-US">
<ShortName>Big Computer</ShortName>
This wonder contains three really big disks, four CD-Rom drives, two Zip drives, an
ethernet card or two, much more memory than you could ever use, four CPUs on two
motherboards. We’ll throw in two monitors, a keyboard and the cheapest mouse we can
find lying around.
</Description>
might appear as “Big Computer” where space is tight, and “Big Computer: This
wonder … lying around.” (or as two separate but complete fields) where there is space
to display more text.
Catalog creators should not use ShortName to duplicate the information in Description.
Instead, they should use ShortName to name the product, and Description to describe
product details.
CIF 3.0 catalog format also supports ShortName. The CIF field name is Short Name.
4 PunchOut
Transaction
SupplierList
4 PunchOut
Transaction
<ItemID>
<SupplierPartID>unknown</SupplierPartID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">10.23</Money>
</UnitPrice>
<Description xml:lang="en">Learn ASP in a Week!</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="SPSC">12345</Classification>
4 PunchOut
Transaction
<ManufacturerPartID>ISBN-23455634</ManufacturerPartID>
<ManufacturerName>O'Reilly</ManufacturerName>
<URL> URL for more information </URL>
<LeadTime>7</LeadTime>
</ItemDetail>
<SupplierList>
<Supplier>
<Name xml:lang="en">Supplier #1 </Name>
<SupplierID domain="duns">0000000</SupplierID>
</Supplier>
4 PunchOut
Transaction
<Supplier>
<Name xml:lang="en">Supplier #2 </Name>
<SupplierID domain="duns">1111111</SupplierID>
<SupplierID domain="duns">2222222</SupplierID>
</Supplier>
</SupplierList>
</ItemOut>
4 PunchOut
Transaction
Direct PunchOut
Direct PunchOut is a cXML capability that can reduce the time it takes for users to
display the first page of a supplier’s PunchOut site.
It offers faster PunchOut session initiation than regular PunchOut by allowing clients
to send PunchOutSetupRequest documents directly to PunchOut sites for authentication,
without first going through a network commerce hub for authentication and
4 PunchOut
Transaction
forwarding.
If suppliers indicate (through their cXML profile) that they support direct PunchOut,
clients send PunchOut requests directly to them. Clients enable PunchOut sites to
authenticate these requests by either including a Message Authentication Code
(MAC) generated by a trusted third party, or by making a client digital certificate
available.
Authentication Methods
Direct PunchOut is made possible by two alternative authentication methods:
Servers indicate the authentication method they support through their cXML Profile.
ProfileResponse
PunchOut sites indicate that they support direct PunchOut and specify the
authentication methods they support by including the following options for
PunchOutSetupRequest in their ProfileResponse documents.
<Transaction requestName="PunchOutSetupRequest">
<URL>https://service.bighub.com/cxml</URL>
<Option name="Direct.URL">https://bigsupplier.com/punchout</Option>
<Option name="Direct.AuthenticationMethod.CredentialMac">Yes</Option>
<Option name="Direct.AuthenticationMethod.Certificate">Yes</Option>
5 Purchase Orders
This chapter describes how to set up a website to receive cXML-format purchase
orders. It also describes how to send purchase order status messages to buying
organizations or marketplaces.
5 Purchase Orders
• Purchase Order Process
• OrderRequest Documents
• Response to an OrderRequest
• Accepting Order Attachments
5 Purchase Orders
Purchase Order Process
Procurement applications convert approved purchase requisitions into one or more
purchase orders. A purchase order is a formal request from a buying organization to a
supplier to fulfill a contract.
cXML is just one format for transmitting purchase orders. Other common formats are
e-mail, fax, and ANSI X.12 EDI (Electronic Data Interchange). cXML is the best
5 Purchase Orders
format for purchase orders because it allows you to easily automate order processing.
cXML’s well-defined structure allows order-processing systems to easily interpret the
elements within a purchase order. With little or no human intervention, the
appropriate data within purchase orders can be routed to your shipping, billing, and
sales departments, as needed.
In addition, the cXML order-routing method allows the transmittal of any supplier
cookies (SupplierPartAuxiliaryID) and purchase order attachments.
When you configure your account on a network commerce hub, you specify a URL to
which all cXML purchase orders will be sent. Upon receiving a purchase order, you
send it to your internal order management system and fulfill it as you normally would.
Your website must also return an Order Response document to the network commerce
hub, which tells the buyer that you successfully received and parsed the purchase
order.
You do not need a PunchOut website in order to receive cXML purchase orders;
PunchOut and cXML order-receiving are distinct capabilities. However, the
infrastructure and applications required for supporting PunchOut are the same for
receiving cXML purchase orders.
There are two types of cXML documents used in the transaction of purchase orders.
Procurement applications send OrderRequest documents, and you respond with
generic Response documents. These documents pass through the network commerce
hub for authentication and routing.
OrderRequest Documents
The OrderRequest document is analogous to a purchase order. The following diagram
shows the structure of the OrderRequest element:
5 Purchase Orders
5 Purchase Orders
5 Purchase Orders
5 Purchase Orders
The following example shows the structure of the OrderRequest element:
5 Purchase Orders
<OrderRequest>
<OrderRequestHeader … >
…
</OrderRequestHeader>
<ItemOut … >
…
</ItemOut>
<ItemOut … >
…
</ItemOut>
</OrderRequest>
5 Purchase Orders
</TelephoneNumber>
</Phone>
</Address>
</ShipTo>
<BillTo>
<Address isoCountryCode="US" addressID="12">
<Name xml:lang="en">Acme Accounts Payable</Name>
5 Purchase Orders
<PostalAddress name="default">
<Street>124 Union Street</Street>
<City>San Francisco</City>
<State>CA</State>
<PostalCode>94128</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
<Phone name="work">
<TelephoneNumber>
<CountryCode isoCountryCode="US">1</CountryCode>
5 Purchase Orders
<AreaOrCityCode>415</AreaOrCityCode>
<Number>6666666</Number>
</TelephoneNumber>
</Phone>
</Address>
</BillTo>
<Shipping>
<Money currency="USD">12.34</Money>
<Description xml:lang="en-US">FedEx 2-day</Description>
</Shipping>
5 Purchase Orders
<Tax>
<Money currency="USD">10.74</Money>
<Description xml:lang="en">CA State Tax</Description>
</Tax>
<Payment>
<PCard number="1234567890123456" expiration="2002-03-12"/>
</Payment>
</OrderRequestHeader>
<ItemOut quantity="2" lineNumber1>
<ItemID>
5 Purchase Orders
<SupplierPartID>220-3165</SupplierPartID>
<SupplierPartAuxiliaryID>E000028901</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">2344.00</Money>
</UnitPrice>
<Description xml:lang="en">Laptop Computer Notebook Pentium® II
processor w/AGP, 300 MHz, with 12.1" TFT XGA Display
</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">43171801</Classification>
<URL>http://www.supplier.com/Punchout.asp</URL>
OrderRequestHeader Element
The following example shows an OrderRequestHeader in full detail:
<OrderRequestHeader
orderID="DO1234"
orderDate="1999-03-12T13:30:23+8.00"
type="new"
requisitionID="R1234"
shipComplete="yes">
<Total>
<Money currency="USD">12.34</Money>
</Total>
<ShipTo>
<Address>
<Name xml:lang="en">Acme Corporation</Name>
<PostalAddress name="Headquarters">
<DeliverTo>Joe Smith</DeliverTo>
<DeliverTo>Mailstop M-543</DeliverTo>
<Street>123 Anystreet</Street>
<City>Sunnyvale</City>
<State>CA</State>
<PostalCode>90489</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
5 Purchase Orders
</Address>
</ShipTo>
<BillTo>
<Address>
<Name xml:lang="en">Acme Corporation</Name>
<PostalAddress name="Finance Building">
<Street>124 Anystreet</Street>
5 Purchase Orders
<City>Sunnyvale</City>
<State>CA</State>
<PostalCode>90489</PostalCode>
<Country isoCountryCode="United States">United States</Country>
</PostalAddress>
</Address>
</BillTo>
<Shipping>
<Money currency="USD">12.34</Money>
<Description xml:lang="en-US">FedEx 2-day</Description>
5 Purchase Orders
</Shipping>
<Tax>
<Money currency="USD">12.34</Money>
<Description xml:lang="en">CA State Tax</Description>
</Tax>
<Payment>
<PCard number="1234567890123456" expiration="1999-03-12"/>
</Payment>
<PaymentTerm payInNumberOfDays="45">
</PaymentTerm>
5 Purchase Orders
<PaymentTerm payInNumberOfDays="30">
<Discount>
<DiscountPercent percent="2">
</Discount>
</PaymentTerm>
<PaymentTerm payInNumberOfDays="20">
<Discount>
<DiscountPercent percent="3">
</Discount>
</PaymentTerm>
5 Purchase Orders
<Contact role="purchasingAgent">
<Name xml:lang="en-US">Mr. Purchasing Agent</Name>
<Email>[email protected]</Email>
<Phone name="Office">
<TelephoneNumber>
<CountryCode isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>800</AreaOrCityCode>
<Number>5551212</Number>
</TelephoneNumber>
</Phone>
</Contact>
<Comments xml:lang="en-US">
Anything well formed in XML can go here.
</Comments>
<SupplierOrderInfo orderID=12345>
</OrderRequestHeader>
5 Purchase Orders
contains a total for the order, whereas the item-level Tax element contains the tax just
for the item. Do not include duplicate information in Comments elements at both
levels.
Total
5 Purchase Orders
This element contains the total cost for the items in the order, excluding any tax and
shipping. It is a container for the Money element.
ShipTo/BillTo
These elements contain the addresses of the Ship To and Bill To entities on the
OrderRequest.
All items must be billed to a single entity. Therefore, the BillTo element appears only in
5 Purchase Orders
the OrderRequestHeader. Items from an order can be sent to multiple locations. Like the
Shipping element (see next section), the ShipTo element can therefore appear either in
the OrderRequestHeader or in individual ItemOut elements.
The Address element contains an addressID attribute that specifies an ID for the address.
This attribute is used to support address codes for relationships that require ID
references. This value should not be the name of a company or person. It is intended
to deepen application-to-application integration. For example, a ShipTo location
identifier could be:
5 Purchase Orders
<Address isoCountryCode="US" addressID="1000487">
The Name element contained within an Address element should always specify the
company name.
The DeliverTo element is listed twice, the first line specifying the name of the person to
receive the goods, and the second specifying their location (building, city, office,
mailstop) where the items should be delivered. The location should always be
5 Purchase Orders
complete enough to be used in a mailing label. For example,
<PostalAddress name="Headquarters">
<DeliverTo>Joe Smith</DeliverTo>
<DeliverTo>Mailstop M-543</DeliverTo>
<Street>123 Anystreet</Street>
<City>Sunnyvale</City>
<State>CA</State>
<PostalCode>90489</PostalCode>
<Country isoCountryCode="US">UnitedStates</Country>
</PostalAddress>
Country contains a human readable name. The isoCountryCode attribute value is the ISO
country code from the ISO 3166 standard.
Avoid empty or whitespace elements because missing values can affect EDI and
cXML suppliers.
Shipping
This element describes how to ship line items and the shipping cost. If the Shipping
element is present in the OrderRequestHeader, it must not appear in the ItemOut elements.
If it is not present in the OrderRequestHeader, it must appear in the ItemOut elements.
Tax
This element contains the tax associated with the order. This element is present if the
buying organization computes tax. When appearing within the OrderRequestHeader, Tax
describes the total tax for an order. Tax elements at the item level can describe line
item tax amounts.
Payment
Describes the payment instrument used to pay for the items requested. In the above
example, the Payment element contains a PCard element, which encodes a standard
purchasing card into the cXML document. In the future, other payment instruments
might be defined.
PaymentTerm
Defines the payment term in orders and invoices. Use PaymentTerm instead of the
InvoiceDetailPaymentTermpreviously defined. PaymentTerm defines either the net term
(without discount) or the discount term (with discount).
Discount
The percentage or amount of the discount term. The discount rate applies if the
invoice total is paid within the time specified by payInNumberOfDays. Positive rates
denote discounts and negative rates denote penalties. Do not use a percentage sign
(%) or divide by 100; for example “2” means 2%.
5 Purchase Orders
Do not use the Discount element if the PaymentTerm is a net term.
Contact
The supplier uses Contact element information to follow up on an order. This element
identifies a person and provides a list of ways to reach that person or entity. The only
5 Purchase Orders
required element is the Name of the contact. Optional and repeating possibilities
include PostalAddress (not recommended for immediate correction of order problems),
Email, Phone, Fax, and URL.
In cXML 1.0, the extrinsics User and CostCenter elements often provided contact
information. With cXML 1.1 and higher, the Contact element provide alternatives to
these extrinsics.
Buying organizations might choose to use this element to identify the original
5 Purchase Orders
requestor, the procurement application system administrator, or some other contact
who can take responsibility for correcting problems with orders. Contact can differ
from both BillTo and ShipTo information for an order.
5 Purchase Orders
(optional) relationships that require id references.
5 Purchase Orders
buyerCorporate Contact details the supplier has about the buying
organization.
supplierCorporate Contact details about the supplier.
The same Contact role must not appear at both the header and item levels.
There is no default role, due to the disparate contents of the Contact element. So,
cXML applications treat a Contact without a role attribute as an additional role.
TelephoneNumber
For international dialing, the CountryCode contains the dial code for a country after any
escape codes. England, for example, would be represented as:
<CountryCode isoCountryCode="UK">44</CountryCode>"
Fax
The Fax element specifies the Fax number of the person or department where goods
are to be shipped or billed. This element contains the TelephoneNumber element
described above.
Comments
Arbitrary human-readable information buyers can send within purchase orders. This
string data is not intended for the automated systems at supplier sites.
The Comments element can contain an Attachment element for including external files.
Attachment
Comments can attach external files to augment purchase orders. The Attachment element
appears within Comments, and it contains only a reference to the external MIME part
of the attachment. All attachments should be sent in a single multipart transmission
with the OrderRequest document. Even if this is not possible, the contentID provided by
the Attachment element must be usable to retrieve the attachment.
5 Purchase Orders
For details about the transfer of attached files, see “Attachments” on page 33.
Attachment contains a single URL with scheme “cid:”. An attached file in a cXML
document might appear as:
<Comments>
<Attachment>
5 Purchase Orders
<URL>cid: [email protected]</URL>
</Attachment>
Please see attached image for my idea of what this
should look like
</Comments>
The Comments element appears in many places within the cXML protocol, but it can
contain the Attachment element only within OrderRequest documents.
5 Purchase Orders
Use Comments to provide local comments specific to the current document.
Followup
All cXML implementations should use the more robust Profile transaction to retrieve
5 Purchase Orders
and convey information about server capabilities, including supported cXML version,
supported transactions, and options to those transactions. See “Profile Transaction”
on page 26 for more information.
DocumentReference
5 Purchase Orders
DocumentReference identifies the purchase order to be updated.
SupplierOrderInfo
Extrinsic
This element contains machine-readable information related to the order, but not
defined by the cXML protocol. In contrast, the Comments element passes information
for human use. Extrinsic elements contain data that is likely to appear in later
documents; the Comments element does not. At this level, Extrinsic extends the
description of all items contained in the purchase order. Some Extrinsic information
might also describe the overall purchase order without affecting the meaning of any
contained ItemOut.
Each named Extrinsic can appear only once within the lists associated with the
OrderRequestHeader and individual ItemOut elements (within the contained ItemDetail
elements). The same name must not appear in both the OrderRequestHeader list and any
list associated with the ItemOut elements. If the same Extrinsic name and value is
repeated in all ItemOut lists, it should be moved to the OrderRequestHeader.
The Extrinsic element can also appear in the IndexItem, PunchOutSetupRequest and
ContractItem elements. These contexts are described later in this document. Extrinsic
values are case-insensitive.
ItemOut
The following example shows a minimum valid ItemOut element.
<ItemOut quantity="1"
lineNumber=”1”>
<ItemID>
<SupplierPartID>5555</SupplierPartID>
</ItemID>
</ItemOut>
5 Purchase Orders
ItemOut has the following attributes:
5 Purchase Orders
lineNumber increases once per ItemOut in a “new” OrderRequest.
Clients should always specify this attribute in an
(optional)
OrderRequest, although it might not be useful in other
ItemOut contexts.
The buyer’s requisition identifier for this line item. Must not
requisitionID
be included if requisitionID is specified in the
(optional)
OrderRequestHeader.
agreementItemNumer The buyer’s master agreement identifier for the line item.
(optional)
The date item was requested for delivery, which allows
5 Purchase Orders
requestedDeliveryDate item-level delivery dates in the OrderRequest. It must be in
(optional)
ISO 8601 format.
Indicates that the item is a non-catalog (ad-hoc) item.
Non-catalog purchase orders contain items entered
manually by requisitioners, not items selected from
electronic catalogs. Often, these items do not have valid
isAdHoc part numbers. Non-catalog orders usually require special
(optional) validation and processing.
Users enter non-catalog items to purchase products and
services on an ad-hoc basis or because they could not
5 Purchase Orders
find them in electronic catalogs.
The lineNumber attribute remains constant for any item through updates to the order.
Deletion of items from an order never changes the lineNumber of remaining items. New
items have higher numbers than those previously included in the order. A change to
an existing item (an increased quantity, for example) does not affect the lineNumber of
that item.
5 Purchase Orders
<ItemOut quantity="2" lineNumber="1"
requestedDeliveryDate="1999-03-12">
<ItemID>
<SupplierPartID>1233244</SupplierPartID>
<SupplierPartAuxiliaryID>ABC</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">1.34</Money>
</UnitPrice>
<Description xml:lang="en">hello</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">12345</Classification>
<ManufacturerPartID>234</ManufacturerPartID>
<ManufacturerName xml:lang="en">foobar</ManufacturerName>
<URL>www.bar.com</URL>
</ItemDetail>
<ShipTo>
<Address>
<Name xml:lang="en">Acme Corporation</Name>
<PostalAddress name="Headquarters">
<Street>123 Anystreet</Street>
<City>Sunnyvale</City>
<State>CA</State>
<PostalCode>90489</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
</Address>
</ShipTo>
<Shipping>
<Money currency="USD">1.34</Money>
<Description xml:lang="en-US">FedEx 2-day</Description>
</Shipping>
<Tax>
<Money currency="USD">1.34</Money>
<Description xml:lang="en">foo</Description>
</Tax>
<Distribution>
<Accounting name="DistributionCharge">
<AccountingSegment id="23456">
<Name xml:lang="en-US">G/L Account</Name>
<Description xml:lang="en-US">Entertainment</Description>
</AccountingSegment>
<AccountingSegment id="2323">
<Name xml:lang="en-US">Cost Center</Name>
<Description xml:lang="en-US">Western Region Sales
</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="USD">.34</Money>
</Charge>
</Distribution>
<Distribution>
<Accounting name="DistributionCharge">
<AccountingSegment id="456">
<Name xml:lang="en-US">G/L Account</Name>
<Description xml:lang="en-US">Travel</Description>
</AccountingSegment>
<AccountingSegment id="23">
<Name xml:lang="en-US">Cost Center</Name>
<Description xml:lang="en-US">Europe Implementation
5 Purchase Orders
</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="USD">1</Money>
</Charge>
</Distribution>
5 Purchase Orders
<Comments xml:lang="en-US">Comment</Comments>
</ItemOut>
The ItemDetail element allows additional data to be sent to suppliers instead of just the
unique identifier for the item represented by the ItemID.
If isAdHoc="yes" exists for some items and not for others, the requisition should be
broken into two requisitions: one for catalog items and one for non-catalog items.
Suppliers will then be able to automatically process as many requisition items as
5 Purchase Orders
possible, instead of having to manually process both catalog and non-catalog items.
The ShipTo, Shipping, Tax, Contact, Comments, and Extrinsic elements (some nested within
ItemDetail or SpendDetail) are identical to the ones that can be in the OrderRequestHeader.
These elements specify per-item data such as shipping, shipping type, and associated
cost. Use these elements either at the OrderRequestHeader level, or at the ItemOut level,
but not at both levels. Tax is the only exception, for more information, see “Tax” on
page 122.
5 Purchase Orders
ItemID
The basic ItemID element, which provides unique identification of an item. ItemID is
defined at “ItemID” on page 109.
Path
The basic Path element, which provides node and path information for a document.
5 Purchase Orders
Path is
defined at “Path Element” on page 158.
ItemDetail
The basic ItemDetail element, which contains descriptive information about a line item
that procurement applications present to users. ItemDetail is defined at “ItemDetail” on
page 109.
SupplierID
SupplierList
Defines a list of suppliers that might be associated with a quote item in ItemOut.
Supplier
SpendDetail
This optional element provides detailed information regarding travel, fee, and labor
line items. The following diagram shows the structure of the SpendDetail element:
SpendDetail can be present in ItemIn and ItemOut elements for the following types of
messages:
• PunchOutSetupRequest
• PunchOutOrderMessage
• OrderRequest
• ConfirmationRequest
The basic ItemIn element adds an item from a shopping basket to a requisition in the
procurement application during a PunchOut session. ItemIn is defined at “ItemIn” on
page 108.
TravelDetail
5 Purchase Orders
The following diagram shows the structure of TravelDetail:
5 Purchase Orders
The following example shows the location of SpendDetail and TravelDetail within an
OrderRequest document:
5 Purchase Orders
<OrderRequest... >
<OrderRequestHeader >
...
</OrderRequestHeader >
<ItemOut>
<ItemDetail >
...
</ItemDetail>
<SpendDetail>
<TravelDetail>
5 Purchase Orders
...
</TravelDetail>
</SpendDetail>
</ItemOut>
</OrderRequest>
5 Purchase Orders
confirmationNumber
this travel line item. For example, hotel reservation number
or e-ticket number from the airline.
pnrLocator Passenger Name Record (PNR) locator used by the travel
(optional) booking provider.
Date and time that this quote will expire. This value is
quoteExpirationTime normally supplied in the PunchoutOrderMessage. If no
(optional) value is supplied, it is assumed that this quote will not
expire.
Common Elements
Dates and times in cXML must be formatted in the restricted subset of ISO
8601. This is described in the Word Wide Web Consortium (W3C) Note
entitled “Date and Time Formats” available at www.w3.org/TR/NOTE-
datetime-970915.html. See “Date, Time, and other Data Types” on page 39
for more information.
Vendor
Address
The basic Address element provides the physical address of the vendor.
Typically, this is the address the vendor’s a business location or
headquarters. Address is described further in “cXML Conventions” on page
31.
SupplierID
Supplier ID for this vendor. This is a (domain, value) pair so that travel
booking providers can define their SupplierID elements according to the
convention they prefer, such as D-U-N-S or TaxID.
Each travel booking provider can specify multiple Supplier ID values. This
capability enables a provider to use a single implementation to coordinate
with various enterprise implementations that use different SupplierID domains.
TermsAndConditions
Text descriptions of terms and conditions associated with a travel line item.
For example, a car rental TermsAndConditions normally includes boundary
limit, additional mileage charges, gasoline charges, and other restriction
information. Multiple TermsAndConditions can be included in a single travel
line item.
5 Purchase Orders
Description
PolicyViolation
5 Purchase Orders
Line-item level policy violation that results from the user selecting this
particular travel item. Policy violations are not associated at the header level
to ensure clear identification of a violation with the appropriate line item.
5 Purchase Orders
violation - a serious violation of company policy
Description
PolicyViolationJustification
5 Purchase Orders
Justification for this PolicyViolation. Typically, the user selects a
PolicyViolationJustification from a standard list of justifications at the travel
booking provider’s web site.
• Comments
Additional comments to further clarify the PolicyViolationJustification, given
by the user.
Penalty
5 Purchase Orders
Penalty (if any) for this travel segment.
Money
Description
Textual description of the cause of the penalty. For example, a change fee
associated with an air ticket.
AvailablePrice
The common AvailablePrice element describes other available prices that the
user did not select.
Value Description
lowest Lowest price available regardless of the travel policies
lowestCompliant Lowest price available that is compliant with travel
policies
highestCompliant Highest price available that is compliant with travel
policies
highest Highest price available regardless of the travel policies
other Other, specify in the Description
Money
Description
Rate
Defines the rate for a travel item. The following example shows a Rate
element for a CarRentalFee:
<CarRentalFee type="baseRate">
<Total>
<Money currency="USD">215.99</Money>
</Total>
<Rate quantity="4">
<Total>
<Money currency="USD">119.96</Money>
</Total>
<UnitRate>
<Money currency="USD">215.99</Money>
<UnitOfMeasure>WEE</UnitOfMeasure>
5 Purchase Orders
</UnitRate>
</Rate>
</CarRentalFee type="baseRate">
5 Purchase Orders
a hotel would be expressed as:
quantity
quantity = 4
UnitofMeasure in UnitRate = DAY
Total
The total amount for the rate. The total amount must equal to quantity x
UnitRate. All Rate amounts for aline item must add up to the Total for that line
item.
5 Purchase Orders
UnitRate
UnitRate defines the rate for a single unit according to the unit of measure.
For example, a single nightly rate for a hotel room can be expressed with
Money equal to the nightly rate amount and the UnitOfMeausre equal to DAY.
The amount to be paid per unit (of time or other measure). In the case of
multiple UnitRates (a rate schedule), use TermReference elements to distinguish
5 Purchase Orders
them.
Description
Textual description for the rate. For a hotel stay, the Description could contain
“hotel nightly rate.”
BookingClassCode
5 Purchase Orders
BookingClassCode is a common element. When used in a travel line item, it
indicates the class of the line item. For example, BookingClassCode is
commonly used to convey frequent flyer information for air travel
reservations.
Each buyer-travel booking provider pair can use any industry standard they
choose. The following example shows a minimal BookingClassCode element:
<BookingClassCode code="W">
<Description xml:lang="en">Coach class</Description>
</BookingClassCode>
Description
Airport
The common Airport element, which contains the three-letter IATA airport
code, is used in AirLegOrigin, AirLegDestination, CarRentalPickup, CarRentalDropoff,
HotelDetail, RailLegOrigin and RailLegDestination.
• Address
The optional Address element provides the physical address of the airport.
Meal
The Meal element of an AirLeg can contain two optional, common elements:
BookingClassCode and Description. The following example represents a heated
vegetarian dinner for an AirLeg.
<Meal>
<Description xml:lang="en">vegetarian dinner</Description>
<BookingClassCode code="H"></BookingClassCode>
</Meal>
• Description
A text description of the meal, including any special needs such as
vegetarian, gluten-free, or dairy-free.
5 Purchase Orders
• BookingClassCode
The common BookingClassCode element is defined at “BookingClassCode”
on page 135. The BookingClassCode of Meal defines the code for the meal.
For example, airlines typically use the following meal codes:
Code Description
5 Purchase Orders
B Breakfast
C Complimentary liquor
D Dinner
F Food for purchase
G Food and beverage for purchase
H Hot meal
K Continental breakfast
5 Purchase Orders
L Lunch
M Meal
N No meal service
O Cold meal
P Liquor for purchase
R Refreshments
S Snack or brunch
5 Purchase Orders
V Refreshments for purchase
• Description
A text description of the meal. Use this description to provide details not
included in BookingClassCode.
For more information about xml standards and basic elements, see Chapter 2, “cXML
Basics.”
5 Purchase Orders
AirDetail
The AirDetail element provides information about an air trip. The following diagram
shows the structure of AirDetail:
TripType
TripType is a container for the type attribute, which is required in both AirDetail and
RailDetail to indicate a round trip, one way, or multi-leg trip.
<TripType type="round"></TripType>
Attribute Description
round round trip
oneWay one-way trip
multiLeg multi-leg or open-jaw trip
AirLeg
5 Purchase Orders
The following diagram shows the structure of AirLeg:
5 Purchase Orders
The AirLeg element provides detailed information about a trip that includes one or
more airplane flights. The following example shows an AirLeg element for a one-way
flight:
5 Purchase Orders
<AirLeg travelSegment="1"
departureTime="2004-12-01T16:10:00-08:00"
arrivalTime="2004-12-01T17:10:00-08:00"
flightNumber="SW 990"
seatNumber="20F"
seatType="aisle"
stops="0"
equipment="Boeing 737">
<Vendor preferred="no">
<Address>
5 Purchase Orders
...
</Address>
</Vendor>
<AirLegOrigin>
<Airport airportCode="SFO">
<Address>
...
</Address>
</Airport>
</AirLegOrigin>
5 Purchase Orders
<AirLegDestination>
<Airport airportCode="BUR">
<Address>
...
</Address>
</Airport>
</AirLegDestination>
<BookingClassCode code="W">
<Description xml:lang="en">Coach class</Description>
</BookingClassCode>
<Meal type="snack">
<Description xml:lang="en">Vegetarian snack</Description>
</Meal>
</AirLeg>
Vendor
The common Vendor element, which provides information about the vendor
of a service, is defined at “Vendor” on page 132.
AirLegOrigin / AirLegDestination
The following example shows a detailed AirLeg for a flight from San
Francisco to Miami.
<AirLegOrigin>
<Airport airportCode="SFO">
<Address>
<Name xml:lang="en">San Francisco Internal Airport</Name>
<PostalAddress>
<Street>San Francisco International Airport</Street>
<City>San Francisco</City>
<State>CA</State>
<PostalCode>94128</PostalCode>
<Country isoCountryCode="US">UnitedStates</Country>
</PostalAddress>
5 Purchase Orders
</Address>
</Airport>
</AirLegOrigin>
<AirLegDestination>
<Airport airportCode="MIA">
<Address>
<Name xml:lang="en">Miami International Airport</Name>
5 Purchase Orders
<PostalAddress>
<Street>4200 NW 21 Street>
<City>Miami</City>
<State>FL</State>
<PostalCode>33122</PostalCode>
<Country isoCountryCode="US">UnitedStates</Country>
</PostalAddress>
</Address>
</Airport>
</AirLegDestination>
5 Purchase Orders
Airport
The common Airport element, which contains the three-letter IATA airport
code in the airportCode attribute, and an optional Address element, is defined at
“Airport” on page 136.
5 Purchase Orders
BookingClassCode
5 Purchase Orders
C, CN, D, J, I, Z business class
Y, YN, B, BN, M, H, V, VN, O, Q, QN, S, K, KN, L, coach class
U, T, W
Rate
The common Rate element is defined at “Rate” on page 134. The total of all
specified AirLeg rates must equal the line item total.
Meal
The common Meal element, which describes one meal in a travel line item, is
defined at “Meal” on page 136.
AvailablePrice
The optional, common AvailablePrice element, which defines available prices that the
user did not select, is defined at “AvailablePrice” on page 134. The AvailablePrice
element of AirDetail defines available price information for a single-leg, multi-leg, or
round trip.
Penalty
The common Penalty element, which describes extra charges assessed by vendors for
user changes to travel line items, is defined at “Penalty” on page 133. The Penalty
element of an AirLeg describes extra charges for changes to, or cancellation of, an air
travel reservation.
CarRentalDetail
5 Purchase Orders
CarRentalDetail has the following attributes:
5 Purchase Orders
Vendor
The common Vendor element, which provides information about the vendor of a
service, is defined at “Vendor” on page 132.
CarRentalPickup / CarRentalDropoff
5 Purchase Orders
entities on the CarRentalDetail. Both CarRentalPickup and CarRentalDropoff require the
common Airport element, which specifies the airport location.
5 Purchase Orders
5 Purchase Orders
BookingClassCode
A four-letter code, which indicates the rental car class. Each buyer-travel booking
provider pair can use the standard they choose. For example, a common U.S. standard
for car rental:
M (Mini)
E (Economy)
C (Compact)
S (Standard)
I (Intermediate)
1st Letter
F (Full size)
P (Premium)
L (Luxury)
V (MiniVan)
X (Special)
B (2 door)
C (2/4 door)
D (4 door)
T (Convertible)
2nd Letter F (Four wheel drive)
V (Van)
W (Wagon)
S (Sport)
X (Special)
A (Automatic)
3rd Letter
M (Manual)
R (A/C)
4th Letter
N (No A/C)
CarRentalFee
CarRentalFee defines the actual charges and fees that apply to this car rental. To capture
the breakdown of various fees, use multiple CarRentalFee elements within one
CarRentalDetail element. The total of these fees must add up to the total at the line item
level.
5 Purchase Orders
CarRentalFee has one attribute:
5 Purchase Orders
Value Description
additionalDriver Additional driver fee
airportAccessFee Airport access fee
baseRate Base rental rate
childSeat Child seat charge
collisionDamageInsurance Collision damage insurance
dropOffCharge Drop off charge
5 Purchase Orders
liabilityInsurance Liability insurance
luggageRack Luggage rack charge
mobilePhone Mobile phone base charge
navigationSystem Navigation system
other Other charges
prepaidGasoline Prepaid gasoline charge
touristTax Tourist tax
5 Purchase Orders
vehicleLicensingFee Vehicle licensing fee
Total
Total amount for this CarRentalFee. All Rate amounts for a line item must
must add up to the Total for that line item.
Rate
5 Purchase Orders
Fee information for individual charges for this CarRentalFee.
LimitedMileage
LimitedMileage specifies the quantity and unit of measure of the mileage limit.
UnitOfMeasure
AvailablePrice
The optional, common AvailablePrice element, which defines available prices that the
user did not select, is defined at “AvailablePrice” on page 134.
HotelDetail
5 Purchase Orders
Vendor
The common Vendor element, which provides information about the vendor of a
service, is defined at “Vendor” on page 132. For HotelDetail, the Vendor element defines
the hotel provider.
Address
5 Purchase Orders
Physical address of the hotel. This might be different from the address specified in the
Vendor field.
The Address in Vendor might be the address of the hotel’s corporate
headquarters, for example, while the Address in HotelDetail would be the address of the
individual hotel.
RoomType
5 Purchase Orders
RoomType has the following attributes:
5 Purchase Orders
(optional) king | queen | full | double | single | other
Description
Amenities
5 Purchase Orders
lines, and other information about a hotel room.
Description
BookingClassCode
Meal
The common Meal element is defined at “Meal” on page 136. The Meal element of
HotelDetail defines any complimentary meals that are included with the room, such as
complimentary continental breakfast.
Rate
The common Rate element is defined at “Rate” on page 134. The Rate element of
HotelDetail defines one or more rates for the hotel stay. For example, the nightly rate or
valet parking rate.
AvailablePrice
RailDetail
TripType
TripType is a container for the type attribute, which is required in both AirDetail and
RailDetail . The TripType element defines a round trip, one way, or multi-leg trip.
5 Purchase Orders
<TripType type="round"></TripType>
Value Description
round round trip
5 Purchase Orders
oneWay one-way trip
multiLeg multi-leg or open-jaw trip
RailLeg
One or more RailLeg elements that make up this RailDetail. Each RailDetail must include
at least one RailLeg.
5 Purchase Orders
The following diagram shows the structure of RailLeg:
5 Purchase Orders
RailLeg has the following attributes:
5 Purchase Orders
arrivalTime Local date and time of arrival at the destination location.
trainNumber Train number.
seatNumber Seat number.
carType The type of the rail car.
Vendor
The common Vendor element, which provides information about the vendor
of a service, is defined at “Vendor” on page 132. For RailLeg, the Vendor
element defines the rail travel provider, such as Amtrak.
RailLegOrigin / RailLegDestination
Airport
The common Airport element, which contains the three-letter IATA airport
code in the airportCode attribute, and an optional Address element, is defined at
“Airport” on page 136.
Address
BookingClassCode
Rate
Meal
The common Meal element is defined at “Meal” on page 136. The Meal
element of HotelDetail defines any complimentary meals that are included with
the room, such as complimentary continental breakfast.
AvailablePrice
5 Purchase Orders
Penalty
The common Penalty element, which describes extra charges assessed by vendors for
user changes to travel line items, is defined at “Penalty” on page 133. The Penalty
element of RailLeg defines extra charges for changes to, or cancellation of, a rail travel
reservation.
5 Purchase Orders
FeeDetail
Conveys information about one-time or recurring fees that are not explicitly defined
elsewhere in cXML. For example, a one-time fee for furniture rental would not fall
into any category defined in TravelDetail or LaborDetail, but could be described in
FeeDetail.
5 Purchase Orders
isRecurring Indicates that the fee is recurring.
(optional)
UnitRate
The amount to be paid per unit of time or other measure. In the case of multiple
UnitRates. as in a rate schedule, use TermReference elements to distinguish them.
5 Purchase Orders
Period
LaborDetail
LaborDetail contains
information about an item related to temporary labor. The
following diagram shows the structure of the LaborDetail element:
.
5 Purchase Orders
UnitRate
UnitRate represents the amount to be paid per unit of time (or of some other measure).
In the case of multiple UnitRates, use TermReference elements to distinguish them.
TermReference
This TermReference identifies this UnitRate as being the rate for the Overtime payCode.
Period
Period specifies the period of time over which the service occurs.
Contractor
Contractor identifiesthe contractor being engaged for temporary labor. The contractor
is uniquely identified by a ContractorIdentifier element, which is exchanged between the
buyer and supplier prior to sending orders or timecards. For more information about
TimeCard transactions, see Chapter 8, “TimeCard Transaction.”
5 Purchase Orders
ContractorIdentifier
ContractorIdentifier uniquely identifies the contractor for both the buyer and
supplier. ContractorIdentifier has the following attribute:
5 Purchase Orders
systems to determine who assigned the identification.
domain buyerReferenceID implies that the identification was
generated in the buyer system.
supplierReferenceID implies that the identification was
generated in the supplier system.
Contact
5 Purchase Orders
JobDescription
Supervisor
Supervisor specifies contact information for the person who will supervise the
contractor.
5 Purchase Orders
WorkLocation
Extrinsic
5 Purchase Orders
Extrinsic elements are intended to provide additional machine-readable information.
They extend the cXML protocol to support features not required by all
implementations. The cXML specification does not define the content of Extrinsic
elements. Each buyer-supplier pair must agree on and implement their definitions of
Extrisic elements.
Describes detailed information for any undefined spend category. The name attribute
of the Extrinsic element should specify the type of spend category, such as print, market
research, or project labor.
<SpendDetail>
<Extrinsic name="MarketResearchDetail">
<Extrinsic name="ResearchObjectives">test objectives</Extrinsic>
<Extrinsic name="ProjectNumber">PN3434343</Extrinsic>
</Extrinsic>
</SpendDetail>
The Extrinsic element can also appear in the OrderRequestHeader, ItemDetail, and
ContractItem elements. These contexts are described further elsewhere in this
document. For more information on Extrinsic, see “Extrinsic” on page 153.
Distribution
Distribution divides the cost of an item among multiple parties. Suppliers return the
Distribution element on invoices to facilitate the buyer’s reconciliation process.
Accounting
AccountingSegment
The AccountingSegment element can contain any relevant accounting code used by a
buying organization. Examples of possible values are asset number, billing code, cost
center, G/L account, and department. For example:
<AccountingSegment id="456">
<Name xml:lang="en-US">G/L Account</Name>
<Description xml:lang="en-US">Travel</Description>
</AccountingSegment>
5 Purchase Orders
AccountingSegment has the following attribute:
Name
5 Purchase Orders
An identifying name for this AccountingSegment with respect to the others in the
Accounting element.
Description
5 Purchase Orders
Charge
This element specifies the amount to be charged to the entity represented by the
Accounting element.
Money
5 Purchase Orders
The unique ISO standard three-letter currency code. For
currency
example, “USD” = United States Dollar.
Response to an OrderRequest
This document is the response part of the synchronous Request-Response transaction.
5 Purchase Orders
The following example shows a Response to an OrderRequest document:
<cXML payloadID="9949494" xml:lang="en"
timestamp="1999-03-12T18:39:09-08:00">
<Response>
<Status code="200" text="OK"/>
</Response>
</cXML>
The Response tells the requestor its OrderRequest was successfully parsed and acted on
by the remote part of HTTP connection. It does not communicate order-level
acknowledgement, such as which items can be shipped, or which need to be
backordered.
cXML contains only references to external MIME parts sent within one multipart
MIME envelope (with the cXML document, in an e-mail or faxed together).
Commerce network hubs receive the attachments, and can forward them to suppliers
or store them for online retrieval.
For more information about purchase order attachments, see “Attachments” on page
33.
6 Path Routing
In complex relationships between buyers and suppliers, a document might be routed
through several intermediary systems before reaching the intended recipient. Path
Routing enables documents to be routed by and copied to intermediary systems such
as marketplaces, and commerce network hubs.
6 Path Routing
• Overview of Path Routing
• Nodes
• Adding Nodes to PunchOutOrderMessage
• Creating OrderRequests
• Other Routable Documents
6 Path Routing
• CopyRequest
Direct marketplaces can be PunchOut sites that enable external buyers to access
suppliers’ PunchOut catalogs. For a marketplace to track transactions originating
from it, it must receive copies of all purchase orders as they route to the supplier.
To receive copies of all purchase orders as they route, the marketplace adds itself as a
Copy node to the Path of all PunchOutOrderMessage documents sent to the external
6 Path Routing
Indirect Marketplaces can receive OrderRequest documents, modify them, split them,
and route them to suppliers. Indirect marketplaces are router nodes that create new
versions and route OrderRequest documents to suppliers.
Adding a Path element at the item or header level enables copying and routing of
cXML documents for marketplaces and commerce network hubs. The Path element
records the path taken between the buyer and supplier which documents can later use
to find their way back to a supplier.
Nodes
Nodes appear in the Path element of either the header section, or ItemIn and ItemOut
elements. Each node in the Path element can be either a router node or a copy node. If
the node is of type “copy”, the system simply wants a copy of each document passing
through. If the node is of type “route”, the system will modify and re-route each
document passing through. Each system in the path must specify which type it is.
Path Element
The Path element contains nodes that are either of type=”copy” or type=”route”. For
example, the following contains a copy node and a router node:
<Path>
<Node type="copy">
<Credential domain="NetworkId">
<Identity>AN01000000111</Identity>
</Credential>
</Node>
<Node type="route">
6 Path Routing
<Credential domain="NetworkId">
<Identity>AN01000000233</Identity>
</Credential>
</Node>
</Path>
Router Nodes
6 Path Routing
A router node creates a new version of the document it receives and routes it to the
next node in the path. The routed document typically changes unit price, bill-to, or
ship-to address information.
OriginalDocument Element
6 Path Routing
the payloadID of the original document. This enables the network hub to keep track of
each hop in the Path and decide which version of the document to display to the
appropriate party.
DocumentReference Element
Each node is responsible for updating any DocumentReference elements in the new
document it generates. For example, when an OrderRequest of type update or delete is
routed to an intermediary node, this node must change the DocumentReference in the
6 Path Routing
new version of the updated OrderRequest to reference the correct payloadId as
illustrated in the following diagram:
6 Path Routing
Buyer Marketplace
(Router Node) Supplier
(Router Node)
ConfirmationRequest ConfirmationRequest
PayloadID4 PayloadID3
OriginalDocument: PayloadID3 OriginalDocument: PayloadID3
DocumentReference: PayloadID1 DocumentReference: PayloadID2
Buyer Marketplace
Supplier
(Router Node)
Copy Nodes
A copy node wants a copy of the document. For example, the following except
illustrates a copy node:
<Node type="copy">
<Credential domain="NetworkId">
<Identity>AN01000000111</Identity>
</Credential>
</Node>
Node sequence is top to bottom, with the originating buyer at the top. The
intermediary node closest to the end supplier must add the supplier of record to the
path as well, if the supplier has not already created the path.
6 Path Routing
The procurement application must include itself as the first router node in the path,
which allows other documents such as ConfirmationRequest and ShipmentNoticeRequest
documents to be routed back to the originating buyer.
Path Element
The Path element contains nodes that are either of type=”copy” or type=”route”. A Path
6 Path Routing
element is in each ItemIn element of a PunchOutOrderMessage. Each system visited by
the PunchOutOrderMessage must add itself as a node to the Path element for each ItemIn
element it cares about.
The following PunchOutOrderMessage shows the Path element with two nodes:
<ItemIn quantity="1">
<ItemID>
<SupplierPartID>1234</SupplierPartID>
6 Path Routing
</ItemID>
<Path>
<Node type="copy">
<Credential domain="NetworkId">
<Identity>AN01000000111</Identity>
</Credential>
</Node>
<Node type="route">
<Credential domain="NetworkId">
<Identity>AN01000000233</Identity>
6 Path Routing
</Credential>
</Node>
</Path>
<ItemDetail>
<UnitPrice>
<Money currency="USD">10.23</Money>
</UnitPrice>
<Description xml:lang="en">Learn ASP in a Week!</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="SPSC">12345</Classification>
<ManufacturerPartID>ISBN-23455634</ManufacturerPartID>
<ManufacturerName>O'Reilly</ManufacturerName>
</ItemDetail>
</ItemIn>
Credentials
The From and To elements of the cXML header in a routed document refer to the buyer
6 Path Routing
and supplier of record. Neither of these parties is required to appear in the Path,
because they might be visible only to one of the Router nodes.
Creating OrderRequests
When generating purchase orders, procurement applications split requisitions based
on the Path and SupplierID of each of the ItemIn elements.
Path Element
Procurement applications put Path elements in the cXML header level of each of the
orders. Procurement applications should not include the identical Path element in any
of the ItemOut elements in an OrderRequest.
Credentials
Because commerce network hubs are responsible for routing OrderRequest documents
to the next node in the path, the Sender credential is always the network hub credential
when received by the next node. The preceding node (most recent originator) can
always be found by examining the From Credential list or, the Path for the most recent
Router node if the Router node doesn’t modify the From element. In addition, the
type="marketplace" credential must be one of the router nodes in the path. A From
credential list with no type="marketplace" credential implies that the identical node is the
originating procurement application.
6 Path Routing
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Network Hub</UserAgent>
</Sender>
<Path>
<Node type="route">
6 Path Routing
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
</Credential>
</Node>
<Node type="copy">
<Credential domain="NetworkId">
<Identity>AN01000000111</Identity>
</Credential>
</Node>
<Node type="route">
6 Path Routing
<Credential domain="NetworkId">
<Identity>AN01000000233</Identity>
</Credential>
</Node>
</Path>
<OriginalDocument payloadID="pay1"/>
</Header>
6 Path Routing
<Header>
<From>
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
</Credential>
<Credential domain="NetworkId" type="marketplace">
<Identity>AN01000000233</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId" type="marketplace">
<Identity>AN01000000233</Identity>
</Credential>
<Credential domain="DUNS">
<Identity>942888711</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
6 Path Routing
<Identity>AN01000000001</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Network Hub</UserAgent>
</Sender>
<Path>
<Node type="route">
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
</Credential>
</Node>
<Node type="copy">
<Credential domain="NetworkId">
<Identity>AN01000000111</Identity>
</Credential>
</Node>
<Node type="route">
<Credential domain="NetworkId">
<Identity>AN01000000233</Identity>
</Credential>
</Node>
</Path>
<OriginalDocument payloadID="pay1"/>
</Header>
PunchOutSetupRequest
Procurement applications must include the same path information in the ItemOut
elements for any subsequent edit or inspect PunchOut sessions.
Procurement applications must not perform any item grouping according to the Path
element during PunchOut sessions.
6 Path Routing
CopyRequest
Organizations that want to receive copies of purchase orders, but that are not the
primary recipients, are called copy organizations. They receive copies of purchase
orders as cXML documents within CopyRequest attachments sent by commerce
network hubs.
6 Path Routing
Copy organizations must add the CopyRequest transaction to their cXML profile. When
the commerce network hub receives a purchase order containing path routing copy
information, it first looks up the copy organization's CopyRequest URL in the
organization’s cXML profile. It then sends the attached document to the copy
organization.
Note that the use of CopyRequest attachments differs from previous implementations of
CopyRequest, in which cXML documents were contained as internal elements within
6 Path Routing
CopyRequest/cXML. In cXML 1.2.011, the use of the cXML element as a child of
copyRequest is deprecated. Instead, use the cXMLAttachment element to attach another
cXML document, whether or not it contains attachments itself. For more information
about attachments, see “Attachments” on page 33.
6 Path Routing
--mime-boundary
Content-Type: text/xml; charset=UTF-8
Content-ID: <[email protected]>
[Other headers]
</Credential>
</To>
<Sender>
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Sender Application</UserAgent>
</Sender>
</Header>
<Request deploymentMode="production">
<CopyRequest>
<cXMLAttachment>
<Attachment>
<URL>cid:[email protected]</URL>
</Attachment>
</cXMLAttachment>
</CopyRequest>
</Request>
</cXML>
--mime-boundary
Content-Type: text/xml; charset=UTF-8
Content-ID: <[email protected]>
[Other headers]
[Forwarded cXML]
--mime-boundary--
Buying organizations use cXML payment documents to pay suppliers for provided
products or services. cXML payment documents provides immediate access to
payment scheduling information, allowing more accurate forecasting and scheduling
of payables and receivables.
• Overview of Payment
• PaymentProposalRequest
• PaymentRemittanceRequest
• PaymentRemittanceStatusUpdateRequest
• Example Payment Documents
7 Payment
Overview of Payment
cXML automates the payment process through scheduled payment and remittance
advice documents. These documents allow trading partners to track and process
payments. The cXML payment process includes scheduled payments (plans for
payment), discounts, creating and sending payments regardless of where payments
are made, and ensuring that payments have been received.
7 Payment
The PaymentProposalRequest document is a scheduled payment. It allows buying
organizations to specify payment due dates and discounts.
The PaymentRemittance document lists payment transaction details for a wide variety of
business scenarios, including standard invoices, credit memos, and debit memos.
7 Payment
When a payment is made, the organization making the payment also creates an
associated remittance advice document. Remittance advice documents are summary
statements that provides details about payments that have been made. A typical
remittance advice includes the payment method used, bank information, discount
amount, amount paid, and a list of payables included in the payment.
PaymentRemittance DTD
The cXML standard uses multiple DTDs to optimize the performance of validating
parsers. The payment transactions described in this chapter are defined in a DTD
named PaymentRemittance.dtd, available at:
http://xml.cXML.org/schemas/cXML/<version>/PaymentRemittance.dtd
PaymentProposalRequest
cXML PaymentProposalRequest documents represent scheduled payments. They list
payment amounts and dates and can be for information only or for triggering
payment.
7 Payment
PaymentProposalRequest has the following attributes:
PayableInfo
A reference to the payable document, such as an invoice, order, or master agreement.
PayableInfo is known to both buyer and supplier. For example, the PayableInfo for an
invoice would be the PayableInvoiceInfo.
The following example shows the structure of a minimum valid PayableInfo element:
<PayableInfo>
7 Payment
<PayableInvoiceInfo>
<InvoiceIDReference or InvoiceIDInfo>
.....
</InvoiceIDReference or InvoiceIDInfo>
</PayableInvoiceInfo>
</PayableInfo>
The following example shows the structure of a PayableInfo element that includes an
optional PayableOrderInfo:
7 Payment
<PayableInfo>
<PayableInvoiceInfo>
<InvoiceIDReference or InvoiceIDInfo>
<PayableOrderInfo>
<OrderIDInfo>
.....
</OrderIDInfo>
</PayableOrderInfo>
</InvoiceIDReference or InvoiceIDInfo>
7 Payment
</PayableInvoiceInfo>
</PayableInfo>
PayableInvoiceInfo
InvoiceReference
InvoiceIDInfo
PayableOrderInfo
7 Payment
PayableOrderInfo has no attributes.
OrderReference
OrderIDInfo
PayableMasterAgreementInfo
PaymentMethod
The method of payment. Must be provided if isNetworkPayment is true.
Buying organizations use this element to identify the method for a payment.
7 Payment
The type of the payment method:
ach—Automated Clearing House
cash—Cash payment
check—Check payment
creditCard—Credit card or PCard payment
type
debitCard—Debit card payment
draft—A written payment order, directing a second party to pay
a third party
7 Payment
wire—Wire transfer
other—Other, not defined in cXML
Description
The description of the payment method. Description is mandatory if the type is set to
“other.” The ShortName element in Description must indicate the name of the payment
method.
7 Payment
ShortName
A short string describing something in fewer characters than the entire Description. Use
the ShortName element when limited space is available. For example, a table of
elements might show the ShortName. A linked “details” view would show the entire
Description. Without a ShortName, the user interface must default to a truncation of
Description.
This element does not require an xml:lang attribute because it appears only within a
Description element. The language of the ShortName must match that of the surrounding
Description.
PaymentPartner
Specifies all partners involved in the payment, such as payer, payee, originating bank,
receiving bank, and remitTo. The number of payment partners required depends on
the payment method used. PaymentPartner has no attributes.
Contact
Contact elements with role payer and payee are always required. If the payment method
indicates a bank transfer, then Contact elements with role originatingBank and
receivingBank are required.
7 Payment
The remitTo element must be provided if isNetworkPayment is true.
IdReference
IdReference is
mandatory for all transactions that involve electronic payments. It is
optional only for non-electronic payment methods, such as check or cash.
7 Payment
the Contact
isoBicID—ISO BIC ID (Bank Identifier Code) as specified in ISO 9362.
The Bank Identifier Code (BIC) is a universal method of identifying
financial institutions. The BIC consists of 8 or 11 characters,
comprising a bank code (4 characters), a country code (2 characters),
a location code (2 characters) and an optional branch code (3
characters)
swiftID—SWIFT ID (Society for Worldwide Interbank Financial
Telecommunications) identification number
bankBranchID—The identification number of the bank branch
7 Payment
The value supplierTaxID is deprecated and will be treated as federalTaxID.
7 Payment
Value Description
bankBranchID The bank branch ID
The following table illustrates some valid role - domain value combinations for Contact
and IdReference:
Contact@role IdReference@domain
payer bankAccountID
ibanID
payee bankAccountID
ibanID
originatingBank abaRoutingNumber
bankNationalID
isoBicID
swiftID
bankBranchID (optional)
7 Payment
receivingBank abaRoutingNumber
bankNationalID
isoBicID
swiftID
bankBranchID (optional)
originatingCorrespo abaRoutingNumber
ndentBank isoBicID
swiftID
receivingCorrespon abaRoutingNumber
dentBank isoBicID
swiftID
intermediaryBank abaRoutingNumber
isoBicID
swiftID
Creator
The creator of this IdReference, such as United Parcel Service or Bank of America.
Description
Text description of the IdReference. This is especially useful when the Creator value is
not immediately understood by the reader.
PCard
Specifies purchasing card information, such as card number and expiration date. This
7 Payment
element allows buying organizations to charge PCards after they approve invoices. If
you specify a PCard, use Contact with role="payer".
Contact
(Deprecated) Use the PaymentPartner element and the remitTo role to specify this
information.
7 Payment
GrossAmount
The gross payment amount.
DiscountAmount
The discount amount.
7 Payment
AdjustAmount
The total of various adjustment amounts. The adjustment amount can be positive
indicating a decrease in payment amount, or negative indicating an increase in
payment amount (such as for late charges or penalties).
NetAmount
The net amount.
NetAmount = GrossAmount - DiscountAmount - AjustmentAmount
If NetAmount is negative, it indicates a credit to the buyer. In this case, except for
paymentProposalID, operation, and PayableInfo, NetAmount, all other attributes and sub-
elements of PaymentProposalRequest are ignored.
Comments
Contains buyer’s comments when the status is changed. For example, if the status is
changed to hold, the buyer can enter a reason which would be included in this field.
Only update, hold, and delete operations have comments.
PaymentRemittanceRequest
The PaymentRemittanceRequest document is analogous to remittance detail advice for
payment or remittance.
7 Payment
The following diagram shows the structure of the PaymentRemittanceRequest element:
7 Payment
The following example shows the structure of the PaymentRemittanceRequest element:
<PaymentRemittanceRequest>
<PaymentRemittanceRequestHeader>
header information
</PaymentRemittanceRequestHeader>
<PaymentRemittanceSummary>
summary-level remittance information
</PaymentRemittanceSummary>
7 Payment
<RemittanceDetail>
detail-level remittance information
</RemittanceDetail>
</PaymentRemittanceRequest>
PaymentRemittanceRequestHeader
The PaymentRemittanceRequestHeader element defines header information that applies to
the entire payment or remittance.
ShortName
Description
PaymentMethod
Contact
PaymentRemittanceRequestHeader PaymentPartner IdReference
PCard
PaymentReferenceInfo PaymentReference
DocumentReference
Comments
Extrinsic
PaymentMethod
Identifies the method for a payment. For more information, see “PaymentMethod” on
page 171.
7 Payment
PaymentPartner
PaymentReferenceInfo
PaymentReference
DocumentReference
7 Payment
The DocumentReference element of a PaymentReference is a container for the
payloadID attribute, which refers to a prior PaymentRemittanceRequest.
PaymentIDInfo
7 Payment
The PaymentIDInfo of a PaymentReference refers to the unique identifier for this payment
in the buying organization’s system. PaymentIDInfo is a container for
paymentRemittanceID and paymentDate attributes. 7 Payment
Comments
Extrinsic
PaymentRemittanceSummary
The PaymentRemittanceSummary element defines summary information of a
PaymentRemittanceRequest. Each money amount in a PaymentRemittanceSummary element
is expressed as a flat amount with currency.
NetAmount
The NetAmount element defines the total net payment amount. NetAmount should satisfy
the following equation:
GrossAmount
DiscountAmount
7 Payment
AdjustmentAmount
RemittanceDetail
The RemittanceDetail element defines the remittance detail of a specific payable that has
been paid. Each money amount in a RemittanceDetail element is expressed as a flat
amount with currency.
7 Payment
PayableInfo
PayableInvoiceInfo
7 Payment
InvoiceReference or InvoiceIDInfo,
and might contain either PayableOrderInfo or
PayableMasterAgreementInfo.
InvoiceReference
InvoiceIDInfo
PayableOrderInfo
OrderReference
OrderIDInfo
PayableMasterAgreementInfo
NetAmount
GrossAmount
DiscountAmount
7 Payment
AdjustmentAmount
The total of various adjustment amounts for this payable, if any. The adjustment
amount can be positive, indicating a decrease in payment amount, or negative,
indicating an increase in payment amount. For example, a negative AdjustmentAmount
might be used to account for late charges or other penalties.
PaymentRemittanceStatusUpdateRequest
The PaymentRemittanceStatusUpdateRequest document provides status information for a
payment remittance. Buying organizations send PaymentRemittanceStatusUpdateRequest
documents to suppliers to inform suppliers of the status of their payables.
<Request>
<PaymentRemittanceStatusUpdateRequest>
<DocumentReference>
.....
</DocumentReference>
<PaymentRemittanceStatus>
....
</PaymentRemittanceStatus>
7 Payment
</PaymentRemittanceStatusUpdateRequest>
<Request>
DocumentReference
The DocumentReference element is a container for payloadID, which associates a status
update with a particular PaymentRemittanceRequest document. DocumentReference repeats
a required attribute of the earlier document and adds one optional identifier generated
by the supplier. For example:
7 Payment
<DocumentReference payloadID="0c300508b7863dcclb_14999"/>
PaymentRemittanceStatus
Defines the status for a payment transaction specified by an existing
PaymentRemittanceRequest. PaymentRemittanceStatus has the following attributes:
Value Description
paid The payment transaction was completed successfully.
failed The payment transaction failed. Under certain conditions, a
PaymentRemittance of type “failed” can be resubmitted by the
buying organization.
canceled The payment transaction was canceled.
For a discussion of the common Status element, see “Status” on page 47.
PaymentRemittanceStatusDetail
xml:lang The language in which the text attribute and element content
are written.
• PaymentProposalRequest Example
7 Payment
• PaymentRemittanceRequest Example
• PaymentRemittanceStatusUpdateRequest Example
PaymentProposalRequest Example
The following scheduled payment is for an ACH payment.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/
PaymentRemittance.dtd">
<cXML payloadID="[email protected]" timestamp="2005-04-20T23:59:45-07:00">
<Header>
<From>
<Credential domain=”NetworkId”>
<Identity>AN99123456789</Identity>
</Credential>
</From>
<To>
<Credential domain=”NetworkId”>
<Identity>AN99987654321</Identity>
</Credential>
</To>
<Sender>
<Credential domain=”NetworkId”>
<Identity>AN99123456789</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
7 Payment
<UserAgent>Procurement Application 1.0</UserAgent>
</Sender>
</Header>
<Request>
<PaymentProposalRequest
paymentProposalID="proposal123"
operation="new"
paymentDate="2005-07-20T23:59:20-07:00">
<PayableInfo>
<PayableInvoiceInfo>
7 Payment
<InvoiceReference invoiceID="ABC">
<DocumentReference payloadID="25510.10.81.231"/>
</InvoiceReference>
<PayableOrderInfo>
<OrderReference orderID="DEF">
<DocumentReference payloadID="25510.10.81.002"/>
</OrderReference>
</PayableOrderInfo>
</PayableInvoiceInfo>
</PayableInfo>
7 Payment
<PaymentMethod type="ach"/>
PaymentRemittanceRequest Example
This example shows a minimum valid PaymentRemittanceRequest.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/
PaymentRemittance.dtd">
<cXML xml:lang="en-US" timestamp="2004-03-10T14:20:53-08:00" payloadID="PR-031004-01">
<Header>
<From>
<Credential domain=”NetworkId”>
<Identity>AN99123456789</Identity>
</Credential>
</From>
7 Payment
<To>
<Credential domain=”NetworkId”>
<Identity>AN99987654321</Identity>
</Credential>
</To>
<Sender>
<Credential domain=”NetworkId”>
<Identity>AN99123456789</Identity>
</Credential>
<UserAgent>Procurement Application 1.0</UserAgent>
</Sender>
</Header>
<Request deploymentMode="production">
<PaymentRemittanceRequest>
<PaymentRemittanceRequestHeader paymentDate="2004-10-10T00:00:00-08:00"
paymentReferenceNumber="ACH123456789" paymentRemittanceID="PR-031204-01">
<PaymentMethod type="ach"></PaymentMethod>
<PaymentPartner>
<Contact role="payer">
<Name xml:lang="en">buyer</Name>
<PostalAddress>
<Street>100 1st Street</Street>
<City>Anywhere</City>
<State>CA</State>
<PostalCode>94089</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
</Contact>
</PaymentPartner>
7 Payment
<PaymentPartner>
<Contact role="payee">
<Name xml:lang="en">Supplier</Name>
<PostalAddress>
<Street>100 Main Street</Street>
<City>Anywhere</City>
<State>CA</State>
<PostalCode>94089</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
7 Payment
</Contact>
</PaymentPartner>
<PaymentPartner>
<Contact role="originatingBank">
<Name xml:lang="en">Moose Credit Union</Name>
<PostalAddress>
<Street>100 Elk Drive</Street>
<City>Mooseville</City>
<State>CA</State>
<PostalCode>94087</PostalCode>
7 Payment
</PostalAddress>
</Contact>
<IdReference domain="abaRoutingNumber" identifier="234567890"></IdReference>
</PaymentPartner>
<PaymentPartner>
<Contact role="receivingBank">
<Name xml:lang="en">Gold Rush Bank</Name>
<PostalAddress>
<Street>100 Bret Harte Road</Street>
<City>Gold Rush</City>
<State>CA</State>
<PostalCode>97123</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
</Contact>
<IdReference domain="abaRoutingNumber" identifier="678902345"></IdReference>
</PaymentPartner>
</PaymentRemittanceRequestHeader>
<PaymentRemittanceSummary>
<NetAmount>
<Money currency="USD">2.00</Money>
</NetAmount>
<GrossAmount>
<Money currency="USD">2.85</Money>
</GrossAmount>
<DiscountAmount>
<Money currency="USD">0.35</Money>
</DiscountAmount>
<AdjustmentAmount>
<Money currency="USD">0.50</Money>
</AdjustmentAmount>
</PaymentRemittanceSummary>
<RemittanceDetail lineNumber="1">
<PayableInfo>
<PayableInvoiceInfo>
<InvoiceIDInfo invoiceID="INV-031204-01"></InvoiceIDInfo>
<PayableOrderInfo>
<OrderIDInfo orderID="P0-031204-01"></OrderIDInfo>
</PayableOrderInfo>
</PayableInvoiceInfo>
</PayableInfo>
<NetAmount>
<Money currency="USD">2.00</Money>
</NetAmount>
<GrossAmount>
<Money currency="USD">2.85</Money>
</GrossAmount>
<DiscountAmount>
<Money currency="USD">0.35</Money>
</DiscountAmount>
7 Payment
<AdjustmentAmount>
<Money currency="USD">0.50</Money>
</AdjustmentAmount>
</RemittanceDetail>
</PaymentRemittanceRequest>
</Request>
</cXML>
PaymentRemittanceStatusUpdateRequest Example
This example shows a PaymentRemittanceStatusUpdateRequest sent from a buyer to a
supplier:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/
PaymentRemittance.dtd">
<cXML payloadID="[email protected]" timestamp="2003-04-
20T23:59:45-07:00">
<Header>
<From>
<Credential domain=”NetworkId”>
<Identity>AN99123456789</Identity>
</Credential>
</From>
<To>
<Credential domain=”NetworkId”>
<Identity>AN99987654321</Identity>
7 Payment
</Credential>
</To>
<Sender>
<Credential domain=”NetworkId”>
<Identity>Procurement Application 1.0</Identity>
</Credential>
</Sender>
</Header>
<Request deploymentMode="production">
<PaymentRemittanceStatusUpdateRequest>
7 Payment
<DocumentReference
payloadID="[email protected]">
</DocumentReference>
<PaymentRemittanceStatus type="canceled"
paymentReferenceNumber="PaymentRefNumber">1234</
</PaymentRemittanceStatus>
</PaymentRemittanceStatusUpdateRequest>
</Request>
</cXML>
7 Payment
8 TimeCard
Transaction
Timecards are used for placing orders related to temporary labor and contractors.
They can be generated and sent by either the buyer or the supplier, depending upon
which system captures the timecard information.
TimeCard Requests
Because of the two-way nature of timecards, there are two requests that involve the
TimeCard element: TimeCardRequest and TimeCardInfoRequest.
8 TimeCard
Transaction
which are typically sent only by suppliers.
8 TimeCard
Transaction
8 TimeCard
Transaction
TimeCard Element
The TimeCard element is used to capture the hours worked by a contractor or other
temporary laborer, and has the following structure:
type Possible values are new, update, and delete. The value
defaults to new, unless the original timecard is updated.
Possible values are submitted, approved, denied. The
status
default value is submitted.
Represents the unique identifier for this timecard in the
timeCardID
buyer and supplier systems. Required.
8 TimeCard
Transaction
OrderInfo
The OrderInfo element is used to reference the order. One timecard can reference only
one order.
Contractor
8 TimeCard
Transaction
The Contractor element is the definition of a contractor used in the context of
temporary labor.
ContractorIdentifier
ContractorIdentifier uniquely identifies the contractor in both the buyer and supplier
systems, and is agreed upon by the buyer and the supplier prior to sending out orders
or timecards. The ContractorIdentifier element contains the following attribute:
Contact
8 TimeCard
Transaction
ReportedTime
The ReportedTime element captures the line items for the timecard.
Period
Period denotes the period of time for which the timecard is being submitted.
8 TimeCard
Transaction
8 TimeCard
Transaction
TimeCardTimeInterval
TimeRange
The TimeRange element defines a time range in which the start and end dates can be
unbounded.
8 TimeCard
Transaction
The TimeRange element contains the following attributes:
8 TimeCard
Transaction
SubmitterInfo
The SubmitterInfo element contains information about the person submitting the
timecard.
Contact
If the Contact element is absent, then it is assumed that the contractor is also the
submitter.
ApprovalInfo
8 TimeCard
Transaction
The ApprovalInfo element includes information about the approver of the timecard. This
information is sent by the supplier for informational purposes only, and can include
all the approvers in the chain. There can be multiple approvals because many people
might need to approve the timecard in question.
8 TimeCard
Transaction
DocumentReference
DocumentReference is used on an update operation to refer to a previous TimeCardRequest
or TimeCardInfoRequest.
8 TimeCard
Transaction
TimeCard Examples
The following example shows a TimeCardInfoRequest sent upon submission to the
supplier:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/Fulfill.dtd">
<cXML xml:lang="en-US"
payloadID=" [email protected]"
timestamp="2003-10-01T23:00:06-08:00">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN0100023456</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity> AN0100023457</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity> AN0100023456</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Our Procurement Application 2.0</UserAgent>
</Sender>
</Header>
<Request>
<TimeCardInfoRequest>
<TimeCard type="new" status="submitted" timeCardID="TC101">
<OrderInfo>
<OrderIDInfo orderID="PO12" orderDate="2003-07-22T08:00:00-08:00"/>
</OrderInfo>
<Contractor>
<ContractorIdentifier domain="supplierReferenceID">Doe8610</ContractorIdentifier>
<Contact>
<Name xml:lang="en">John Doe</Name>
</Contact>
</Contractor>
<ReportedTime>
<Period startDate="2003-09-22T08:00:00-08:00"
endDate="2003-09-26T18:00:00-08:00"/>
<TimeCardTimeInterval duration="PT8H" payCode="Regular">
<TimeRange startDate="2003-09-22T08:00:00-08:00"
endDate="2003-09-22T18:00:00-08:00"/>
</TimeCardTimeInterval>
8 TimeCard
Transaction
<TimeCardTimeInterval duration="PT2H"
payCode="Mealbreak" isNonBillable="yes">
<TimeRange startDate="2003-09-22T012:00:00-08:00"
endDate="2003-09-22T14:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT2H" payCode="Overtime">
<TimeRange startDate="2003-09-22T18:00:00-08:00"
endDate="2003-09-22T20:00:00-08:00"/>
</TimeCardTimeInterval>
8 TimeCard
Transaction
<TimeCardTimeInterval duration="PT8H" payCode="Regular">
<TimeRange startDate="2003-09-23T08:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT8H" payCode="Regular">
<TimeRange startDate="2003-09-24T08:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT8H" payCode="Regular">
<TimeRange startDate="2003-09-25T08:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT8H" payCode="Regular">
<TimeRange startDate="2003-09-26T08:00:00-08:00"/>
</TimeCardTimeInterval>
</ReportedTime>
<SubmitterInfo submittedDate="2003-10-01T08:00:00-08:00">
<Contact>
<Name xml:lang="en">John Doe</Name>
</Contact>
</SubmitterInfo>
</TimeCard>
</TimeCardInfoRequest>
8 TimeCard
Transaction
</Request>
</cXML>
8 TimeCard
Transaction
timestamp="2003-10-01T23:00:06-08:00">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN0100023456</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity> AN0100023457</Identity>
8 TimeCard
Transaction
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity> AN0100023456</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Suppliers Time Card Application 5.0</UserAgent>
</Sender>
</Header>
<Request>
<TimeCardInfoRequest>
<TimeCard type="update" status="approved" timeCardID="TC101">
<OrderInfo>
<OrderIDInfo orderID="PO123" orderDate="2003-07-22T08:00:00-08:00"/>
</OrderInfo>
<Contractor>
<ContractorIdentifier domain="supplierReferenceID">Doe8610</ContractorIdentifier>
<Contact>
<Name xml:lang="en">John Doe</Name>
</Contact>
</Contractor>
<ReportedTime>
<Period startDate="2003-09-22T08:00:00-08:00"
endDate="2003-09-26T18:00:00-08:00"/>
<TimeCardTimeInterval duration="PT8H" payCode="Regular">
<TimeRange startDate="2003-09-22T08:00:00-08:00"
endDate="2003-09-22T18:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT2H"
payCode="Mealbreak" isNonBillable="yes">
<TimeRange startDate="2003-09-22T012:00:00-08:00"
endDate="2003-09-22T14:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT2H" payCode="Overtime" >
<TimeRange startDate="2003-09-22T18:00:00-08:00"
endDate="2003-09-22T20:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT8H" payCode="Regular" >
<TimeRange startDate="2003-09-23T08:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT8H" payCode="Regular" >
<TimeRange startDate="2003-09-24T08:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT8H" payCode="Regular" >
<TimeRange startDate="2003-09-25T08:00:00-08:00"/>
</TimeCardTimeInterval>
<TimeCardTimeInterval duration="PT8H" payCode="Regular" >
<TimeRange startDate="2003-09-26T08:00:00-08:00"/>
</TimeCardTimeInterval>
</ReportedTime>
<SubmitterInfo submittedDate="2003-10-01T08:00:00-08:00">
8 TimeCard
Transaction
<Contact>
<Name xml:lang="en">John Doe</Name>
</Contact>
</SubmitterInfo>
<ApprovalInfo approvedDate="2003-10-02T08:00:00-08:00">
<Contact>
<Name xml:lang="en">John Doe</Name>
</Contact>
</ApprovalInfo>
8 TimeCard
Transaction
<DocumentReference payloadID="[email protected]"/>
</TimeCard>
</TimeCardInfoRequest>
</Request>
</cXML>
8 TimeCard
Transaction
8 TimeCard
Transaction
8 TimeCard
Transaction
9 Master Agreements
cXML supports the transmission of Master Agreement documents, which are
contracts between trading partners.
9 Master Agreements
• Overview of Master Agreements
• MasterAgreementRequest
9 Master Agreements
with suppliers. They represent a common mechanism for managing supplier and
budget commitments, and they enable buyers to negotiate better discounts by basing
the discounts on future purchases, while enabling suppliers to more accurately
forecast demand.
9 Master Agreements
an order against a contract is called a release.
MasterAgreementRequest
The MasterAgreementRequest document defines the Master Agreement created by
the buying organization. It specifies beginning and end dates, and the committed
9 Master Agreements
maximum and minimum values of the agreement. It also lists maximum and
minimum values and quantities for individual items.
<URL>www.foo.com</URL>
</ItemDetail>
<Shipping trackingDomain="FedEx" trackingId="1234567890">
<Money currency="USD">2.5</Money>
<Description xml:lang="en-us">FedEx 2-day</Description>
</Shipping>
<Comments xml:lang="en-US">Any well formed XML</Comments>
9 Master Agreements
</ItemOut>
</AgreementItemOut>
</MasterAgreementRequest>
MasterAgreementRequestHeader Element
The MasterAgreementRequestHeader contains information about the Master Agreement
common to all contained items.
9 Master Agreements
MasterAgreementHeader has the following attributes:
The date and time the agreement request was created. This is
agreementDate different from the effective and expiration date of the agreement.
type Specifies whether the agreement refers to a value or quantity.
Specifies the date the agreement is available for ordering or
effectiveDate
releases.
expirationDate Specifies the date the agreement is no longer available
9 Master Agreements
Specifies the type of the agreement request. Can be “new”,
“update” or “delete”. Defaults to "new". The "delete" operation is
operation used to cancel an existing agreement. The delete request
should be an exact replica of the original request.
parentAgreementPa PayloadID for the corresponding parent document from which
yloadID this agreement is derived. Optional.
agreementID The procurement system agreementID for this request.
9 Master Agreements
(Optional) Contains the maximum amount for all line items in the
MaxAmount
Master Agreement.
(Optional) Contains the committed amount for all line items on
MinAmount
the Master Agreement.
AgreementItemOut Element
The AgreementItemOut element specifies the requirements of a particular line item that
is part of the Master Agreement contract.
cXML allows entities to set the status of purchase orders and line items within them.
• Overview of Status
10 Later Status
• StatusUpdateRequest
Changes
• ConfirmationRequest
• ShipNoticeRequest
Overview of Status
10 Later Status
After the OrderRequest transaction has completed, suppliers and intermediate servers
Changes
might need to communicate additional information back to the buying organization.
In addition, after a buying organization receives an invoice, it might need to
communicate back to the supplier about invoice status. The transactions described in
this chapter are used for that purpose. These transactions share some common
semantics and elements.
10 Later Status
returned document contains a nearly empty Response (only a Status). Each returned
Changes
document has the form:
<cXML payloadID="[email protected]"
timestamp="2000-01-12T18:39:09-08:00" xml:lang="en-US">
<Response>
<Status code="200" text="OK"/>
</Response>
</cXML>
10 Later Status
Changes
StatusUpdateRequest
This transaction informs an earlier node about changes in the processing status of an
order or an invoice.
This request updates the processing status of a single OrderRequest document. For
example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US"
payloadID="[email protected]"
timestamp="2000-01-08T23:00:06-08:00">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN00000123</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN00000456</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN00000123</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Supplier’s Super Order Processor</UserAgent>
</Sender>
</Header>
10 Later Status
Changes
<Request>
<StatusUpdateRequest>
<DocumentReference
payloadID="0c300508b7863dcclb_14999"/>
<Status code="200" text="OK" xml:lang="en-US">Forwarded
to supplier</Status>
</StatusUpdateRequest>
</Request>
</cXML>
This request contains only an DocumentReference and a Status element. The Status can
communicate a later transport error encountered by an intermediate hub. The
semantics of this element are identical to a Status that might have been returned in the
initial HTTP response to an OrderRequest document.
The 200/OK code is especially important when documents are stored and forwarded.
This code indicates that a supplier has begun processing the OrderRequest or a hub has
10 Later Status
forwarded the document. The recipient should expect no further StatusUpdateRequest
Changes
documents after 200/OK arrives.
Suppliers and hubs utilizing the StatusUpdate transaction must return code 201/
Accepted when an OrderRequest is queued for later processing. After it sends 200/OK
(in the immediate Response to an OrderRequest or a later StatusUpdateRequest), the server
should send no further StatusUpdate transactions for that order. Errors later in
processing might lead to exceptions to this rule.
10 Later Status
Changes
DocumentReference Element
The DocumentReference element associates a status update with a particular
OrderRequest or InvoiceDetailRequest document. It repeats a required attribute of the
earlier document and adds one optional identifier generated by the supplier. For
example:
<DocumentReference
10 Later Status
payloadID="0c300508b7863dcclb_14999"/>
Changes
DocumentReference contains no elements, but has the following attribute:
PaymentStatus Element
The PaymentStatus element contains the status of a PCard transaction. The status
update includes information such as the success of the transaction, transaction ID,
authorization ID, order ID, total, tax, shipping information, and the time stamp of the
original submission.
The PaymentStatus element contains the required PCard and Total element, and
optionally Shipping, Tax, and Extrinsic elements.
The PCard element contains two attributes that specify the number of the PCard and its
expiration date.
10 Later Status
Changes
PaymentStatus has the following attributes
10 Later Status
buyer.
Changes
Assigned to the transaction by the payment processing
transactionID
gateway.
The authorization code for the transaction provided by the
authorizationID
bank.
SourcingStatus Element
10 Later Status
The SourcingStatus element provides update information for a RFQ sourcing
transaction, PunchOutSetupRequest document with operation=”source”.
Changes
<StatusUpdateRequest>
<DocumentReference payloadID="123345678.RFQID:1234456787" />
<Status code="200" text="OK">Approve Request</Status>
<SourcingStatus action="approve" xml:lang="en"/>
</StatusUpdateRequest>
The action attribute identifies the update type for the transaction. Can be “approve”,
10 Later Status
“cancel”, or “deny”. The body of the SourcingStatus element can contain human-
Changes
readable information about the new state of the RFQ.
InvoiceStatus Element
When using StatusUpdateRequest for invoices, include the InvoiceStatus element.
<StatusUpdateRequest>
10 Later Status
</InvoiceStatus">
</StatusUpdateRequest>
InvoiceIDInfo Element
PartialAmount Element
10 Later Status
Changes
ConfirmationRequest
This transaction provides detailed status updates on a specific Order Request. It
extends the simple acknowledgment of an order, provided by StatusUpdateRequest, to a
more detailed item level confirmation and ship notification.
Note: The DTD for this transaction is contained in Fulfill.dtd rather than
cXML.dtd.
No specific Response document is required for this transaction. Servers must respond
to a ConfirmationRequest with a generic Response document.
A document is one of the following types, specified by the type attribute of the
ConfirmationHeader element: “accept,” “allDetail,” “detail,” “backordered,” “except,” “reject,”
“requestToPay,” and “replace.” With a type of “detail”, you can update portions of a
10 Later Status
purchase order, such as prices, quantities, and delivery dates, reject portions, and add
tax and shipping information. Only the line items mentioned are changed. With a type
Changes
of “allDetail”, you can update all information of specified line items without rejecting
or accepting the order. You can apply the confirmation to the entire order request
using the types “accept”, “reject”, and “except”. “allDetail” and “detail” update individual
lines, they do not accept or reject the entire order.
10 Later Status
transaction against the PCard listed in the purchase order and return the status of the
Changes
transaction. The network hub then sends the transaction status back to the supplier in
a StatusUpdateRequest document.
10 Later Status
point to this document through its DocumentReference element. However, the
Changes
confirmID makes the update much more explicit.-->
<ConfirmationHeader type="accept" noticeDate="2000-10-12T18:39:09-08:00"
confirmID="C999-234" invoiceID="I1010-10-12">
<Shipping>
<Money currency="USD">2.5</Money>
<Description xml:lang="en-CA">FedEx 2-day</Description>
</Shipping>
<Tax>
10 Later Status
<Money currency="USD">0.19</Money>
<Description xml:lang="en-CA">CA Sales Tax</Description>
Changes
</Tax>
<Contact role="shipFrom">
<Name xml:lang="en-CA">Workchairs, Vancouver</Name>
<PostalAddress>
<Street>432 Lake Drive</Street>
<City>Vancouver</City>
<State>BC</State>
<PostalCode>B3C 2G4</PostalCode>
<Country isoCountryCode="CA">Canada</Country>
</PostalAddress>
<Phone>
<TelephoneNumber>
<CountryCode isoCountryCode="CA">1</CountryCode>
<AreaOrCityCode>201</AreaOrCityCode>
<Number>9211132</Number>
</TelephoneNumber>
</Phone>
</Contact>
<Comments xml:lang="en-CA">Look's great</Comments>
</ConfirmationHeader>
<!-- The orderID and orderDate attributes are not required in the
OrderReference element. -->
<OrderReference orderID="DO1234">
<DocumentReference payloadID="[email protected]" />
</OrderReference>
</ConfirmationRequest>
Multiple “detail” ConfirmationRequest documents can refer to a single purchase order, but
they must not refer to common line items.
While suppliers send multiple confirmations for a purchase order, each confirmation
must mention a line item only once. In addition, a line item must not be mentioned in
more than one confirmation request. Multiple confirmations are allowed, and
sensible, only for “allDetail” or “detail”. Only one confirmation per order is allowed for
“accept”, “except”, or “reject”. When a confirmation with one of these types arrives, the
receiving system must discard all previous confirmations for the purchase order.
10 Later Status
Changes
ConfirmationItem elements can appear in any order within the ConfirmationRequest
document. However, listing the lineNumber elements in ascending order is preferred.
Again, no line item can appear more than once within a ConfirmationRequest element.
OrderReference Element
The OrderReference element provides a clear reference to a purchase order. While the
contained DocumentReference provides an unambiguous reference, the additional
attributes of the OrderReference allow the ConfirmationRequest and ShipNoticeRequest to be
viewed independently. The OrderReference contains a DocumentReference element (see
page 226) and two attributes: orderID and orderDate.
orderID Attribute
Specifies the buyer system orderID for the confirmation, that is, the PO number. When
10 Later Status
used, it must be copied directly from the referenced OrderRequest OrderRequestHeader
Changes
element.
orderDate Attribute
Specifies the date and time the OrderRequest was created. If present, it must be
copied directly from the referenced OrderRequest OrderRequestHeader element.
10 Later Status
ConfirmationHeader Element
Changes
The ConfirmationHeader element contains information that is common to all items
contained in the ConfirmationRequest. It has the following attributes:
• type
• noticeDate
• invoiceID
• operation
10 Later Status
• ConfirmID
Changes
• incoTerms
• Contact
Changes
• Hazard
• Comments
• Extrinsic
If the ConfirmationHeader (see page page 215) is either, “allDetail”, “detail” or “except”, you
can include ConfirmationItem elements to update specific line items from a purchase
order.
10 Later Status
Changes
</Contact>
<Comments xml:lang="en-CA">Look's great, but for the price.</Comments>
</ConfirmationHeader>
<!-- The orderID and orderDate attributes are not required in the OrderReference
element. -->
<OrderReference orderID="DO1234">
<DocumentReference payloadID="[email protected]" />
</OrderReference>
<ConfirmationItem lineNumber="1" quantity="10">
<UnitOfMeasure>EA</UnitOfMeasure>
<ConfirmationStatus quantity="10" type="detail" shipmentDate="2000-10-14"
deliveryDate="2000-10-19">
<UnitOfMeasure>EA</UnitOfMeasure>
<UnitPrice>
<Money currency="USD">1.64</Money>
</UnitPrice>
<Comments xml:lang="en-CA">Very sorry. There's been a slight
(30 cents) price increase for that colour and it will be one day late.
10 Later Status
</Comments>
Changes
</ConfirmationStatus>
</ConfirmationItem>
</ConfirmationRequest>
type Attribute
10 Later Status
accept Accepts the entire order as described in the referenced purchase
Changes
order.
A document of this type can contain ConfirmationItem elements. They
must contain only ConfirmationStatus elements of type="accept".
allDetail Updates only specific line items. Line items not mentioned retain
their current status. Unlike the "detail" type, this type of confirmation
includes all information known by the supplier, whether or not it
differs from the data provided in the original OrderRequest
document.
This confirmation is compatible with current EDI and order entry
10 Later Status
tools, which commonly send buyers a snapshot of an order in
Changes
supplier's systems. Due to the reconciliation issues caused by
confirmations of this type, it is recommended that this type be
considered as a "bridge" strategy for the short term.
This confirmation must contain ConfirmationItem elements and
ConfirmationStatus elements must have types "allDetail", "reject", or
"unknown". Do not include "accept" or "detail" ConfirmationStatus
types because they could conflict.
10 Later Status
Changes
detail Updates individual line items. Line items not mentioned retain their
current states. This document type should include only information
that differs from the information in the purchase order.
Do not include the variations described in an earlier
ConfirmationRequest in later ConfirmationRequest documents that
restore information provided in the purchase order. For example, the
Tax element might appear in the ConfirmationStatus of one
ConfirmationRequest but not in an update to that confirmation. This
signifies that the purchase order contained the correct charge.
This document type must contain ConfirmationItem elements and
ConfirmationStatus elements can have any type except "allDetail".
backordred Sets the entire purchase order to backordered status. The supplier
does not have the items in stock, but will ship them when they are
available.
except Accepts the entire purchase order with exceptions. Line items not
mentioned are as described in the purchase order.
This document type must contain ConfirmationItem elements and
ConfirmationStatus elements can have any type except "allDetail".
reject Rejects the entire purchase order. Specify a reason for the rejection
in the Comments element. This document must not contain
ConfirmationItem elements.
requestToPay Requests the initiation of payment transactions for either the entire
purchase order or some line items.
If there are no ConfirmationItem elements, the payment is against
the total amount of the purchase order, except those being rejected.
If there are ConfirmationItem elements, the payment is against the
specified items and quantities.
This document does not have to describe the complete line item. It
contains "requestToPay" ConfirmationStatus elements for new
payment transactions.
replace Replaces all of the items from the purchase order. This document
includes only "detail" ConfirmationStatus elements, and they must
include an ItemIn element.
If the buyer sends a change order before receiving this type of
OrderConfirmation, the supplier should accept the change order.
noticeDate Attribute
Specifies the date and time the confirmation document was created.
invoiceID Attribute
10 Later Status
Changes
confirmID Attribute
A supplier-specified optional identifier for the document assigned by the supplier. The
attribute is user-visible and secondary to the document's PayloadID.
This value does not vary as a particular confirmation is updated. That is, documents
with operation="update" describing the status of the same items in the same order share a
confirmID with the original ConfirmationRequest with operation="new".
operation Attribute
10 Later Status
This optional attribute specifies whether the confirmation is new, or an update to a
Changes
previous confirmation.
10 Later Status
add additional information learned later. In either case, an "update" document must be
Changes
complete: all data from the original confirmation or a previous update should be
discarded by the recipient.
10 Later Status
confirmations (sending an "update" ConfirmationRequest document describing a
Changes
subset of items in an earlier version), or partial consolidations of confirmations
(sending an "update" ConfirmationRequest document that contains a subset of
information from another confirmation).
A confirmation can not be deleted; the protocol does not include a delete option for
this request. Suppliers must replace incorrect or invalid confirmations with correct
information. A type="unknown" ConfirmationStatus will reset such information to its
original state. This covers the case of an error in accepting or rejecting an item that
has not been researched.
incoTerms Attribute
The incoTerms attribute specifies optional shipping terms defined by the International
Chamber of Commerce. These terms inform the buyer which portion of the shipping
charges are their responsibility. Allowed values include:
DocumentReference Element
The DocumentReference element should appear only when operation is “update” (see
page 217). It should reference the most recent ConfirmationRequest document for
this particular confirmation, usually indicated by a common confirmID. For example,
when a confirmation is created, updated, and then updated again, the final document
10 Later Status
Changes
should contain a DocumentReference referring to the previous ConfirmationRequest
with operation="update". That document, in turn, refers to the original operation="new"
ConfirmationRequest document (see page 217).
Tax and Shipping amounts can be updated and included in the confirmation with new
values without any corresponding line item information.
Total Element
The Total value should match the OrderRequest document value unless a
ConfirmationItem describes a new UnitPrice or quantity. It is not necessary to copy this
information from the OrderRequest document: although permissible, Total, Tax, and
Shipping information should not be included if they match those amounts in the
original order.
10 Later Status
Changes
Contact Element
The Contact element should be used primarily to add new information about an order.
It is not necessary to copy this information from the OrderRequest document.
10 Later Status
Changes
customerService Customer service
sales Sales
shipFrom Starting point for shipments related to this order
shipTo Copies the ShipTo element from the OrderRequest document
payTo Where payment for this order should be sent
billTo Copies the BillTo element from the OrderRequest document
supplierCorporate Supplier at corporate
10 Later Status
Changes
Elements in the Contact list can appear in any order. A contact role must not appear
more than once within a ConfirmationHeader element.
Hazard Element
Elements in the Hazard list can appear in any order. The same hazard should not be
listed more than once in a ConfirmationHeader element. Each hazard listed at this level
10 Later Status
should apply to the entire order or all items mentioned in the confirmation. A
Changes
ConfirmationRequest that updates the status of a single line item should not include
Hazard elements in the ConfirmationItem element. See “Hazard Element” on page 235 for
more information.
Comments Element
The Comments element can contain additional information about the status of the
overall order, or the portion described in this confirmation, such as payment terms,
additional details on shipping terms and clarification of the status. For status
information, terms such as “backordered”, “shipped”, and “invalid” might be
appropriate. All such data are intended for human use.
Extrinsic Element
The Extrinsic element list can be used to insert additional data about the order for
application consumption. These elements can include pre-defined keywords and
values affecting workflow in the receiving system.
Elements in the Extrinsic list can appear in any order. An extrinsic type must not appear
more than once within a ConfirmationHeader element. A type must not be mentioned
both in this list and in a particular ConfirmationStatus element. The ConfirmationHeader
must not contain a default extrinsic value overridden at the lower level.
ConfirmationItem Element
The ConfirmationItem element completely describes the status of a specific line item.
The ConfirmationItem element can contain the following elements: UnitOfMeasure,
ConfirmationStatus, Contact, and Hazard. ConfirmationStatus can occur more than once, and
only Contact is optional.
You can use more than one ConfirmationRequest document to update the status of an
entire order, but only mention a particular line item in one document and in only one
ConfirmationItem within that document.
10 Later Status
Changes
Contact Element
Use Contact elements in the ConfirmationItem to describe contacts specific to the item.
The elements can be in any order. If you specify a particular Contact role, specify it in
the ConfirmationItem or ConfirmationHeader but not both. Do not specify the role more
than once within a ConfirmationItem.
List elements in the Contact list in any order. Do not add a Contact role attribute more
than once within a ConfirmationItem element.
Hazard Element
List elements in the Hazard list in any order. Do not list the same hazard more than
once in a ConfirmationItem. Each hazard listed at this level, in a ConfirmationItem
element, must apply to this specific line item. A ConfirmationRequest that updates the
status of a single line item should not include Hazard elements in the ConfirmationItem
10 Later Status
element.
Changes
ConfirmationStatus Element
The ConfirmationStatus element provides the status of a specific line item or portion
thereof. Quantities at this level must sum to the quantity in the containing
ConfirmationItem. Use a consistent UnitOfMeasure in the ConfirmationItem element and its
contained ConfirmationStatus element. In a substitution, you can use a different
10 Later Status
UnitOfMeasure in the ItemDetail contained within the ItemIn element.
Changes
When accepting or rejecting an item, include only a UnitOfMeasure element in the
ConfirmationStatus element.
Use an ItemIn element only to recommend a substitution. With a substitution, you must
match the quantity of the ItemIn element to that of the containing ConfirmationStatus,
unless the UnitOfMeasure has changed. This requires an ItemDetail element within the
ItemIn element.
10 Later Status
Changes
You can update UnitPrice, Tax and Shipping amounts in the ConfirmationStatus element
without a complete part substitution. It is not necessary to copy this information from
the OrderRequest document. Do not include UnitPrice, Tax, and Shipping if they match
those in the original ItemOut element.
When the type is "accept", "allDetail", or "detail", you can add tax or shipping amounts not
mentioned in the original order. Use the "accept" type when these additions are the only
changes to the order. Use the "detail" type to indicate a substitution if there is an ItemIn
10 Later Status
Changes
Use the Comments element to add information about the status of this portion of the
item. Terms such as "backordered", "shipped", and "invalid" might be sensible. All such data
is intended for human use.
Alternately, use the Extrinsic element list to insert additional data about this particular
item portion for application consumption. These elements can include pre-defined
keywords and values affecting workflow in the receiving system.
Elements in the Extrinsic list can appear in any order. An extrinsic attribute value must
not appear more than once within a ConfirmationStatus element. A type must not be
mentioned both in this list and in the overall ConfirmationHeader element. The
ConfirmationHeader must not contain a default extrinsic value overridden at this lower
level.
quantity Attribute
Specifies how many items have this status. Expressed in the units specified in the
UnitOfMeasure element.
10 Later Status
Changes
type Attribute
10 Later Status
detail Accept this portion with the changes detailed in the
Changes
ConfirmationStatus element. At least one of the UnitPrice, Shipping,
Tax, or ItemIn elements, or the deliveryDate attribute must be
present. This is a substitution if there is an ItemIn element, a price
change if there is a UnitPrice element, or a delayed shipment if
there is a deliveryDate attribute.
reject Reject this portion of the line item.
requestToPay Requests payment for this portion of the line item. It initiates a
request to the financial institution to begin the settlement process of
the portion of the line item.
10 Later Status
This type is allowed in documents with overall request
Changes
(ConfirmationHeader) type "requestToPay".
unknown The status of this portion of the line item is not known at the time of
this confirmation. This line item status provides a placeholder while
the supplier does further research. Update confirmations can also
reset the status of a line item portion to "unknown" when an earlier
confirmation incorrectly accepted or rejected that portion.
Allowed only in documents whose ConfirmationHeader type is
"allDetail", "detail", or "except".
10 Later Status
backordered Sets this portion of the line item to backordered status. The supplier
does not have the items in stock, but will ship them when they are
Changes
available.
shipmentDate Attribute
Specifies the date and time this shipment is expected to leave the supplier. Use the
ConfirmationStatus element to include this information if the type is "accept", "allDetail", or
"detail".
10 Later Status
Changes
deliveryDate Attribute
Specifies the new date and time this shipment is expected to arrive. Do not include if
the value matches the requestedDeliveryDate attribute, if any, in the corresponding
OrderRequest document. Otherwise, use the ConfirmationStatus element to include this
information if its type is "accept", "allDetail", or "detail".
ShipNoticeRequest
Suppliers use the ShipNoticeRequest document to send shipment information about
orders. This transaction describes a single shipment and can contain portions of
multiple orders as well as hazard information for the entire shipment or individual
line items.
Note: The DTD for this transaction is contained in Fulfill.dtd rather than
cXML.dtd.
• ShipNoticeHeader
• ShipControl
• ShipNoticePortion
ShipNoticeRequest documents do not provide updates to tax and shipping amounts. This
information should be transmitted with ConfirmationRequest documents. If necessary,
you can send a ConfirmationRequest with operation="update" with this information after
the shipment has been delivered.
10 Later Status
Changes
<PostalCode>B3C 2G4</PostalCode>
<Country isoCountryCode="CA">Canada</Country>
</PostalAddress>
<Phone>
<TelephoneNumber>
<CountryCode isoCountryCode="CA">1</CountryCode>
<AreaOrCityCode>201</AreaOrCityCode>
<Number>9211132</Number>
</TelephoneNumber>
</Phone>
</Contact>
<Comments xml:lang="en-CA">Got it all into one shipment.</Comments>
</ShipNoticeHeader>
<ShipControl>
<CarrierIdentifier domain="SCAC">FDE</CarrierIdentifier>
<CarrierIdentifier domain="companyName">Federal Express</CarrierIdentifier>
<ShipmentIdentifier>8202 8261 1194</ShipmentIdentifier>
</ShipControl>
10 Later Status
<ShipNoticePortion>
Changes
<!-- The orderID and orderDate attributes are not required in the OrderReference
element. -->
<OrderReference orderID="DO1234">
<DocumentReference payloadID="[email protected]" />
</OrderReference>
</ShipNoticePortion>
</ShipNoticeRequest>
The ShipNoticeRequest element contains information about a ship notice common to all
10 Later Status
contained items. It is not necessary to copy this information from the OrderRequest
Changes
document. The Contact element should be used primarily to add new information
about an order.
10 Later Status
Shipments with multiple responsible carriers are described in one of two ways:
Changes
1. A single carrier or third-party logistics provider creates a tracking identifier
that can be used to retrieve information about the entire trip. Suppliers send
such information in a single ShipControl element.
ShipControl elements must appear in the order the shipment will travel. The first such
element must not have an explicit starting date, the ShipControl startDate attribute must
not be present, and that carrier's control must begin at the shipment's orgination time
specified by the ShipNoticeHeader shipmentDate attribute value. All later ShipControl
elements must have increasing, or later, starting dates specified by the ShipControl
startDate attribute value.
ShipNoticeHeader Element
The ShipNoticeHeader element contains information about a ship notice common to all
contained items. The ShipNoticeHeader element can contain the following elements:
ServiceLevel, DocumentReference, Contact, Hazard, Comments, and Extrinsic, all of which are
optional.
ServiceLevel Element
DocumentReference Element
The contained DocumentReference element appears only when the operation is "update"
or "delete". In that case, the DocumentReference element references the most recent
ShipNoticeRequest document for this particular ship notice, usually indicated by a
common shipmentID. For example, when a ship notice is created, updated, and then
updated again, the final document should contain a DocumentReference referring to the
previous ShipNoticeRequest with operation="update". That document, in turn, refers to the
original operation="new" ShipNoticeRequest document.
10 Later Status
Changes
Contact Element
Contact roles can include: technicalSupport, customerService, sales, shipFrom (starting point
for this shipment), shipTo (should echo the ShipTo element from the OrderRequest
documents), buyerCorporate (details the supplier has about the buying organization),
and supplierCorporate. Generally, it is not necessary to copy information from the
various OrderRequest documents: the Contact element should be used primarily to add
information to that known about an order.
Elements in the Contact list can appear in any order. A Contact role attribute value must
not appear more than once within a ShipNoticeHeader element.
Hazard Element
Elements in the Hazard list can appear in any order. The same hazard should not be
listed more than once in a ShipNoticeHeader. Each hazard listed at this level, in a
10 Later Status
ShipNoticeHeader element, should apply to the entire shipment, or to all items contained
Changes
in this shipment. A ShipNoticeRequest for a single line item should not include Hazard
elements in the ShipNoticeItem element.
Comments Element
Use the Comments element to include additional information about the shipment. In
the ShipNoticeHeader element, that information must be common to all contained items
10 Later Status
and routes. All such data must be intended for human use.
Changes
Extrinsic Element
Alternately, use the Extrinsic element list to insert additional data about the shipment
for application consumption. These elements can include pre-defined keywords and
values affecting workflow in the receiving system.
Elements in the Extrinsic list can appear in any order. An extrinsic type, Extrinsic name
10 Later Status
attribute value, must not appear more than once within a ShipNoticeHeader element. A
Changes
type must not be mentioned both in this list and in a particular ShipControl or
ShipNoticePortion element. The ShipNoticeHeader must not contain a default extrinsic
value overridden at either lower level.
shipmentID Attribute
This value does not vary as a particular ship notice is updated. That is, "update" or
"delete" documents describing the same shipment share a shipmentID with the original
"new" ShipNoticeRequest.
operation Attribute
If the operation is not "new", explicitly or by default, you must also include in the
ShipNoticeRequest a DocumentReference element in the ShipNoticeHeader element. See
“DocumentReference Element” on page 226 for more information on this element.
This effectively sequences multiple versions of a ship notice.
noticeDate Attribute
Specifies the date and time the ShipNoticeRequest document was created. Required.
shipmentDate Attribute
The date and time the shipment left the supplier. You must specify this attribute in all
ShipNoticeRequest documents except when the operation is "delete".
deliveryDate Attribute
Specifies the date and time this shipment is expected to arrive. While this value can
default to the requestedDeliveryDate of a single order, that attribute is optional in an
OrderRequest document, and the ShipNoticeRequest can refer to multiple OrderRequest
documents. You must include this attribute in all ShipNoticeRequest documents except
when the operation is "delete".
10 Later Status
Changes
ServiceLevel Element
Specifies a language-specific string for the service level code. Each ServiceLevel must
contain a string in the specified language that corresponds to the level of service, such
as “overnight”, provided by the carrier for this shipment. It has the required attribute
xml:lang (see page 90).
ShipControl Element
Specifies the carrier responsible for some portion of the shipment. A ShipControl
element contains the CarrierIdentifier, ShipmentIdentifier, PackageIdentification, Route, Contact,
Comments, and Extrinsic elements.
The shipment is tracked using the identifiers provided at this level. Those identifiers
should be valid from the startDate of one ShipControl element or the shipment's
shipmentDate until the startDate of the next.
10 Later Status
Changes
CarrierIdentifier
The CarrierIdentifier list can include multiple identifiers for the same carrier. Elements in
this list can appear in any order. A particular identification domain
(CarrierIdentifier@domain attribute value) must not appear more than once in a ShipControl
element. The identification provided by all elements of the CarrierIdentifier list must
correspond to the same company.
10 Later Status
Route Element
Changes
If present, Route elements must be in the order the shipment will travel.
Contact Element
carrierCorporate Details the contact information the supplier has about the carrier
10 Later Status
organization.
Changes
shipFrom A Contact element with role "shipFrom" must appear in all
ShipControl elements after the first. This role must not appear in the
first ShipControl element because it would duplicate that role in the
overall ShipNoticeHeader element.
Do not use a “shipTo“ role in this element because a Contact with role "shipTo" would
always duplicate information in the following ShipControl element or that role in the
ShipNoticeHeader. Control passes from one carrier to another at a particular location and
10 Later Status
estimated time.
Changes
List the elements in Contact in any order. A Contact role attribute value must not appear
more than once within a ShipControl element.
Comments Element
The Comments element can contain additional information about the shipment while
under the control of this carrier. In the context of the ShipControl element, that
information must be common to all contained routes or made clear which Route is
affected. All such data must be intended for human use.
Extrinsic Element
Alternately, the Extrinsic element list can be used to insert additional data about this
carrier or their period of responsibility for application consumption. These elements
can include pre-defined keywords and values affecting workflow in the receiving
system.
Elements in the Extrinsic list can appear in any order. An Extrinsic name attribute value
must not appear more than once within a ShipControl element. The same type must not
be mentioned both in this list and in the overall ShipNoticeHeader element. The
ShipNoticeHeader must not contain a default extrinsic value overridden at this lower
level.
startDate Attribute
Specifies the date and time this shipment started this part of the route. Required for all
ShipControl elements after the first. This attribute must not appear in the first ShipControl
element because it would duplicate the ShipNoticeHeader's shipmentDate attribute.
Route Element
Specifies how the shipment will travel on this segment. If two ShipmentIdentifier values
are present, the second defines the end of a contiguous and inclusive range of
numbers that appear on the shipment. Route can contain a Contact element.
The only Contact role should be "carrierCorporate", which details the contact information
the supplier has about the carrier organization, "shipFrom", and "shipTo".
10 Later Status
Changes
A Route element can describe only a single mode of travel. If described at all, each
mode of a multi-modal route must be described by a separate Route element. It is not
necessary to describe every leg of the journey to the buyer's ShipTo location.
The "carrierCorporate" role is relevant at this level only when a third party is providing
tracking information across multiple carriers. A Contact element with role "shipFrom"
must appear in all Route elements after the first. Route elements are not required to
describe the entire travel under a specific carrier's control. They can describe a
discontinuous stream of events, starting and ending at different times and locations.
Elements in the Contact list can appear in any order. A Contact role attribute value must
not appear more than once within a Route element.
method Attribute
10 Later Status
Changes
air Transportation by flight
motor Transportation by land motor craft, common carrier
rail Transportation by rail
ship Transportation by boat; ocean
Because shipments can travel through multiple segments with different methods, this
attribute has no default.
10 Later Status
Changes
startDate Attribute
Specifies the date and time this shipment started this part of the trip. Required in all
Route elements after the first.
endDate Attribute
10 Later Status
Specifies the date and time this shipment ended this part of the trip. Must come after
Changes
startDate. If any Route elements follow, the startDate of that element must not precede
this value.
CarrierIdentitifier Element
Identifies the carrier that will transport this shipment. There is one attribute, called
domain.
10 Later Status
Changes
domain Attribute
Specifies the domain in which CarrierIdentifier value has meaning. For example,
“SCAC” for Standard Carrier Alpha Code, or the legal company name.
company The legal name for this company. In some cases, this can also be
name provided in a Contact element with role "carrierCorporate". Using a
Contact element should be reserved for cases in which additional detail
about the carrier must be conveyed.
SCAC Standard Carrier Alpha Code. www.nmfta.org
IATA International Air Transport Association. www.iata.org
AAR Association of American Railroads. www.aar.org
UIC International Union of Railways. www.uic.asso.fr
EAN European Article Numbering. www.ean-ucc.org
DUNS Dun and Bradstreet's Data Universal Numbering System.
www.dnb.com/dnbhome.htm
ShipmentIdentifier Element
A tracking number defined by the carrier that appears on the shipment that can be
used to obtain additional detail about the shipment. Has meaning in the domain
described by the CarrierIdentifier values in the containing Route element.
Different carriers have different names for shipment identifiers. This is commonly
called a way bill number, a pro number, and also a bill of lading. They all represent
tracking numbers.
PackageIdentification Element
Specifies the identifiers that appear on the containers, skids, boxes, or packages that
constitute the shipment. The range of numbers described is inclusive at both extremes.
rangeBegin Attribute
Specifies the earliest number that appears on the separate elements in this shipment.
rangeEnd Attribute
Specifies the highest number that appears on the separate elements in this shipment.
Must be greater than or equal to rangeBegin.
10 Later Status
Changes
ShipNoticePortion Element
Contains purchase order and item information. Specifies what will be in the shipment.
It contains three elements, OrderReference, ShipNoticeItem, Contact, Comments, and Extrinsic.
All but OrderReference are optional. It contains two attributes: quantity and lineNumber.
OrderReference Element
10 Later Status
Contact Element
Changes
Any Contact elements provided at this level describe contacts specific to this portion of
the order. The ShipNoticeHeader description mentions roles appropriate at this level as
well, though shipFrom, shipTo, buyerCorporate, and supplierCorporate information should
not vary at this level. A particular Contact role must not appear in both the
ShipNoticePortion and ShipNoticeHeader elements. Therefore, roles such as
“technicalSupport”, “customerService”, and “sales” are most appropriate within the
ShipNoticePortion.
10 Later Status
Changes
Elements in the Contact list can appear in any order. A Contact role attribute value must
not appear more than once within a ShipNoticePortion element.
Comments Element
The Comments element can contain additional information about the order in this
shipment. In this context (the ShipNoticePortion element), that information must be
10 Later Status
common to all contained items or make it clear which ShipNoticeItem is affected. All
Changes
such data must be intended for human use.
Extrinsic Element
Alternately, the Extrinsic element list can be used to insert additional data about this
order for application consumption. These elements can include pre-defined keywords
and values affecting workflow in the receiving system.
10 Later Status
Changes
Elements in the Extrinsic list can appear in any order. An Extrinsic name attribute value
must not appear more than once within a ShipNoticePortion element. A type must not be
mentioned both in this list and in the overall ShipNoticeHeader element. The
ShipNoticeHeader must not contain a default extrinsic value overridden at this lower
level.
ShipNoticeItem Element
The portion of a specific line item that is part of this shipment. Each line item from an
order must be mentioned in at most one ShipNoticeItem element. ShipNoticeItem contains
three elements: UnitOfMeasure (for more information, see “UnitOfMeasure” on page
57), Packaging, and Hazard.
Elements in the Hazard list can appear in any order. The same Hazard should not be
listed more than once in a ShipNoticeItem. Each Hazard listed at this level (in a
ShipNoticeItem element) must apply to this specific line item. A ShipNoticeRequest for a
single line item should not include Hazard elements in the ShipNoticeItem element.
quantity Attribute
Quantity specifies how many items were shipped. Expressed in units given in the
UnitOfMeasure element.
lineNumber Attribute
Position, counting from 1, of the item in an order. Matches the corresponding line
item, ItemOut, in the document referenced by the OrderReference element.
Packaging Element
Details about the packaging of this line item. The dimensions mentioned in the
Dimension element list can appear in any order. The Packaging element contains one or
more PackagingCode elements and optional Dimension element (see page 235). A
particular Dimension type attribute value must not appear more than once in a Packaging
element.
PackagingCode Element
Specifies one language-specific code for the packaging of the item. Values such as
"pallet", "skid" and "truck load" might be appropriate for an English-based locale. The
xml:lang attribute specifies the language or locale in which the PackagingCode content is
written.
10 Later Status
Changes
Dimension Element
• quantity attribute
Specifies the size in this dimension. Expressed in the units given in the
UnitOfMeasure element.
• type attribute
Type of dimension. Supported values include:
10 Later Status
weight The weight of the packaging.
Changes
volume The volume of the packaging
Hazard Element
The Hazard element provides a textual description and optional codes about hazards
inherent in both an item and an overall shipment. A hazard for an entire shipment can
be due to either identical hazards for all items or to hazards inherent in shipping the
various products together. It can also include detailed handling requirements. There
10 Later Status
are two elements: Description, and Classification. Classification is optional and can occur
Changes
more than once.
10 Later Status
Classification elements can appear in any order. A Classification domain attribute must not
Changes
appear more than once in a Hazard element.
All listed Classification elements and the Description, if provided, must relate to a single
hazard. Additional hazards must use separate Hazard elements.
10 Later Status
Changes
OrderReference Element
The OrderReference element refers to a prior OrderRequest document. It contains a
DocumentReference element.
orderID Attribute
Specifies the buyer system orderID for the ship notice, that is, the PO number. When
used, it must be copied directly from the referenced OrderRequest document's
OrderRequestHeader element.
orderDate Attribute
Specifies the date and time the OrderRequest was created. The date format is yyyy-mm-
dd per international ISO standard 8601.
11 Invoices
The cXML InvoiceDetail transaction enables suppliers to send invoices to buying
organizations or marketplaces. This transaction supports invoice details for a wide
variety of business scenarios, including standard invoices, credit memos, debit
memos, and receipts.
11 Invoices
• Overview of Invoices
• InvoiceDetailRequest
• Response
• Invoice Status Update
• Example Invoices
11 Invoices
Overview of Invoices
Suppliers use cXML invoices to bill buying organizations or marketplaces for
provided products or services. Invoices can be generated against any portion of any
line items from single or multiple purchase orders. The InvoiceDetail transaction
supports cancel invoices, credit memos, debit memos, and receipts.
11 Invoices
Invoices describe purchase orders, line items, partners involved, accounting
distribution, payment terms, discounts, shipping and special handling, taxes, deposit
and prepayment, and remittance information.
Suppliers send invoices to commerce network hubs. Commerce network hubs route
invoices to the buying organization by either querying the buying organization’s
ProfileResponse or by looking up routing information in the buying organization’s
network account.
11 Invoices
For PCard-enabled purchase orders, suppliers can request payment by using either
invoices or the request-to-pay functionality provided by ConfirmationRequest documents
(for more information, see “ConfirmationRequest” on page 211.)
Shipping Information
Invoices can include shipping information such as shipping charges, dates, from/to
addresses, and carrier IDs. Ones of the reasons invoices support shipping information
is because it can affect the final prices and taxes for orders shipped internationally.
Types of Invoices
InvoiceDetailRequest has the features and flexibility to support most business scenarios.
11 Invoices
Individual and Summary Invoices
11 Invoices
Invoice Level
11 Invoices
Specify isHeaderInvoice="yes" and use
InvoiceDetailHeaderOrder elements, which do not contain line-
item information.
Detailed Invoice (Line-item level invoice) Applies against specific line items from
one or more purchase orders.
Leave out isHeaderInvoice and use InvoiceDetailOrder elements,
which contain line-item information.
Invoice Purpose
11 Invoices
Use the InvoiceDetailRequestHeader attributes to specify the purpose of the invoice.
11 Invoices
header invoice. Amounts must be negative.
Debit Memo Specifies debit to a buying organization.
Specify purpose="debitMemo" and operation="new". Must be a
header invoice. Amounts must be positive.
Information Only Provides a record of charges, similar to a receipt. No action is
expected.
Specify isInformationOnly="yes" and operation="new".
Cancel Invoice Cancels a previously sent invoice.
Specify operation="delete".
11 Invoices
Invoice DTD
The cXML standard uses multiple DTDs to optimize the performance of validating
parsers. The InvoiceDetail transaction is defined in a separate DTD named
InvoiceDetail.dtd, available at:
http://xml.cXML.org/schemas/cXML/<version>/InvoiceDetail.dtd
InvoiceDetailRequest
InvoiceDetailRequest documents represent invoices.
All invoice line level amounts must add up to the total specified in
InvoiceDetailSummary.
11 Invoices
InvoiceDetailRequestHeader
Defines header information that applies to the entire invoice.
11 Invoices
Indicates whether the buying organization needs to take action:
yes — Invoice is for the buying organization's information only
(no action needs to be taken by the buying organization).
isInformationOnly
Not specified — (default) Invoice is functional. The buying
organization needs to take action upon receiving this document
(submit payment or accept credit).
Purpose of the invoice:
standard — (default) A standard billing statement from the
supplier to the buying organization.
11 Invoices
creditMemo — A credit memo for issuing credit to the buying
organization. isHeaderInvoice must be yes. Also, the element
purpose InvoiceDetailSummary/DueAmount must be a negative
amount.
debitMemo — A debit memo for billing a balance owed by the
buying organization. isHeaderInvoice must be yes. Also, the
element InvoiceDetailSummary/DueAmount must be a positive
amount.
How this document is acting on the invoice:
11 Invoices
new — (default) Creates a new invoice.
operation
delete — Cancels an existing invoice. The PayloadID of the
existing invoice must be specified in a DocumentReference.
Date and time Invoice was created (should be earlier than the
invoiceDate
cXML timestamp).
11 Invoices
11 Invoices
InvoiceDetailHeaderIndicator
Defines indicators that describe overall attributes of the invoice. By default, all
indicators are false.
InvoiceDetailLineIndicator
Indicates the presence of invoicing details at invoice line level (in InvoiceDetailItem,
InvoiceDetailServiceItem, or InvoiceDetailOrderSummary). By default, all indicators are false.
If this element indicates that invoicing details exist at invoice line level, invoice lines
that do not provide such information are assumed to have values of zero, or “not
available” for that information.
11 Invoices
InvoicePartner
Defines a party involved in invoicing, including the issuer of the invoice and the
person sold to.
Invoices support InvoicePartner because the Contact element alone does not support the
wide variety of reference identifiers involved in invoicing.
11 Invoices
Do not use this element to specify ship from or ship to; instead, use
InvoiceDetailShipping.
Contact
Contact information of the invoice partner. Allowed contact roles are issuerOfInvoice,
soldTo, billTo, remitTo.
11 Invoices
IdReference
11 Invoices
identifier The unique identifier of the IdReference within the domain.
The domain of the IdReference. One of the following values:
accountID bankRoutingID accountPayableID
federalTaxID stateTaxID accountReceivableID
provincialTaxID vatID gstID
domain taxExemptionIS
Values can be application-specific, such as 1099ID or
courtRegisterID.
supplierTaxID has been deprecated and is treated as
federalTaxID.
11 Invoices
Creator
The creator of the IdReference (for example, the name of the bank, shipper, or
other organization).
Description
DocumentReference
InvoiceDetailShipping
shippingDate The date and time this shipment leaves the supplier.
Contact
The ship from and ship to addresses. Both ship from and ship to must be specified.
Name
PostalAddress
11 Invoices
Email has the following attributes:
Phone
11 Invoices
Telephone number of the contact
Fax
URL
11 Invoices
CarrierIdentifier
This list can include multiple identifiers for the same carrier. Elements in this list can
appear in any order. An identification domain (CarrierIdentifier domain) must not appear
more than once in an InvoiceDetailShipping element. All identification provided by
elements of one CarrierIdentifier list must correspond to the same company.
11 Invoices
Domain for this value. Recognized domains include:
companyName - The legal name for this company. In some
cases, this could also be provided in a Contact element with
role "carrierCorporate". That option should be reserved for
cases in which additional detail about the carrier appears in this
element.
SCAC - Standard Carrier Alpha Code. www.nmfta.org/
domain scac2.htm
IATA - International Air Transport Association. www.iata.org
11 Invoices
AAR - Association of American Railroads. www.aar.org
UIC - International Union of Railways. www.uic.asso.fr
EAN - European Article Numbering. www.ean-ucc.org
DUNS - D&B's Data Universal Numbering System.
www.dnb.com
ShipmentIdentifier
DocumentReference
InvoiceDetailPaymentTerm (deprecated)
PaymentTerm
Defines a payment term in an invoice or order. PaymentTerm defines either the net term
(without discount) or the discount term (with discount).
Discount
The percentage or amount of the discount term. The discount rate applies if the
invoice total is paid within the time specified by payInNumberOfDays. Positive rates
denote discounts and negative rates denote penalties. Do not use a percentage sign
(%) or divide by 100; for example “2” means 2%.
Period
InvoiceDetailOrder
Defines the invoice information of an order with item details, used only when
isHeaderInvoice is false (not specified).
11 Invoices
An invoice line is an InvoiceDetailItem or an InvoiceDetailServiceItem and its invoice line
number is specified by the invoiceLineNumber attribute.
InvoiceDetailOrderInfo
11 Invoices
agreement. The more definitive the reference, the more likely applications can
successfully perform document matching.
11 Invoices
OrderReference
MasterAgreementReference
11 Invoices
MasterAgreementReference has the following attributes:
MasterAgreementIDInfo
11 Invoices
if the order being invoiced is a release. This element identifies the master agreement
of the contract or release order to be invoiced.
OrderIDInfo
SupplierOrderInfo
InvoiceDetailItem
The buying organization might require information provided here to match the
information provided in the purchase order. For example, the buying organization
might require there to be no change in the UnitOfMeasure value.
UnitOfMeasure
The line item’s unit of measure. For more information, see “UnitOfMeasure” on page
57.
UnitPrice
11 Invoices
InvoiceDetailItemReference
lineNumber The purchase order line number of current line item, copied
from the OrderRequest.
11 Invoices
The product serial number for the current line item.
serialNumber
(deprecated) This attribute was deprecated in cXML 1.2.009. Use
SerialNumber elements, instead.
ItemID
The supplier part number of current line item, from the OrderRequest.
Description
11 Invoices
The line item description, from the OrderRequest.
SerialNumber
11 Invoices
elements should match the invoice item quantity.
ManufacturerPartID
11 Invoices
ManufacturerName
Country
SubtotalAmount
The invoice subtotal of the current line item: UnitPrice times quantity.
Tax
The tax for the line item. Ignored if isTaxInLine is false (not specified).
Money
Description
TaxDetail
TaxableAmount
11 Invoices
TaxAmount
TaxLocation
11 Invoices
Description
TriangularTransactionLawReference
11 Invoices
InvoiceDetailLineSpecialHandling
The special handling information for the line item. Ignored if isSpecialHandlingInLine is
false (not specified).
InvoiceDetailLineShipping
The shipping information for the line item. Ignored if isShippingInLine is false (not
specified).
11 Invoices
GrossAmount
The SubtotalAmount plus taxes, shipping, and special handling charges for the line item.
InvoiceDetailDiscount
The discount for the line item. Ignored if isDiscountInLine is false (not specified).
11 Invoices
NetAmount
Distribution
Comments
Extrinsic
Additional information related to the line item. Should not duplicate anything in
InvoiceDetailItem or InvoiceDetailOrder.
InvoiceDetailServiceItem
InvoiceDetailServiceItemReference
Classification
ItemID
11 Invoices
Description
SubtotalAmount
The subtotal amount of the service item. If unit price and invoiced quantity are
specified, then subtotal should be the product of them.
11 Invoices
Period
UnitRate
11 Invoices
The rate at which the service item is charged. In cXML version 2.1.011 or later, use
the UnitRate element rather than UnitOfMeasure and UnitPrice, because UnitRate includes
the rate code. For some services, such as temporary labor, UnitRate is required.
UnitRate represents the amount to be paid per unit of time (or of some other measure).
In the case of multiple UnitRates, each UnitRate should include a TermReference to
distinguish it from others. TermReference is a generic base element that identifies the
definition of the UnitRate in question. See “UnitRate” on page 152.
11 Invoices
UnitOfMeasure (deprecated)
UnitOfMeasure is
deprecated in cXML 1.2.011, and should not be used in new cXML
documents. Use UnitRate instead. UnitOfMeasure is the unit of measure for the service.
For example, HUR for per hour or MON for per month.
UnitPrice (deprecated)
UnitPrice is
deprecated in cXML 1.2.011, and should not be used in new cXML
11 Invoices
documents. Use UnitRate instead. UnitPrice is the price, per unit of measure.
Tax
The tax for the line item. Ignored if isTaxInLine is false (not specified).
GrossAmount
The SubtotalAmount plus taxes, shipping, and special handling charges for the line item.
InvoiceDetailDiscount
The discount for the line item. Ignored if isDiscountInLine is false (not specified).
NetAmount
Distribution
Comments
InvoiceLaborDetail
Contractor
JobDescription
Supervisor
Specifies contact information for the person who supervises the contractor.
WorkLocation
InvoiceTimeCardDetail
Invoice details about a temporary labor service. The pay code for this invoice
line item is in the UnitRate of the containing InvoiceDetailServiceItem.
11 Invoices
TimeCardReference
11 Invoices
TimeCardIDInfo
Defines the unique ID of the timecard known to the buyer and supplier
systems. TimeCardIDInfo has the following attribute:
11 Invoices
“TimeCard Transaction.”
Extrinsic
Use Extrinsic elements to specify line item related attributes such as service location,
overtime/regular, and union/non- union.
11 Invoices
For simple attributes such as overtime/regular, use a simple name, value pair, for
example:
<Extrinsic name="serviceType">Temporary</Extrinsic>.
For structured attributes such as service location, use a structured element, for
example:
11 Invoices
<Extrinsic name="serviceLocation">
<Contact role="serviceLocation">
<Name>XYZ Inc</Name>
<PostalAddress>
<Street>123 Easy St</Street>
<City>Sunnyvale</City>
<State>California</State>
<PostalCode>94089</PostalCode>
<Country isoCountryCode="US">USA</Country>
</PostalAddress>
11 Invoices
</Contact>
</Extrinsic>
InvoiceDetailHeaderOrder
Defines the header invoice information of a purchase order, without item details, used
only when isHeaderInvoice="yes".
In this case, an invoice line is an InvoiceDetailHeaderOrder and its invoice line number is
specified by the invoiceLineNumber attribute.
InvoiceDetailOrderInfo
InvoiceDetailOrderSummary
SubtotalAmount
Period
Tax
The tax for this order. Ignored if isTaxInLine is false (not specified).
11 Invoices
InvoiceDetailLineSpecialHandling
InvoiceDetailLineShipping
The shipping information for this invoice line. Ignored if isShippingInLine is false (not
11 Invoices
specified).
InvoiceDetailShipping
Money
11 Invoices
The shipping amount.
GrossAmount
InvoiceDetailDiscount
The discount or penalty for this invoice line. Ignored if isDiscountInLine is false (not
11 Invoices
specified).
NetAmount
11 Invoices
The GrossAmount minus discount amount.
Comments
Extrinsic
Additional information related to the line item. Should not duplicate anything in
InvoiceDetailOrderSummary or InvoiceDetailHeaderOrder.
InvoiceDetailSummary
Defines the summary information of an invoice.
SubtotalAmount
Tax
SpecialHandlingAmount
Total special handling charge. You can optionally add a Description element to explain
the charge.
ShippingAmount
GrossAmount
Sum of subtotal, taxes, special handling charges, and shipping charges, before
discounts.
InvoiceDetailDiscount
11 Invoices
NetAmount
DepositAmount
11 Invoices
DueAmount
Response
11 Invoices
Immediately after receiving an invoice, the receiving system should respond with a
generic cXML Response document, for example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/
InvoiceDetail.dtd">
<cXML timestamp="2001-10-31T23:07:22-08:00" payloadID="1004598442900-
[email protected]">
11 Invoices
<Response>
<Status code="201" text="Accepted">Acknowledged</Status>
</Response>
</cXML>
11 Invoices
Invoice Status Update
After buying organizations receive invoices, they can perform reconciliation to match
the charges within them to amounts within purchase orders or master agreements.
They can then set invoice status to indicate whether charges reconciled successfully.
processing The invoice was received by the buying organization and is being
processed.
reconciled The invoice reconciled. The amounts in the invoice have not yet
been paid.
paying The invoice is in the payment process or has been partially paid.
paid The invoice amounts have been paid by the buying organization.
11 Invoices
<UserAgent>Procurement Application V1.0</UserAgent>
</Sender>
</Header>
<Request>
<StatusUpdateRequest>
<DocumentReference payloadID="Inv123"></DocumentReference>
<Status code="200" text=""></Status>
<InvoiceStatus type="paid">
<PartialAmount>
11 Invoices
<Money currency="USD">10.99</Money>
</PartialAmount>
<Comments>This charge is paid, minus $2.00 due to missing items.</Comments>
</InvoiceStatus>
</StatusUpdateRequest>
</Request>
</cXML>
11 Invoices
on page 206.
Example Invoices
The following examples illustrate several types of invoices.
11 Invoices
• Standard Detail Invoice
• Service Invoice
• Marketplace Invoice
11 Invoices
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE cXML SYSTEM "http://
xml.cXML.org/schemas/cXML/1.2.014/InvoiceDetail.dtd">
<cXML timestamp="2001-10-10T16:23:01-07:00" payloadID="Oct102001_0447pm">
<Header>
<From>
<Credential domain="AribaNetworkUserID">
<Identity>[email protected]</Identity>
</Credential>
11 Invoices
</From>
<To>
<Credential domain="AribaNetworkUserID">
<Identity>[email protected]</Identity>
</Credential>
</To>
<Sender>
<Credential domain="AribaNetworkUserID">
<Identity>[email protected]</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Supplier’s Super Invoice Generator</UserAgent>
</Sender>
</Header>
<Request>
<InvoiceDetailRequest>
<InvoiceDetailRequestHeader invoiceDate="2001-10-09T00:00:00-07:00"
invoiceID="Oct102001_0447pm" purpose="standard" operation="new">
<InvoiceDetailHeaderIndicator isHeaderInvoice="yes" />
<InvoiceDetailLineIndicator isTaxInLine="yes" isShippingInLine="yes"
isSpecialHandlingInLine="yes" isDiscountInLine="yes" />
<InvoicePartner>
<Contact role="billTo">
<Name xml:lang="en-US">Buyer Headquarters</Name>
<PostalAddress>
<Street>111 Main Street</Street>
<City>Anytown</City>
<State>CA</State>
<PostalCode>94089</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
<InvoicePartner>
<Contact role="remitTo">
<Name xml:lang="en-US">Supplier Accts. Receivable</Name>
<PostalAddress>
<Street>One Bank Avenue</Street>
<City>Any City</City>
<State>CA</State>
<PostalCode>94087</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
</Contact>
<IdReference identifier="123456789" domain="bankRoutingID" />
<IdReference identifier="3456" domain="accountID" />
</InvoicePartner>
<Comments xml:lang="en-US">This is an invoice for DO789</Comments>
</InvoiceDetailRequestHeader>
<InvoiceDetailHeaderOrder>
<InvoiceDetailOrderInfo>
<OrderReference>
11 Invoices
<DocumentReference payloadID="99576652.982.090.136" />
</OrderReference>
</InvoiceDetailOrderInfo>
<InvoiceDetailOrderSummary invoiceLineNumber="1">
<SubtotalAmount>
<Money currency="USD">5000.00</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">500.00</Money>
11 Invoices
<Description xml:lang="en-US">State Tax</Description>
</Tax>
<InvoiceDetailLineSpecialHandling>
<Money currency="USD">110.00</Money>
</InvoiceDetailLineSpecialHandling>
<InvoiceDetailLineShipping>
<InvoiceDetailShipping>
<Contact role="shipFrom" addressID="1000487">
<Name xml:lang="en">Main Shipping Dock</Name>
<PostalAddress name="default">
11 Invoices
<Street>15 Oak Road</Street>
<City>Bigtown</City>
<State>CA</State>
<PostalCode>95032</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
<Email name="default">[email protected]</Email>
<Phone name="work">
<TelephoneNumber>
<CountryCode isoCountryCode="US">1</CountryCode>
11 Invoices
<AreaOrCityCode>888</AreaOrCityCode>
<Number>1234567</Number>
</TelephoneNumber>
</Phone>
</Contact>
<Contact role="shipTo" addressID="1000487">
<Name xml:lang="en">Main Receiving</Name>
<PostalAddress name="default">
<DeliverTo>Jason Lynch</DeliverTo>
11 Invoices
<Street>77 Nowhere Street</Street>
<City>Industrial Town</City>
<State>CA</State>
<PostalCode>95035</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
<Email name="default">[email protected]</Email>
<Phone name="work">
<TelephoneNumber>
<CountryCode isoCountryCode="US">1</CountryCode>
11 Invoices
<AreaOrCityCode>999</AreaOrCityCode>
<Number>3582000</Number>
</TelephoneNumber>
</Phone>
</Contact>
</InvoiceDetailShipping>
<Money currency="USD">200.00</Money>
</InvoiceDetailLineShipping>
<GrossAmount>
<Money currency="USD">5810.00</Money>
</GrossAmount>
<InvoiceDetailDiscount percentageRate="10">
<Money currency="USD">581.00</Money>
</InvoiceDetailDiscount>
<NetAmount>
<Money currency="USD">5229.00</Money>
</NetAmount>
<Comments>This a Standard Header Level Invoice</Comments>
</InvoiceDetailOrderSummary>
</InvoiceDetailHeaderOrder>
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="USD">5000.00</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">500.00</Money>
<Description xml:lang="en-US">State Tax</Description>
</Tax>
<SpecialHandlingAmount>
<Money currency="USD">110.00</Money>
<Description xml:lang="en">Invoice Surcharge</Description>
</SpecialHandlingAmount>
<ShippingAmount>
<Money currency="USD">200.00</Money>
</ShippingAmount>
<GrossAmount>
<Money currency="USD">5810.00</Money>
</GrossAmount>
<InvoiceDetailDiscount percentageRate="10">
<Money currency="USD">581.00</Money>
</InvoiceDetailDiscount>
<NetAmount>
<Money currency="USD">5229.00</Money>
</NetAmount>
<DepositAmount>
<Money currency="USD">1000.00</Money>
</DepositAmount>
<DueAmount>
<Money currency="USD">4229.00</Money>
</DueAmount>
</InvoiceDetailSummary>
</InvoiceDetailRequest>
11 Invoices
</Request>
</cXML>
11 Invoices
payment. It also contains the buying organization’s accounting information copied
from the purchase order.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/
InvoiceDetail.dtd">
<cXML payloadID="Oct102001_1204pm" timestamp="2001-04-20T23:59:45-07:00">
<Header>
From, To, and Sender credentials
</Header>
11 Invoices
<Request>
<InvoiceDetailRequest>
<InvoiceDetailRequestHeader invoiceID="Oct102001_1204pm"
purpose="standard" operation="new"
invoiceDate="2001-04-20T23:59:20-07:00">
<InvoiceDetailHeaderIndicator/>
<InvoiceDetailLineIndicator isTaxInLine="yes” isShippingInLine="yes"
isAccountingInLine="yes"/>
<InvoicePartner>
Sell To contact information
11 Invoices
</InvoicePartner>
<InvoicePartner>
Remit To contact information
</InvoicePartner>
<PaymentTerm payInNumberOfDays="10">
<Discount>10</Discount>
</PaymentTerm>
<PaymentTerm payInNumberOfDays="20">
<Discount>5</Discount>
</PaymentTerm>
11 Invoices
<PaymentTerm payInNumberOfDays="30">
<Discount>0</Discount>
</PaymentTerm>
<PaymentTerm payInNumberOfDays="40">
<Discount>-5</Discount>
</PaymentTerm>
<PaymentTerm payInNumberOfDays="50">
<Discount>-9</Discount>
</PaymentTerm>
</InvoiceDetailRequestHeader>
11 Invoices
<InvoiceDetailOrder>
<InvoiceDetailOrderInfo>
<OrderReference>
<DocumentReference payloadID="99576652.982.090.136"/>
</OrderReference>
<MasterAgreementReference>
<DocumentReference payloadID="99576652.980.000.423"/>
</MasterAgreementReference>
<SupplierOrderInfo orderID="DO1234"></SupplierOrderInfo>
</InvoiceDetailOrderInfo>
<InvoiceDetailItem invoiceLineNumber="1" quantity="1">
<UnitOfMeasure>EA</UnitOfMeasure>
<UnitPrice><Money currency="USD">15.40</Money></UnitPrice>
<InvoiceDetailItemReference lineNumber="1">
<ItemID>
<SupplierPartID>TEX08134</SupplierPartID>
</ItemID>
<Description xml:lang="en">
Texas Instruments Superview Calculator - 12-Digit Print/Display
</Description>
<SerialNumber>45993823469876</SerialNumber>
</InvoiceDetailItemReference>
<SubtotalAmount>
<Money currency="USD">15.40</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">1.54</Money>
<Description xml:lang="en">total item tax</Description>
<TaxDetail purpose="tax" category="sales" percentageRate="8">
<TaxableAmount>
<Money currency="USD">15.40</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">1.23</Money>
</TaxAmount>
<TaxLocation xml:lang="en">CA</TaxLocation>
</TaxDetail>
<TaxDetail purpose="tax" category="sales" percentageRate="2">
<TaxableAmount>
<Money currency="USD">15.40</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">0.31</Money>
</TaxAmount>
<TaxLocation xml:lang="en">US</TaxLocation>
</TaxDetail>
</Tax>
<InvoiceDetailLineShipping>
<InvoiceDetailShipping>
Ship From and Ship To contact information
</InvoiceDetailShipping>
<Money currency="USD">2.00</Money>
11 Invoices
</InvoiceDetailLineShipping>
<GrossAmount>
<Money currency="USD">18.94</Money>
</GrossAmount>
<NetAmount>
<Money currency="USD">18.94</Money>
</NetAmount>
<Distribution>
<Accounting name="Buyer assigned accounting code 15">
11 Invoices
<AccountingSegment id="ABC123456789">
<Name xml:lang="en">Purchase</Name>
<Description xml:lang="en">Production Control</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="USD">18.94</Money>
</Charge>
</Distribution>
<Distribution>
11 Invoices
<Accounting name="Buyer assigned accounting code 16">
<AccountingSegment id="ABC000000001">
<Name xml:lang="en">Trade</Name>
<Description xml:lang="en">Misc (Expensed)</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="USD">18.94</Money>
</Charge>
</Distribution>
11 Invoices
</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="2" quantity="1">
<UnitOfMeasure>PK</UnitOfMeasure>
<UnitPrice><Money currency="USD">4.95</Money></UnitPrice>
<InvoiceDetailItemReference lineNumber="2">
<ItemID>
<SupplierPartID>PENCIL123</SupplierPartID>
</ItemID>
<Description xml:lang="en">
11 Invoices
One dozen wood #2 pencils with eraser
</Description>
</InvoiceDetailItemReference>
<SubtotalAmount>
<Money currency="USD">4.95</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">0.50</Money>
<Description xml:lang="en">total item tax</Description>
<TaxDetail purpose="tax" category="sales" percentageRate="8">
11 Invoices
<TaxableAmount>
<Money currency="USD">0.40</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">4.95</Money>
</TaxAmount>
<TaxLocation xml:lang="en">CA</TaxLocation>
</TaxDetail>
<TaxDetail purpose="tax" category="sales" percentageRate="2">
<TaxLocation xml:lang="en">US</TaxLocation>
<TaxableAmount>
<Money currency="USD">4.95</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">0.10</Money>
</TaxAmount>
</TaxDetail>
</Tax>
<InvoiceDetailLineShipping>
<InvoiceDetailShipping>
Ship From and Ship To contact information
</InvoiceDetailShipping>
<Money currency="USD">1.00</Money>
</InvoiceDetailLineShipping>
<GrossAmount>
<Money currency="USD">6.45</Money>
</GrossAmount>
<NetAmount>
<Money currency="USD">6.45</Money>
</NetAmount>
</InvoiceDetailItem>
</InvoiceDetailOrder>
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="USD">20.35</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">2.04</Money>
<Description xml:lang="en">total tax</Description>
<TaxDetail purpose="tax" category="sales" percentageRate="8">
<TaxableAmount>
<Money currency="USD">20.35</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">1.63</Money>
</TaxAmount>
<TaxLocation xml:lang="en">CA</TaxLocation>
</TaxDetail>
<TaxDetail purpose="tax" category="sales" percentageRate="2">
<TaxableAmount>
<Money currency="USD">20.35</Money>
</TaxableAmount>
11 Invoices
<TaxAmount>
<Money currency="USD">0.41</Money>
</TaxAmount>
<TaxLocation xml:lang="en">US</TaxLocation>
</TaxDetail>
</Tax>
<ShippingAmount>
<Money currency="USD">3.00</Money>
</ShippingAmount>
11 Invoices
<GrossAmount>
<Money currency="USD">25.39</Money>
</GrossAmount>
<NetAmount>
<Money currency="USD">25.39</Money>
</NetAmount>
<DueAmount>
<Money currency="USD">25.39</Money>
</DueAmount>
</InvoiceDetailSummary>
11 Invoices
</InvoiceDetailRequest>
</Request>
</cXML>
Service Invoice
The following invoice is for both regular items and service items.
11 Invoices
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/
InvoiceDetail.dtd">
<cXML payloadID="[email protected]" timestamp="2001-04-20T23:59:45-07:00">
<Header>
From, To, and Sender credentials
</Header>
<Request deploymentMode="test">
<InvoiceDetailRequest>
<InvoiceDetailRequestHeader
11 Invoices
invoiceID="123456"
purpose="standard"
operation="new"
invoiceDate="2001-04-20T23:59:20-07:00">
<InvoiceDetailHeaderIndicator/>
<InvoiceDetailLineIndicator
isTaxInLine="yes"
isShippingInLine="yes"
isAccountingInLine="yes"/>
<InvoicePartner>
11 Invoices
11 Invoices
<TaxableAmount>
<Money currency="USD">5713</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">200</Money>
</TaxAmount>
<TaxLocation xml:lang="en">CA</TaxLocation>
</TaxDetail>
</Tax>
11 Invoices
<GrossAmount>
<Money currency="USD">6000</Money>
</GrossAmount>
<NetAmount>
<Money currency="USD">6000</Money>
</NetAmount>
</InvoiceDetailItem>
<InvoiceDetailServiceItem
invoiceLineNumber="2"
quantity="100">
11 Invoices
<InvoiceDetailServiceItemReference lineNumber="1">
<Classification domain="UNSPC">76111501</Classification>
<Description xml:lang="en">
Window cleaning services at $30/hour
</Description>
</InvoiceDetailServiceItemReference>
<SubtotalAmount>
<Money currency="USD">3000.00</Money>
</SubtotalAmount>
<Period startDate="2001-02-01T12:00:00-00:00"
11 Invoices
endDate="2001-03-30T12:00:00-00:00"/>
<UnitOfMeasure>HUR</UnitOfMeasure>
<UnitPrice>
<Money currency="USD">30</Money>
</UnitPrice>
<Distribution>
<Accounting name="Buyer assigned accounting code 1">
<AccountingSegment id="ABC123456789">
<Name xml:lang="en">Facilities</Name>
11 Invoices
<Description xml:lang="en">Facilities</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="USD">3000</Money>
</Charge>
</Distribution>
<Extrinsic name="serviceLocation">
<Contact role="serviceLocation">
<Name xml:lang="en">Jerry Seinfeld : NEW YORK</Name>
11 Invoices
<PostalAddress>
<Street>2345 S. SAN PEDRO</Street>
<City>New York</City>
<State>NY</State>
<PostalCode>10002</PostalCode>
<Country isoCountryCode="US">USA</Country>
</PostalAddress>
</Contact>
</Extrinsic>
</InvoiceDetailServiceItem>
<!--- timecard invoice service line item -->
<InvoiceDetailServiceItem
invoiceLineNumber = "3" quantity = "12">
<InvoiceDetailServiceItemReference lineNumber = "1">
<Classification domain = "UNSPC">80111604</Classification>
<Description xml:lang = "en">Assistant AA101</Description>
</InvoiceDetailServiceItemReference>
<SubtotalAmount>
<Money currency = "USD">1200</Money>
</SubtotalAmount>
<Period startDate = "2001-04-01T12:00:00-00:00"
endDate = "2001-04-30T12:00:00-00:00"/>
<UnitRate>
<Money currency = "USD">100.00</Money>
<UnitOfMeasure>HUR</UnitOfMeasure>
<TermReference termName=”payCode” term=”regular”/>
</UnitRate>
<GrossAmount>
<Money currency = "USD">1200</Money>
</GrossAmount>
<NetAmount>
<Money currency = "USD">1200</Money>
</NetAmount>
<InvoiceLaborDetail>
<Contractor>
<ContractorIdentifier domain="ContractorId">
Contr1234
</ContractorIdentifier>
<Contact>
<Name>John Doe</Name>
</Contact>
</Contractor>
<JobDescription>
Assistant left-handed broom closet monitor.
</JobDescription>
<Supervisor>
<Contact>
<Name>Jill Hill</Name>
</Contact>
</Supervisor>
<InvoiceTimeCardDetail>
<TimeCardIDInfo timeCardID="TC123”>
11 Invoices
</InvoiceTimeCardDetail>
</InvoiceLaborDetail>
</InvoiceDetailServiceItem>
</InvoiceDetailOrder>
<InvoiceDetailOrder>
<InvoiceDetailOrderInfo>
<MasterAgreementIDInfo agreementID="MA-1235"/>
</InvoiceDetailOrderInfo>
<!--- milestone invoicing -->
11 Invoices
<InvoiceDetailServiceItem invoiceLineNumber="4">
<InvoiceDetailServiceItemReference lineNumber="1">
<Classification domain="UNSPC">78102694</Classification>
<Description xml:lang="en">
Market Research preliminary analysis
</Description>
</InvoiceDetailServiceItemReference>
<SubtotalAmount>
<Money currency="USD">5000</Money>
</SubtotalAmount>
11 Invoices
</InvoiceDetailServiceItem>
</InvoiceDetailOrder>
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="USD">13713</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">287</Money>
<Description xml:lang="en">total tax</Description>
<TaxDetail purpose="tax"
11 Invoices
category="State sales tax"
percentageRate="8">
<TaxableAmount>
<Money currency="USD">5713</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">200</Money>
</TaxAmount>
<TaxLocation xml:lang="en">CA</TaxLocation>
11 Invoices
</TaxDetail>
<TaxDetail purpose="tax"
category="Federal sales tax"
percentageRate="2">
<TaxableAmount>
<Money currency="USD">5713</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">87</Money>
</TaxAmount>
11 Invoices
</TaxDetail>
</Tax>
<GrossAmount>
<Money currency="USD">14000.00</Money>
</GrossAmount>
<NetAmount>
<Money currency="USD">14000.00</Money>
</NetAmount>
<DueAmount>
<Money currency="USD">14000.00</Money>
</DueAmount>
</InvoiceDetailSummary>
</InvoiceDetailRequest>
</Request>
</cXML>
Marketplace Invoice
This example shows the header of an invoice sent to a marketplace. It illustrates how
to generate correct credentials for a marketplace.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/
InvoiceDetail.dtd">
<cXML payloadID="[email protected]"
timestamp="2001-04-20T23:59:45-07:00">
<Header>
<From>
<!-- Supplier -->
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
</Credential>
</From>
<To>
<!-- Marketplace -->
<Credential domain="AribaNetworkUserId" type="marketplace">
<Identity>[email protected]</Identity>
</Credential>
<!-- Marketplace Member Organization -->
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
</Credential>
</To>
<Sender>
<!-- Supplier -->
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Our Nifty Invoice Generator V1.0</UserAgent>
</Sender>
11 Invoices
</Header>
<Request>
<InvoiceDetailRequest>
11 Invoices
11 Invoices
11 Invoices
11 Invoices
11 Invoices
12 Catalogs
Catalogs are documents that convey product and service content to buying
organizations. Suppliers use them to describe the products and services they offer and
their prices.
12 Catalogs
• Catalog Definitions
• Type Definitions
• Subscription Management Definitions
• Catalog Upload Transaction
Catalog Definitions
The cXML catalog definitions consist of two main elements: Supplier and Index. These
elements describe data intended for persistent or cached use within a hub or a buying
organization’s procurement system.
• Supplier—Contains basic data about the supplier, such as address, contact, and
ordering information.
• Index—Describes data about the supplier’s inventory of goods and services, such as
12 Catalogs
description, part numbers, and classification codes.
Note that Index uses several sub-elements to describe line items in suppliers’
inventories. Suppliers can send either price information for caching within buyers’
systems or PunchOut information to enable buyers to punch out to remote websites
for pricing and other information.
12 Catalogs
These elements are unusual in cXML because they commonly appear as the top level
element in a compliant XML document. In fact, Index rarely appears elsewhere in a
cXML document.
Supplier
The Supplier element encapsulates a named supplier of goods or services. It must have
a Name element and a SupplierID element. Additionally, it describes optional address
and ordering information for the supplier:
Supplier
corporateURL
storeFrontURL
Name
*
xml:lang +
SupplierID SupplierLocation
domain
value
OrderMethods
+ ?
Address
OrderTarget OrderMethod Contact
code
Phone|Email|Fax|URL
?
OrderProtocol
12 Catalogs
<Supplier>
<Name xml:lang="en-US">Workchairs </Name>
<SupplierID domain="oracle107">29</SupplierID>
<SupplierID domain="DUNS">76554545</SupplierID>
<SupplierLocation>
<Address>
<Name xml:lang="en-US">Main Office</Name>
<PostalAddress>
…
12 Catalogs
</PostalAddress>
<Email>[email protected]</Email>
<Phone name="Office">
…
</Phone>
<Fax name="Order">
…
</Fax>
<URL>http://www.workchairs.com/Support.htm</URL>
</Address>
<OrderMethods>
<OrderMethod>
<OrderTarget>
<URL>http://www.workchairs.com/cxmlorders</URL>
</OrderTarget>
</OrderMethod>
<Contact>
<Name xml:lang="en-US">Mr. Smart E. Pants</Name>
<Email>[email protected]</Email>
12 Catalogs
<Phone name="Office">
…
</Phone>
</Contact>
</OrderMethods>
</SupplierLocation>
</Supplier>
SupplierLocation
12 Catalogs
Some suppliers conduct business from more than one location. A SupplierLocation
element can be used for each location. This element also encapsulates how that
location does business or the ways that it can accept orders. A SupplierLocation element
contains an Address and a set of OrderMethods.
12 Catalogs
The OrderMethods element is a grouping of one or more OrderMethod elements for the
given SupplierLocation element. The position of OrderMethods in the list is significant—
the first element is the preferred ordering method, the second element is the next
priority, and so on in decreasing order of preference.
Index
This element is the root element for updating catalogs within buying organizations’
procurement systems.
An Index element is associated with a single supplier. The Index element allows for a
list of supplier IDs, where each ID is considered a synonym for that supplier.
The Index contains one or more IndexItem elements. The IndexItem element contains
elements that add or delete from the buying organization’s cached catalog. The
following example shows an outline of an Index element:
<Index loadmode="Incremental">
<SupplierID> ... </SupplierID>
...
<IndexItem>
<IndexItemAdd>
<ItemID>
...
</ItemID>
<ItemDetail>
...
</ItemDetail>
<IndexItemDetail>
<SearchGroupData>
...
</SearchGroupData>
...
</IndexItemDetail>
</IndexItemAdd>
</IndexItem>
<IndexItem>
<IndexItemDelete>
<ItemID>
...
12 Catalogs
</ItemID>
</IndexItemDelete>
</IndexItem>
<IndexItem>
<IndexItemPunchout>
<ItemID>
...
</ItemID>
<PunchOutDetail>
12 Catalogs
<SearchGroupData>
...
</SearchGroupData>
...
</PunchOutDetail>
</IndexItemPunchout>
</IndexItem>
</Index>
The mode in which the target application should load the Index:
12 Catalogs
IndexItem, IndexItemAdd, IndexItemDelete, and IndexItemPunchout
The IndexItem element is a container for the list of items in an index. It contains three
types of elements:
12 Catalogs
• IndexItemDelete—Removes an item from the index. It contains an ItemID element
identifying the item.
• IndexItemPunchout—Inserts an item for initiating puchout to the supplier's website. It
contains a PunchoutDetail element and an ItemID element. It is similar to an
IndexItemAdd element except that it does not require price information. Buyers
acquire item details in real-time from the supplier’s website.
12 Catalogs
ItemID
If SupplierPartID does not uniquely identify the item, the supplier should use
SupplierPartAuxiliaryID to specify an “auxiliary” key that identifies the part uniquely
when combined with the SupplierID and SupplierPartID. For example, a supplier might
use the same SupplierPartID for an item, but have a different price for units of “EA” and
“BOX”. In this case, a reasonable SupplierPartAuxiliaryID for the two items might be
“EA” and “BOX.”
SupplierPartAuxiliaryID could
also be used as a supplier cookie, enabling the supplier to
refer to complex configuration or part data. It could contain all the data necessary for
the supplier to reconstruct what the item in question is in their computer system (a
basket or cookie of data that makes sense only to the supplier). For more information,
see “Buyer and Supplier Cookies” on page 98.
ItemDetail
ItemDetail contains detailed information about an item, or all the data that a user might
want to see about an item beyond the essentials represented in the ItemID. It must
contain a UnitPrice, a UnitOfMeasure, one or more Description elements, and a Classification,
and it can optionally contain a ManufacturerPartID, a ManufacturerName, a URL, a LeadTime,
and any number of Extrinsic elements. For more information, see “ItemDetail” on page
109.
The optional LeadTime element describes the number of days needed for the buyer to
receive the product. For example:
<LeadTime>14</LeadTime>
Note that in an IndexItemAdd element, duplicate LeadTime information might come from
both ItemDetail, where it is optional, and IndexItemDetail, where it is mandatory. If the
LeadTime elements are defined in both cases, then they should be identical.
IndexItemDetail
12 Catalogs
PunchoutDetail
12 Catalogs
Type Definitions
Types allow type providers such as content aggregators, suppliers, and marketplaces
to extend root catalog item definitions and to define named groupings of commodity-
specific attributes such as parametric types.
Types are named collections of named attributes. Each attribute is further defined in
terms of a type, that is, types can contain other types. Types can also derive from or
extend other types.
Type definitions describe supplemental catalog attributes and parametric data types.
They provide a rich framework for defining parametric types, and they allow the
definition and standardization of parametric types from type provider organizations
independent of index data.
12 Catalogs
Use the SearchGroupData and SearchDataElement elements to specify the actual
parametric data for a given catalog item. SearchGroupData must reference a defined
type, and SearchDataElement specifies data for each type attribute within that type.
TypeProvider
12 Catalogs
TypeProvider specifies the provider of the types being defined, identified by a name and
one or more IDs (for example, NetworkId or DUNS).
The canonical name used to reference the type provider when fully
name
qualifying the name of a type (for example, in a SearchGroupData element
(required)
reference).
12 Catalogs
Name
The Name element is for localized display purposes, allowing different names to be
provided per locale.
OrganizationID
Type
Type elements are named elements containing one or more TypeAttribute elements.
Types can extend (or derive from) other types, thus inheriting their parents’
TypeAttribute elements.
There is one important distinction between type inheritance and standard object-
oriented inheritance models: child TypeAttributes cannot override parent TypeAttributes.
Name
Type names are always scoped by TypeProvider names, allowing for the existence of
multiple type taxonomies. Applications should respect the following notation for a
fully-qualified type name outside a defined TypeProvider scope:
Type Provider Name:Type Name
For example, if an organization named Acme provides a type definition named Pipes,
that type would be referenced as "Acme:Pipes" in SearchGroupData names.
12 Catalogs
Description
You can provide names in multiple locales through the optional Description element
list. The ShortName element within that Description should be used to provide an
alternative locale specific name for the type. The required name attribute should be
used within the SearchGroupData element to reference a given type.
12 Catalogs
TypeAttribute
TypeAttribute elements define attributes within a type. The name attribute is required and
is the name used in the SearchDataElement element. Optional Name elements provide
locale-specific alternative names for this attribute.
TypeAttribute elements
themselves are of a named type, as indicated by the "type"
attribute. The name can be another Type, or a PrimitiveType, defined below.
12 Catalogs
"date" A date of the form yyyy-mm-dd; for example,
2002-01-25
"boolean" A Boolean value; yes, no, 1, 0, true, false, t, or f.
shortTag Alias for this attribute.
Specifies the name of another object in the system that
mappedFrom
implicitly defines this attribute.
isRequired Indicates whether this attribute requires a (non-empty) value.
Indicates that the value for an attribute must be provided
12 Catalogs
(usually by the requisitioner) before the item can be included
isRequiredForOrdering
in an order for the supplier. Typically used for ad-hoc or
partially specified catalog items.
isRefinable Indicates whether this attribute is refinable in search queries.
Name
Description
EnumerationValue
EnumerationValue allows you to optionally specify a set of one or more valid data values
for the TypeAttribute.
For example:
<TypeAttribute name="COLOR"
type="Name"
isRefinable="yes">
<Name xml:lang="en">Color</Name>
<EnumerationValue>Red</EnumerationValue>
<EnumerationValue>Yellow</EnumerationValue>
<EnumerationValue>Black</EnumerationValue>
</TypeAttribute>
Range
Range allows you to optionally specify a range of valid data values for the TypeAttribute.
It contains RangeBegin, RangeEnd, or both.
For example:
<TypeAttribute name="WEIGHT"
type="Number"
12 Catalogs
isRefinable="yes">
<Name xml:lang="en">Weight</Name>
<Range>
<RangeBegin>12</RangeBegin>
<RangeEnd inclusive="no">100</RangeEnd>
</Range>
</TypeAttribute>
12 Catalogs
Both RangeBegin and RangeEnd can optionally specify the attribute inclusive="no", which
excludes the specified beginning or ending value as legal values.
PrimitiveType
PrimitiveType is a named scalar type, where the list of recognized scalar types is given
above. These types are building blocks for defining simple TypeAttributes. For example
a PrimitiveType could define a TypeAttribute that is a string of length 255.
12 Catalogs
Subscription Management Definitions
Intermediaries such as network commerce hubs can manage supplier information and
catalogs used by procurement systems.
This section describes request-response elements for managing supplier data and
catalogs. In all cases, the requests are initiated by the procurement system.
12 Catalogs
This section discusses:
• Supplier Data
• Catalog Subscriptions
12 Catalogs
Supplier Data
Supplier data management uses three types of transactions:
• SupplierList – Returns the names of suppliers with which the buyer has
relationships.
• SupplierData – Returns supplier details.
• SupplierChange – Returns the names of suppliers whose information has changed.
SupplierListRequest
SupplierListRequest requests a list of the suppliers with whom the buyer has established
trading relationships.
<Request>
<SupplierListRequest/>
</Request>
SupplierListResponse
SupplierListResponse lists the suppliers with whom the buyer has established trading
relationships.
<Response>
<Status code="200" text="OK"/>
<SupplierListResponse>
<Supplier corporateURL=http://www.workchairs.com
storeFrontURL="http://www.workchairs.com">
<Name xml:lang="en-US">Workchairs, Inc.</Name>
<Comments xml:lang="en-US">this is a cool company</Comments>
<SupplierID domain="DUNS">123456</SupplierID>
</Supplier>
<Supplier corporateURL=http://www.computersRus.com
storeFrontURL="http://www.computersRus.com">
<Name xml:lang="en-US">Computers R us</Name>
<Comments xml:lang="en-US">another cool company</Comments>
<SupplierID domain="DUNS">123456789</SupplierID>
</Supplier>
</SupplierListResponse>
</Response>
SupplierDataRequest
12 Catalogs
<SupplierDataRequest>
<SupplierID domain="DUNS">123456789</SupplierID>
</SupplierDataRequest>
</Request>
SupplierDataResponse
12 Catalogs
<Response>
<Status code="200" text="OK"/>
<SupplierDataResponse>
<Supplier corporateURL=http://www.workchairs.com
storeFrontURL="http://www.workchairs.com">
<Name xml:lang="en-US">Workchairs, Inc.</Name>
<Comments xml:lang="en-US">this is a cool company</Comments>
<SupplierID domain="DUNS">123456</SupplierID>
<SupplierLocation>
<Address>
<Name xml:lang="en-US">Main Office</Name>
<PostalAddress>
<DeliverTo>Bob A. Worker</DeliverTo>
<Street>123 Front Street</Street>
<City>Toosunny</City>
<State>CA</State>
<PostalCode>95000</PostalCode>
<Country isoCountryCode="US">USA</Country>
</PostalAddress>
12 Catalogs
<Email>[email protected]</Email>
<Phone name="Office">
<TelephoneNumber>
<CountryCode
isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>800</AreaOrCityCode>
<Number>5551212</Number>
</TelephoneNumber>
</Phone>
<Fax name="Order">
12 Catalogs
<TelephoneNumber>
<CountryCode
isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>408</AreaOrCityCode>
<Number>5551234</Number>
</TelephoneNumber>
</Fax>
<URL>http://www.workchairs.com/Support.htm</URL>
</Address>
<OrderMethods>
12 Catalogs
<OrderMethod>
<OrderTarget>
<URL>http://www.workchairs.com/cxmlorder</URL>
</OrderTarget>
<OrderProtocol>cXML</OrderProtocol>
</OrderMethod>
</OrderMethods>
</SupplierLocation>
</Supplier>
</SupplierDataResponse>
</Response>
For information about the Supplier element, see “Supplier” on page 278.
SupplierChangeMessage
This message relies on the GetPending transaction. The buying organization sends a
GetPendingRequest to query for waiting messages. If the network commerce hub has a
message waiting, it includes it within the GetPendingResponse. For more information,
see Chapter 13, “Get Pending/Data Download Transaction.”
<Message>
<SupplierChangeMessage type="new">
<Supplier corporateURL=http://www.workchairs.com
storeFrontURL="http://www.workchairs.com">
<Name xml:lang="en-US">Workchairs, Inc.</Name>
<Comments xml:lang="en-US">this is a cool company</Comments>
<SupplierID domain="DUNS">123456</SupplierID>
<SupplierLocation>
<Address>
<Name xml:lang="en-US">Main Office</Name>
<PostalAddress>
<DeliverTo>Bob A. Worker</DeliverTo>
<Street>123 Front Street</Street>
<City>Toosunny</City>
<State>CA</State>
<PostalCode>95000</PostalCode>
<Country isoCountryCode="US">USA</Country>
</PostalAddress>
<Email>[email protected]</Email>
<Phone name="Office">
<TelephoneNumber>
<CountryCode
isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>800</AreaOrCityCode>
<Number>5551212</Number>
</TelephoneNumber>
</Phone>
12 Catalogs
<Fax name="Order">
<TelephoneNumber>
<CountryCode
isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>408</AreaOrCityCode>
<Number>5551234</Number>
</TelephoneNumber>
</Fax>
<URL>http://www.workchairs.com/Support.htm</URL>
12 Catalogs
</Address>
<OrderMethods>
<OrderMethod>
<OrderTarget>
<URL>http://www.workchairs.com/cxmlorder</URL>
</OrderTarget>
<OrderProtocol>cXML</OrderProtocol>
</OrderMethod>
</OrderMethods>
</SupplierLocation>
</Supplier>
</SupplierChangeMessage>
</Message>
Catalog Subscriptions
Catalog-subscription management uses three types of transactions:
12 Catalogs
• SubscriptionList – Returns the names of catalogs to which the buyer has
subscribed.
• SubscriptionContent – Returns catalog contents.
• SubscriptionChange – Returns the names of catalogs that have changed.
Subscription
The catalog subscription transactions all use the Subscription element to describe
12 Catalogs
metadata about a catalog subscription.
For example:
<Subscription>
<InternalID>1234</InternalID>
<Name xml:lang="en-US">Q2 Prices</Name>
<Changetime>2002-03-12T18:39:09-08:00</Changetime>
<SupplierID domain="DUNS">123456789</SupplierID>
12 Catalogs
<Format version="2.1">CIF</Format>
<Description xml:lang="en-US">The best prices for software</Description>
</Subscription>
ChangeTime The date and time when any aspect of the subscription last changed.
SubscriptionListRequest
SubscriptionListResponse
12 Catalogs
</Subscription>
</SubscriptionListResponse>
</Response>
SubscriptionContentRequest
This element requests the contents of a subscribed catalog. The request includes the
InternalID and SupplierID for the catalog.
12 Catalogs
<Request>
<SubscriptionContentRequest>
<InternalID>1234</InternalID>
<SupplierID domain="DUNS">123456789</SupplierID>
</SubscriptionContentRequest>
</Request>
SubscriptionContentResponse
This element contains the contents of a catalog. The catalog format can be either CIF
(Catalog Interchange Format) or cXML. If it is CIF, it is base64 encoded and included
as the content of a CIFContent element. If it is cXML, the Index element is directly
included.
<Response>
<Status code="200" text="OK"/>
<SubscriptionContentResponse>
<Subscription>
12 Catalogs
<InternalID>1234</InternalID>
<Name xml:lang="en-US">Q2 Software Prices</Name>
<Changetime>1999-03-12T18:39:09-08:00</Changetime>
<SupplierID domain="DUNS">123456789</SupplierID>
<Format version="3.0">CIF</Format>
<Description xml:lang="en-US">The best prices for software</Description>
</Subscription>
<SubscriptionContent filename="april_prices.cif">
<CIFContent>
<!-- base64 encoded data -->
12 Catalogs
ABCDBBDBDBDBDB
...
</CIFContent>
</SubscriptionContent>
</SubscriptionContentResponse>
</Response>
12 Catalogs
SubscriptionChangeMessage
This element signals the buying organization’s procurement system that a subscribed
catalog has changed.
This message relies on the GetPending transaction. The buying organization sends a
GetPendingRequest to query for waiting messages. If the network commerce hub has a
message waiting, it includes it within the GetPendingResponse. For more information,
see Chapter 13, “Get Pending/Data Download Transaction.”
<Message>
<SubscriptionChangeMessage type="new">
<Subscription>
<InternalID>1234</InternalID>
<Name xml:lang="en-US">Q2 Software Prices</Name>
<Changetime>1999-03-12T18:39:09-08:00</Changetime>
<SupplierID domain="DUNS">123456789</SupplierID>
<Format version="2.1">CIF</Format>
</Subscription>
</SubscriptionChangeMessage>
</Message>
The type attribute describes the type of change: new, delete, or update.
The Catalog Upload transaction supports both CIF and cXML catalogs.
CatalogUploadRequest
Sent by suppliers to upload a catalog. It contains the catalog as an
attachment and specifies whether the catalog is new or an update,
and whether to automatically publish it after upload.
12 Catalogs
Response Sent by the network commerce hub to acknowledge the receipt of a
CatalogUploadRequest.
CatalogUploadRequest
The following example shows a CatalogUploadRequest:
12 Catalogs
--kdflkajfdksadjfklasdjfkljdfdsfdkf
MIME header Content-type: text/xml; charset=UTF-8
Content-ID: <[email protected]>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML timestamp="2000-12-28T16:56:03-08:00" payloadID="[email protected]">
<Header>
<From>
<Credential domain="DUNS">
<Identity>123456789</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkID">
ID of network hub <Identity>AN01000000001</Identity>
</Credential>
</To>
<Sender>
<Credential domain="DUNS">
<Identity>123456789</Identity>
12 Catalogs
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>My Homemade Catalog Manager V2.0</UserAgent>
</Sender>
</Header>
<Request>
<CatalogUploadRequest operation="update">
<CatalogName xml:lang="en">Winter Prices</CatalogName>
<Description xml:lang="en">This catalog contains our premiere-level prices for
office chairs and other durable furniture.</Description>
12 Catalogs
<Attachment>
ID of MIME attachment <URL>cid:[email protected]</URL>
</Attachment>
<Commodities>
<CommodityCode>52</CommodityCode>
</Commodities>
<AutoPublish enabled="true"/>
<Notification>
<Email>[email protected]</Email>
<URLPost enabled="true"/>
12 Catalogs
</Notification>
</CatalogUploadRequest>
</Request>
</cXML>
--kdflkajfdksadjfklasdjfkljdfdsfdkf
MIME attachment Content-type: text/plain; charset=US-ASCII
header Content-Disposition: attachment; filename=PremiereCatalog.cif
Content-ID: <[email protected]>
Content-length: 364
CIF_I_V3.0
LOADMODE: F
CODEFORMAT: UNSPSC
CURRENCY: USD
SUPPLIERID_DOMAIN: DUNS
ITEMCOUNT: 3
TIMESTAMP: 2001-01-15 15:25:04
DATA
942888710,34A11,C11,"Eames Chair, Black Leather",11116767,400.00,EA,3,"Fast
MFG",,,400.00
942888710,56A12,C12,"Eames Ottoman, Black Leather",11116767,100.00,EA,3,"Fast
MFG",,,100.00
942888710,78A13,C13,"Folding Chair, Grey Stackable",11116767,25.95,EA,3,"Fast
MFG",,,25.95
ENDOFDATA
MIME trailer --kdflkajfdksadjfklasdjfkljdfdsfdkf--
CatalogUploadRequest Element
12 Catalogs
CatalogName
CatalogName specifies the name of the uploaded catalog. This value is the user-visible
name, not the file name of the catalog.
12 Catalogs
Language codes are defined in the XML 1.0 Specification (at
www.w3.org/TR/1998/REC-xml-19980210.html). In the most
common case, this includes an ISO 639 Language Code and,
optionally, an ISO 3166 Country Code separated by a hyphen.
xml:lang The recommended cXML language code format is xx[-YY[-zzz]*]
where xx is an ISO 639 Language code, YY is an ISO 3166
Country Code, and zzz is an IANA or private subcode for the
language in question. Again, use of the Country Code is always
recommended. By convention, the language code is lowercase
and the country code is uppercase. This is not required for correct
matching of the codes.
Description
Description briefly describes the catalog contents. Buying organizations can search and
view this information.
12 Catalogs
Specifies the language used for the catalog name.
xml:lang For more information, see the description of xml:lang for
CatalogName, above.
Attachment
The Attachment element contains one URL element with the scheme “cid:”.
12 Catalogs
For more information about attachments, see “Attaching Your Catalog” on page 299.
Commodities
Commodities specifies
the top-level commodity codes for the items in your catalog.
Buying organizations use these codes to search for new catalogs.
AutoPublish
You can automatically publish only if both of the following requirements are met:
1. A previous version of the catalog exists in your account and you are
performing an update operation.
2. The previous version is in the “published” state. It must have been published
private (with a list of buyers) or public.
Notification
Notification sends
catalog-status notifications through e-mail or cXML POST. For
examples of these messages, see “Receiving Later Catalog Status” on page 300.
Notification contains either one Email element or one URLPost element, or both elements.
Email specifies
the mailbox to the newtork commerce hub e-mails status messages.
You can use only one Email element, and it can contain only one e-mail address.
URLPost specifies whether the newtork commerce hub sends catalog status messages
as cXML StatusUpdateRequest documents.
12 Catalogs
URLPost has the following attribute
12 Catalogs
Attaching Your Catalog
Send your catalog attached to the CatalogUploadRequest document. Large catalogs must
be zipped to compress them before uploading.
The referenced catalog file must reside within a multipart MIME envelope with the
cXML document. A cXML requirement for this envelope (over the basics described
in RFC 2046 “Multipurpose Internet Mail Extensions (MIME) Part Two: Media
Types”) is the inclusion of Content-ID headers with the attached file.
12 Catalogs
attachment method.
The Attachment element contains only a reference to the external MIME part of the
attachment. Attachment contains a single URL with the scheme “cid:”.
For more information about attachments in cXML, see the discussion of the
“Attachment” on page 124.
12 Catalogs
Response
After you send a CatalogUploadRequest, the network commerce hub replies with a
standard cXML Response document:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
12 Catalogs
<cXML payloadID="[email protected]"
timestamp="2001-01-23T19:21:47-08:00">
<Response>
<Status code="201" text="Accepted">The catalog upload request is
processing</Status>
</Response>
</cXML>
If you include the Notification element to request later catalog-status notification, the
network sends a message when the catalog reaches its final status. The possible final
catalog states are:
12 Catalogs
Validated The catalog contains no syntax errors.
BadZipFormat The zip format is incorrect.
HasErrors The catalog contains syntax errors, and it cannot be published.
Published The catalog has been published (private or public).
URLPost
12 Catalogs
commerce hub:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
12 Catalogs
<Credential domain="NetworkID">
<Identity>AN01000000001</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>ANValidator</UserAgent>
</Sender>
</Header>
<Request>
<StatusUpdateRequest>
<DocumentReference payloadID="123456669131--
12 Catalogs
[email protected]"></DocumentReference>
<Status text="Success" code="200">
Validated
</Status>
</StatusUpdateRequest>
</Request>
</cXML>
12 Catalogs
Download Transaction
13 Get Pending/Data
Transaction
Some organizations do not have an HTTP entry point for receiving cXML documents
posted by entities outside of their corporate firewalls. The cXML get pending and data
Download Transaction
download transactions enables these organizations to poll for waiting documents and
13 Get Pending/Data
download them.
Download Transaction
13 Get Pending/Data
• DataRequest
• DataResponse
GetPendingRequest
This element pulls a set of messages that are waiting for the requester. The
MessageType element and the lastReceivedTimestamp and maxMessages attributes control
the type and count of the fetched documents.
Upon receiving the request, the receiver returns the oldest documents, of the specified
types, with timestamps equal to or later than the specified timestamp. If there are
multiple documents meeting this criterion, they are returned, subject to the
maxMessages attribute. The queuing system discards all pending documents of the
specified message types with timestamps earlier than the specified timestamp.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[email protected]" timestamp="2005-01-
13T00:00:16+00:00">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN13000000259</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN13000000259</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Our Buyer App 1.0</UserAgent>
</Sender>
</Header>
<Request>
<GetPendingRequest lastReceivedTimestamp="2005-03-12T18:39:09-08:00"
13 Get Pending/Data
maxMessages="5">
<MessageType>SubscriptionChangedMessage</MessageType>
</GetPendingRequest>
</Request>
</cXML>
Download Transaction
13 Get Pending/Data
GetPendingResponse
The server returns a Response document in the same HTTP connection. If the Response
contains no GetPendingResponse document, no documents are waiting. If it contains a
GetPendingResponse document, there are documents waiting.
No Documents Waiting
Download Transaction
13 Get Pending/Data
The following example indicates that there are no waiting documents of the requested
message type:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML timestamp="2005-01-12T16:00:25-08:00" payloadID="1105574420906--
[email protected]">
<Response>
Download Transaction
13 Get Pending/Data
<Status code="200" text="OK"/>
</Response>
</cXML>
Documents Waiting
If there is a GetPendingResponse document, there are documents waiting. The
GetPendingResponse document can contain waiting documents in-line or contain a
DataAvailableMessage element that refers to waiting documents.
Documents In-Line
The server can send waiting document in-line in the GetPendingResponse document, in
which case the client does not need to use the data download transaction.
<Response>
<Status code="200" text="OK"/>
<GetPendingResponse>
<cXML xml:lang="en-US"
payloadID="[email protected]"
timestamp=""2005-01-12T16:00:25-08:00">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN13000000259</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
</Credential>
<UserAgent>Network Hub 2.0</UserAgent>
</Sender>
</Header>
<Message>
<SubscriptionChangeMessage type="new">
<Subscription>
<InternalID>1234</InternalID>
<Name xml:lang="en-US">Q2 Prices</Name>
<Changetime>2002-03-12T18:39:09-08:00</Changetime>
<SupplierID domain="DUNS">123456789</SupplierID>
<Format version="2.1">CIF</Format>
</Subscription>
</SubscriptionChangeMessage>
</Message>
</cXML>
</GetPendingResponse>
</Response>
</cXML>
13 Get Pending/Data
Documents Referenced through DataAvailableMessage
Download Transaction
13 Get Pending/Data
Mail Extensions (MIME) attachments, not embedded in cXML documents.
There are several reasons why servers might use the MIME attachment method used
by the data download transaction instead of the in-line method used by the
GetPendingResponse document:
• MIME can transport documents that use different DTDs or DTD versions than the
GetPendingResponse document.
Download Transaction
• MIME attachments are simpler to process than nested documents with multiple
13 Get Pending/Data
parent and child elements.
• MIME is better for large documents, which transport as separate files, rather than
one very large document.
Download Transaction
13 Get Pending/Data
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML timestamp="2005-01-12T16:00:18-08:00" payloadID="1105574420906--
[email protected]">
<Response>
<Status code="200" text="OK"/>
<GetPendingResponse>
<cXML timestamp="2005-01-12T16:00:18-08:00"
payloadID="[email protected]">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN13000000259</Identity>
</Credential>
</To>
<Sender>
Download Transaction
13 Get Pending/Data
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
<UserAgent>ANCXMLDispatcher</UserAgent>
</Credential>
</Sender>
</Header>
<Message>
<DataAvailableMessage>
<InternalID domain="PendingMessages">3738</InternalID>
</DataAvailableMessage>
</Message>
</cXML>
</GetPendingResponse>
</Response>
</cXML>
DataRequest
After you obtain a DataAvailableMessage, use its internal ID value to download the
waiting documents by sending a cXML DataRequest document. For example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[email protected]" timestamp="2005-01-
13T00:00:21+00:00">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN13000000259</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN13000000259</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Our Buyer App 1.0</UserAgent>
</Sender>
</Header>
<Request>
<DataRequest>
13 Get Pending/Data
<InternalID domain="PendingMessages">3738</InternalID>
</DataRequest>
</Request>
</cXML>
Download Transaction
13 Get Pending/Data
DataResponse
The server responds with a cXML DataResponse document and the requested
documents together in a MIME envelope in the same HTTP connection. The Content-
Type HTTP header defines the MIME boundary.
Download Transaction
13 Get Pending/Data
Content-Type: multipart/mixed; boundary="----=_Part_0_10550230.1105574425445"
------=_Part_0_10550230.1105574425445
Content-Type: text/xml; charset=UTF-8
Content-ID: <[email protected]>
Download Transaction
13 Get Pending/Data
<Response>
<Status code="200" text="OK"/>
<DataResponse>
<Attachment>
<URL>cid:[email protected]</URL>
</Attachment>
</DataResponse>
</Response>
</cXML>
------=_Part_0_10550230.1105574425445
Content-Type: text/xml; charset=UTF-8
Content-ID: <[email protected]>
<Credential domain="NetworkId">
<Identity>AN12000000259</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN13000000259</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN01000000001</Identity>
</Credential>
<UserAgent>Network Hub 2.0</UserAgent>
</Sender>
</Header>
<Request deploymentMode="production">
<StatusUpdateRequest>
<DocumentReference payloadID="[email protected]"/>
<Status code="200" message="OK"/>
</StatusUpdateRequest>
</Request>
</cXML>
------=_Part_0_10550230.1105574425445--
You do not need to authenticate documents downloaded through the data download
transaction if they come from a trusted source.
14 Provider PunchOut
Transaction
Provider PunchOut enables applications to punch out to a remote application that
supplies some service to the originating application, such as credit card validation,
single login, or self registration.
cXML documents provide a means for the originator and the provider to
14 Provider PunchOut
communicate during this transaction. These cXML documents are
Transaction
ProviderSetupRequest, ProviderSetupResponse, and ProviderDoneMessage and are tailored
specifically to handle the interaction between an originating application and a service
provider. They pass details such as what service is to be provided, session
information, the return URL of the originator, and status or followup information.
• Message Flow
14 Provider PunchOut
• ProviderSetupRequest Document
Transaction
• ProviderSetupResponse Document
• ProviderDoneMessage Document
14 Provider PunchOut
Transaction
14 Provider PunchOut
Transaction
Message Flow
The order of cXML message flow in the Provider PunchOut transaction is shown in
the following diagram.
Network
ProviderSetupRequest Document
The ProviderSetupRequest document initiates a Provider PunchOut transaction and
passes several items of information to the provider, including information about the
member organization and user, the return URL, and which service is being requested.
The document contains two sections, one specified by a Header element, the other by a
Request element. The Header contains credential information about the user and the
requesting organization and the Request contains the actual ProviderSetupRequest
element that contains information needed to initiate the Provider PunchOut.
Header
The Header portion of the document contains addressing and authentication
information. The following sample is the header portion taken from a
ProviderSetupRequest document. The UserAgent element contains the digital signature of
Transaction
the provider; a string that corresponds to the application and the version making the
request. For example, “www.triton.com” or “Procurement Application 7.0.” The two
parties must agree on a common certificate format and authority.
<Header>
<From>
<!-- Triton Bank -->
14 Provider PunchOut
<Credential domain="NetworkId" type="marketplace">
Transaction
<Identity>AN01000001709</Identity>
</Credential>
<Credential domain="triton.com">
<Identity>9999</Identity>
</Credential>
</From>
<To>
<!-- Marketplace -->
14 Provider PunchOut
<Credential domain="NetworkId">
<Identity>AN01000000003</Identity>
Transaction
</Credential>
</To>
<Sender>
<!-- Triton Bank -->
<Credential domain="NetworkId">
<Identity>AN01000001709</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
14 Provider PunchOut
<UserAgent>www.triton.com</UserAgent>
</Sender>
Transaction
</Header>
Because the Header element is similar for each message type, see “Header” on page 42
for specifics on how to construct this portion of the message.
Request
14 Provider PunchOut
The Request portion of the document contains a ProviderSetupRequest, which has several
items of information about the transaction from the originator, including a cookie to
Transaction
track the session for the originator, a return URL, what service is being requested
from the provider, and other information contingent upon the type of service and the
provider.
<Request>
<ProviderSetupRequest>
<OriginatorCookie>iTRk9bG49EJOGhJC</OriginatorCookie>
<BrowserFormPost>
<URL>https://www.triton.com/providerdone.asp</URL>
</BrowserFormPost>
<SelectedService>signin</SelectedService>
<Extrinsic name="Brand">Triton</Extrinsic>
<Extrinsic name="User">
<Identity>0001</Identity>
</Extrinsic>
<Extrinsic name="QueryString">req=R532&login=gtou&</Extrinsic>
</ProviderSetupRequest>
</Request>
The following table provides guidelines for the structure of the request section of the
Provider PunchOut message.
Request
ProviderSetupRequest
OriginatorCookie
OriginatorCookie is tied to the user’s session on the requestor’s site and is returned to the
requestor later with the ProviderDoneMessage. This implements a one-time key allowing
the user to return to the same session on the originating application.
Transaction
BrowserFormPost URL
The originating application provides the BrowserFormPost location so that the provider
can display a “Done” button, and provide information, such as a Status, at the end of
the interactive session. Inclusion should lead to a ProviderDoneMessage document
being sent from the provider at the end of each session. URL contains the location on
14 Provider PunchOut
the requestor’s site to return the user when they have finished at the provider site.
Transaction
SelectedService
Identifies the service requested by the originating application and offered by the
provider.
Extrinsic
14 Provider PunchOut
The extrinsics for the Provider PunchOut depend upon what service the provider
Transaction
supplies. Please see specific documentation for your specific ProviderSetupRequest.
Note: XML content, elements, and their attributes must be defined in the
cXML DTD or XML escaped.
Sample
14 Provider PunchOut
To demonstrate a typical ProviderSetupRequest document, the following is a request
Transaction
from a marketplace member named Triton Bank, to a marketplace.
<cXML timestamp="2000-07-11T15:03:14-07:00" payloadID="963352994214--
[email protected]”>
<Header>
<From>
<Credential domain="NetworkId" type="marketplace">
<Identity>AN01000001709</Identity>
14 Provider PunchOut
</Credential>
<Credential domain="triton.com">
Transaction
<Identity>9999</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN01000000003</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN01000001709</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>www.triton.com</UserAgent>
</Sender>
</Header>
<Request>
<ProviderSetupRequest>
<OriginatorCookie>iTRk9bG49EJOGhJC</OriginatorCookie>
<BrowserFormPost>
<URL>https://www.triton.com/providerdone.asp</URL>
</BrowserFormPost>
<SelectedService>signin</SelectedService>
<Extrinsic name="Brand">Triton</Extrinsic>
<Extrinsic name="User>
<Identity>0001</Identity>
</Extrinsic>
<Extrinsic name="QueryString">req=R532&login=gtou&</Extrinsic>
</ProviderSetupRequest>
</Request>
</cXML>
ProviderSetupResponse Document
The ProviderSetupResponse document notifies the originating application of the results
of the request. Status and start page information is included.
<cXML payloadID="[email protected]"
xml:lang="en-US" timestamp="2000-03-12T18:40:15-08:00">
<Response>
<Status code="200" text="OK"/>
<ProviderSetupResponse>
<StartPage>
<URL>http://[email protected]/enter?23423SDFSDF23</URL>
</StartPage>
</ProviderSetupResponse>
</Response>
</cXML>
The following table provides guidelines for the structure of the ProviderSetupResponse
document of the Provider PunchOut transaction.
Transaction
Status 1 Response None code, text
ProviderSetupReponse 1 Response StartPage None
StartPage 1 ProviderSetupReponse URL None
URL 1 StartPage None None
14 Provider PunchOut
Response
Transaction
Contains the Status and ProviderSetupResponse elements.
Status
Provides information on the success or failure of the provider request. The content of
the Status element can be any data needed by the requestor and can describe the error
in more detail. Status has the following attributes:
14 Provider PunchOut
Transaction
The status code of the request. This follows the HTTP status code model.
code
For example, 200 represents a successful request.
The text of the status message. This text aids user readability in logs, and
text it consists of canonical strings in English.
For a 200/OK status code, there might be no data. However, for a 500/Internal Server
Error status code, it is strongly recommended that the actual XML parse error or
application error be presented. This error allows better one-sided debugging and inter-
14 Provider PunchOut
operability testing.
Transaction
The provider should not include the ProviderSetupResponse element unless the status
code is in the 200 range. See “Status” on page 47 for a list of all possible status code
values.
ProviderSetupResponse
14 Provider PunchOut
If the request was successful, the ProviderSetupResponse element is included in the
response document and contains the StartPage and URL elements which indicate where
Transaction
the user should be redirected.
StartPage URL
This element contains a URL element that specifies the URL to pass to the browser to
initiate the Provider PunchOut browsing session requested in the ProviderSetupRequest
element. This URL must contain enough state information to bind to a session context
on the provider website.
Sample
The following ProviderSetupResponse document is in reply to Triton Bank from a
provider from the previous ProviderSetupRequest section.
<cXML payloadID="[email protected]"
xml:lang="en-US" timestamp="2000-03-12T18:40:15-08:00">
<Response>
<Status code="200" text="OK"/>
<ProviderSetupResponse>
<StartPage>
<URL>http://[email protected]/enter?23423SDFSDF23</URL>
</StartPage>
</ProviderSetupResponse>
</Response>
</cXML>
ProviderDoneMessage Document
The ProviderDoneMessage document contains any information the originating
application must know about the completed operation at the provider site.
Header
The ProviderDoneMessage Header section is similar to the header sections in the Request
and Response messages; however, because this message is sent with a Form Post, you
should not include a SharedSecret in the Sender element. The UserAgent element
contains the digital signature of the provider. The two parties must agree on a
common certificate format and authority.
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN01000000003</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>AN01000001709</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN01000000003</Identity>
</Credential>
Transaction
<UserAgent>Purchase</UserAgent>
</Sender>
</Header>
Because the Header element is similar for each message type, see “Header” on page 42
for the specifics on how to construct this portion of the message.
14 Provider PunchOut
Message
Transaction
The Message portion of the document contains the ProviderDoneMessage element, which
contains any information requested by the originating application, and information to
return to the user to their session at the originating application’s site.
<Message>
<Status code="200" text="OK"/>
14 Provider PunchOut
<ProviderDoneMessage>
<OriginatorCookie>c546794949</OriginatorCookie>
Transaction
<ReturnData name="method">
<ReturnValue>Triton.transact</ReturnValue>
<Name xml:lang="en-US">Triton OM transact</Name>
</ReturnData>
</ProviderDoneMessage>
</Message>
The following table details guidelines for the structure of the message section of the
14 Provider PunchOut
ProviderDoneMessage document.
Transaction
Element Instances Parent Elements Child Elements Attributes
Message 1 None Status, None
ProviderDoneMessage
Status 1 Message None text, code
ProviderDoneMessage 1 Message OriginatorCookie, None
ReturnData,
ReturnValue,
14 Provider PunchOut
Name
Transaction
OriginatorCookie 1 ProviderDoneMessage None None
ReturnData Any ProviderDoneMessage ReturnValue, name
Name
ReturnValue 1 ProviderSetupRequest None None
Name 1 BrowserFormPost, None xml:lang
Followup
OriginatorCookie
The same element that was passed in the original ProviderSetupRequest document. It
must be returned here to allow the requesting application to match the
ProviderDoneMessage document with an earlier ProviderSetupRequest document and
return the user to the correct session.
ReturnData
Contains any information the originator must know about the completed operation at
the provider site. The name attribute identifies the type (domain) of the ReturnData to
the requestor.
ReturnValue
A value that is used by the originating application. This value depends on what
service the provider supplies.
Name
An identifier for the data returned. Provides a description for the contents of the
ReturnData element.
When displaying values, keep in mind that Name and ReturnValue have similar
semantics, but different uses in the originating application.
Sample
The provider sends the following ProviderDoneMessage document, which notifies the
originating application, Triton Bank, that the user has finished with their session on
the provider site.
<cXML timestamp="2000-07-11T15:13:28-07:00" payloadID="963353608827--
[email protected]">
<Header>
<From>
<!-- marketplace -->
<Credential domain="NetworkId">
<Identity>AN01000000003</Identity>
</Credential>
</From>
<To>
<!-- Triton bank -->
<Credential domain="NetworkId">
Transaction
<Identity>AN01000001709</Identity>
</Credential>
</To>
<Sender>
<!-- marketplace -->
<Credential domain="NetworkId">
<Identity>AN01000000003</Identity>
14 Provider PunchOut
</Credential>
<UserAgent>Purchase</UserAgent>
Transaction
</Sender>
</Header>
<Message>
<Status code="200" text="OK"/>
<ProviderDoneMessage>
<OriginatorCookie>c546794949</OriginatorCookie>
<ReturnData name="method">
<ReturnValue>Triton.transact</ReturnValue>
14 Provider PunchOut
<Name xml:lang="en-US">Triton OM transact</Name>
</ReturnData>
Transaction
</ProviderDoneMessage>
</Message>
</cXML>
14 Provider PunchOut
Transaction
14 Provider PunchOut
Transaction
Authentication
15 Alternative
Methods
cXML supports alternatives to the shared secret authentication method for verifying
the sender of cXML documents.
Authentication
15 Alternative
Methods
• Message Authentication Code (MAC)
• Auth Transaction
Authentication
15 Alternative
Message Authentication Code (MAC) authentication allows the authentication of
Methods
documents sent directly from a client to a server without passing through a trusted
third party (such as a network commerce hub) for authentication. These documents
contain a credential with an authentication code that can be interpreted only by the
trusted third party and the receiving server, not by the sender.
The format of the Credential element containing the MAC is described in “Credential”
on page 43.
Authentication
15 Alternative
Methods
Overview of MACs
The primary purpose of MACs is to convey receivers’ shared secrets without
revealing them to senders. MACs keep shared secrets secure by encoding them
through a hash.
MACs are as secure as shared secrets. Senders must guard MACs as carefully as
shared secrets. Compromising either piece of information could make trading partners
Authentication
15 Alternative
vulnerable.
Methods
To use MAC authentication, both the trusted third party and the receiver must be able
to compute MACs.
Computation Algorithm
MACs are created by an algorithm that combines data known by both the trusted third
party and the receiver.
cXML specifies the use of the HMAC-SHA1 algorithm described in IETF RFC 2104,
“HMAC: Keyed-Hashing for Message Authentication”.
The HMAC-SHA1 algorithm provide the security required for cXML, and it has been
formally proven to be as secure as the underlying hash algorithm.
If a MAC is stolen, changing the sender’s shared secret has no effect. It is impractical
to expect the sender to contact the receiver out-of-band to invalidate the MAC,
because they might not have an established relationship. To address this problem, a
creation date (creationDate) and an expiration date (expirationDate) are embedded in
MACs. The expiration date limits the damage that can be result from a stolen MAC,
because MACs eventually expire. The shorter the expiration period, the greater the
security afforded. Receivers must reject MACs that are received after their expiration
date.
Receivers can also reject unexpired MACs based on the amount of time that has
elapsed since the creation date. For example, if a receiver receives a MAC that was
created several years ago, but expires tomorrow, the receiver might not wish to accept
the MAC. This decision is left with the implementors of the receiving systems.
It is mandatory for receivers to check that the creation date is in the past and the
expiration date is in the future, and to reject it if either is not the case. However, it is
optional for receivers to check whether the creation date is too long in the past.
Receivers must not only check that MACs are valid, but also that the data
authenticated by MACs is acceptable. Specifically, receivers must validate that they
wish to accept messages from the entities identified by the From and Sender
credentials.
Computation Process
This section describes how to compute a MAC of type="FromSenderCredentials". The
inputs for this MAC type are known only by the trusted third party and the receiver.
The trusted third party uses this computation to generate ProfileResponse Option
elements and the receiving server uses it to validate the CredentialMac element.
Authentication
15 Alternative
Methods
Assembling the Hash Inputs
The MAC function takes two inputs, the data input and the secret key input:
• The data input is the UTF-8-encoded byte representation of each value listed below,
in order, after normalization, with each value terminated by a single null byte
(0x00):
Authentication
15 Alternative
From/Credential@domain
Methods
From/Credential/Identity
Sender/Credential@domain
Sender/Credential/Identity
Sender/Credential/CredentialMac@creationDate
Sender/Credential/CredentialMac@expirationDate
• The secret key input is the cXML shared secret used between the receiver and the
third party.
Authentication
15 Alternative
Methods
Normalizing the Inputs
Normalize the values listed above to remove differences in case and formatting before
computation:
Authentication
15 Alternative
example, “AribaNetworkUserId”. Note that
Methods
“NetworkId” and “DUNS” are not case-
sensitive.
Identity Discard leading or trailing whitespace and an9900000100
use the lowercase version of the string.
creationDate No normalization needed, because they are 2003-01-15T11:42:46-
expirationDate in ISO8601 format described in “Date, 08:00
Time, and other Data Types” on page 39.
Authentication
15 Alternative
MAC Algorithm
2. Use HMAC-SHA1 to hash the above sequence with the receiver’s shared
secret, for example, “abracadabra” (61 62 72 61 63 61 64 61 62 72 61),
which yields:
71 1e 89 a7 3e 7c 9e b8 97 11 10 cd 78 57 fd a0 94 da fd
The trusted third party inserts the final result in ProfileResponse documents it sends to
the entity that will be the client (document sender), and the client inserts it in a
CredentialMac element in all direct communication to the server (document receiver).
ProfileResponse
The following cXML example shows a ProfileResponse sent from a trusted third party
Authentication
15 Alternative
(such as a commerce network hub) to a client (such as a procurement application) so
Methods
the client can send direct requests to the receiving server.
<cXML payloadID="[email protected]"
timestamp="2003-01-15T09:39:09-08:00" xml:lang="en-US">
<Response>
<Status code="200" text="OK"/>
<ProfileResponse>
<Option name="CredentialMac.type">FromSenderCredentials</Option>
Authentication
15 Alternative
<Option name="CredentialMac.algorithm">HMAC-SHA1-96</Option>
<Option name="CredentialMac.creationDate">2003-01-15T08:42:46-0800</Option>
Methods
<Option name="CredentialMac.expirationDate">2003-01-15T11:42:46-0800</Option>
<Option name="CredentialMac.value">cR6Jpz58nriXERDN</Option>
<Transaction requestName="OrderRequest">
<URL>https://service.hub.com/ANCXMLDispatcher.aw/ad/cxml</URL>
</Transaction>
<Transaction requestName="PunchOutSetupRequest">
<URL>https://service.hub.com/AN/cxml</URL>
<Option name="Direct.URL">https://bigsupplier.com/punchout</Option>
Authentication
15 Alternative
<Option name="Direct.AuthenticationMethod.CredentialMac">Yes</Option>
Methods
<Option name="Direct.AuthenticationMethod.Certificate">Yes</Option>
</Transaction>
</ProfileResponse>
</Response>
</cXML>
For more information about the Profile transaction, see Chapter 3, “Profile
Transaction.”
Authentication
15 Alternative
Methods
CredentialMac
The following cXML document fragment shows an example CredentialMac element as
it would be inserted by the client in documents sent directly to the server.
<cXML>
<Header>
<To>
Authentication
15 Alternative
<Credential domain=”DUNS”>
<Identity>049329048</Identity>
Methods
</Credential>
</To>
<From>
<Credential domain=”NetworkId”>
<Identity>AN9900000100</Identity>
</Credential>
</From>
<Sender>
<Credential domain=”NetworkId”>
<Identity>AN9900000100</Identity>
<CredentialMac type=”FromSenderCredentials”
algorithm=”HMAC-SHA1-96”
creationDate=”2003-01-15T08:42:46-0800”>
expirationDate=”2003-01-15T11:42:46-0800”>
cR6Jpz58nriXERDN
</CredentialMac>
<UserAgent>Procure System 3.0</UserAgent>
</Credential>
</Sender>
</Header>
[. . .]
</cXML>
For more information about the CredentialMac element see “Credential” on page 43.
Auth Transaction
The Auth transaction allows receivers to validate organizations’ credentials through a
mutually trusted third party. It should be used to authenticate received documents that
do not contain either a shared secret or a MAC.
The receiver encloses the credential of the sender (the principal) in an AuthRequest
document and sends it to the trusted third party for validation.
If the principal attempts to authenticate using a client digital certificate, the receiver
includes both the principal’s credential and information about the principal’s
certificate in the AuthRequest document. (The receiver obtains this certificate
information from its Webserver or SSL/TLS implementation.)
The trusted third party receives the AuthRequest and looks up the principal’s credential
to see if it is a recognized organization. If the principal’s certificate information was
included, the trusted third party makes sure the certificate is valid and that it matches
the organization associated with the credential.
If the credential (and optional certificate) authenticates, the trusted third party
responds with a positive AuthResponse that contains the validated credential. If the
credential is invalid, the trusted third party responds with an empty cXML response of
status 403 (Forbidden).
The receiver can cache the results of the Auth transaction until the expiration date
indicated in the AuthResponse. During this period, if the principal presents the same
Authentication
15 Alternative
credential and certificate, the receiver need not send another AuthRequest.
Methods
AuthRequest
A request sent to a mutually trusted third party to authenticate an entity.
The following example includes X509 certificate information, which comes from the
requesting entity’s client digital certificate.
Authentication
15 Alternative
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
Methods
<cXML timestamp="2000-12-28T16:56:03-08:00" payloadID="[email protected]">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>AN99000000092</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
Authentication
15 Alternative
<Identity>AN99000000092</Identity>
Methods
</Credential>
</To>
<Sender>
<Credential domain="NetworkId">
<Identity>AN99000000092</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>cXML application 2.0</UserAgent>
Authentication
15 Alternative
</Sender>
</Header>
Methods
<Request>
<AuthRequest>
<Credential domain="DUNS">
<Identity>12345</Identity>
</Credential>
<X509Data>
<X509IssuerSerial>
<X509IssuerName>Verisign</X509IssuerName>
Authentication
15 Alternative
<X509SerialNumber>12345</X509SerialNumber>
Methods
</X509IssuerSerial>
</X509Data>
</AuthRequest>
</Request>
</cXML>
Credential
A cXML credential.
X509Data
X509IssuerSerial
A container for the serial number and issuer name of the X.509 certificate.
X509IssuerName
X509SerialNumber
X509SKI
X509 SubjectName
The distinguished name of the subject of the X.509 certificate. This should be a string
representation of an LDAP distinguished name, as described in RFC 2253.
X509Certificate
X509CRL
AuthResponse
Returns a list of valid credentials of the person entity in the AuthRequest document.
Authentication
15 Alternative
Note that this response is for successful authentications only.
Methods
AuthResponse has the following attribute:
Authentication
15 Alternative
The absence of an expirationDate should be interpreted to forbid caching.
Methods
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[email protected]" timestamp="2001-01-25T15:19:07-08:00">
<Response>
<Status code="200" text="OK"/>
<AuthResponse expirationDate="2002-12-31T09:00:00-08:00">
<Credential domain="DUNS">
<Identity>12345</Identity>
Authentication
15 Alternative
</Credential>
Methods
</AuthResponse>
</Response>
</cXML>
Authentication
15 Alternative
Methods
Authentication
15 Alternative
Methods
Readers of this chapter should be familiar with electronic signature terminology and
concepts such as asymmetric key pairs, certificates, and smart cards.
W3C XML signatures and XAdESs have many options designed to allow for
flexibility. These options are described in the following resources:
16 cXML Digital Signatures
Note that signature and certificate requirements vary according to local laws and
regulations. Prior to implementing a signing system, be sure to learn the requirements
of the relevant locale.
ds:Signature Element
The cXML element contains a space for the ds:Signature element after the Request,
Response, or Message element. The ds:Signature element holds information about what
is being signed, the signature, and the keys used to create the signature. It also has a
place to store additional information such as XAdES extensions or attachment
manifests.
The cXML element also contains a space for the signatureVersion attribute. For more
general information about the cXML envelope, see page 38.
The Message, Request, and Response elements contain an Id attribute. For more
complete information about the Message, Request, and Response elements, see the
relevant sections of Chapter 2.
cXMLSignedInfo
The cXMLSignedInfo element includes cXML-specific details about the signature, and
has the following attributes:
Because some information from the cXML header is significant, it must be signed. To
sign these attributes from the header, repeat the information in a cXMLSignedInfo
element placed within a ds:Object element. The ds:Object must be the first ds:Object in
the signature. For example:
<ds:Object>
The value of the Id attribute must be "cXMLSignedInfo". The values of the signatureVersion
and payloadID attributes must exactly match the values specified in the cXML element,
and the receiver of the document must verify this match. No transforms should be
used in this ds:Reference. This element must be signed via the first ds:Reference object
16 cXML Digital Signatures
<ds:DigestValue>xxxxxxxxxxxxxxxxxxxxxxxxxxx</ds:DigestValue>
</ds:Reference>
The Request, Response, or Message element should be signed in its entirety. To do this,
specify the string "cXMLData" as the value of the Id attribute on the Request, Response, or
Message element and include a ds:Reference element with the URI "#cXMLData" in the
ds:SignedInfo. No transforms should be applied to this reference. This ds:Reference must
be the second ds:Reference in the ds:SignedInfo.
The ds:KeyInfo element should be present with a single ds:X509Certificate element. This
should include the Base64 encoding of the DER representation of an X.509 certificate
containing the public key corresponding to the private key used to sign the document.
Using XAdES
The use of XAdES is a sender option, but it might be legally required in some
situations. If XAdES is used, xades:QualifyingProperties should be the second ds:Object in
the signature. The xades:SignedProperties element and all its children must be signed by
specifying "XAdESSignedProps" as the value for the Id attribute of xades:SignedProperties
and including a ds:Reference with the URI "#XAdESSignedProps" and no transforms in the
ds:SignedInfo. Again, if XAdES is to be used, the certificate referred to in the xades:Cert
element must be the same as that contained in the ds:KeyInfo element, the Id attribute of
the ds:Signature element must be set to cXMLSignature and the Target attribute of
xades:QualifyingProperties must be #cXMLSignature.
Signing Attachments
Each ds:Reference in the manifest should use a URI with the "cid:" scheme to refer to the
attachments through their MIME Content-Id. The ds:Manifest element itself should be
signed using a fragment URI reference included in the ds:SignedInfo. This requirement
exists because a compliant XML signature implementation must validate all the
ds:Reference elements under ds:SignedInfo. Base validation ensures that the manifest
itself has not been corrupted, but will not validate the objects referred to in the
manifest. This approach makes it possible to validate the document on its own if the
attachments have been discarded. For example:
<ds:Object>
<ds:Manifest Id="AttachmentManifest">
timestamp="200104-20T23:59:45-07:00">
<Header>
<From>
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
</Credential>
</From>
<To>
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
</Credential>
</To>
<Sender>
<Credential domain="AribaNetworkUserId">
<Identity>[email protected]</Identity>
<SharedSecret>abracadabra</SharedSecret>
</Credential>
<UserAgent>Our Invoice Application 4.0</UserAgent>
</Sender>
</Header>
<Request Id="cXMLData" deploymentMode="production">
<InvoiceDetailRequest>
<InvoiceDetailRequestHeader invoiceDate="2001-04-20T23:59:20-07:00"
invoiceID="123456-004" operation="new" purpose="standard">
...
</InvoiceDetailRequestHeader>
<InvoiceDetailOrder>
...
</InvoiceDetailOrder>
<InvoiceDetailSummary>
...
</InvoiceDetailSummary>
</InvoiceDetailRequest>
</Request>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="cXMLSignature">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n20010315">
</ds:CanonicalizationMethod>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1">
</ds:SignatureMethod>
<ds:Reference URI="#cXMLSignedInfo">
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
</ds:DigestMethod>
<ds:DigestValue>mxtVp6Rg9K5wo/c5BO88g7sZYEg=</ds:DigestValue>
</ds:Reference>
<ds:Reference URI="#cXMLData">
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
</ds:DigestMethod>
<ds:DigestValue>1uBJgSa3BXewh/1wsPDWCzn8Sgk=</ds:DigestValue>
</ds:Reference>
<ds:Reference URI="#XAdESSignedProps">
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
</ds:DigestMethod>
<ds:DigestValue>XIasOHckorH8fz/thdyZIZvV2yI=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
nNfsBpc22u9aypYLvgE5cuiHVO077vnaolS76LoAuks9bAwLO0kz/nkTQfb2zKSQTy8jj6W/
TJGCQj691PlKBnIqaMPPN3k+hbi6A5cJHPRd3HNPexU5sSi4StTuxlWAiHe/
XEeBEeclu7K6sR4Rh1gzzELg05v21aRX4oVGbjk=</ds:SignatureValue>
<ds:KeyInfo>
</xades:SignaturePolicyIdentifier>
</xades:SignedSignatureProperties>
</xades:SignedProperties>
</xades:QualifyingProperties>
</ds:Object>
</ds:Signature>
</cXML>
A New Features in
DTDs and documentation for this version are available at www.cXML.org.
cXML 1.2.014
Scheduled Payment Document
Scheduled payment (PaymentProposalRequest) documents allow buying organizations
to inform their suppliers about planned payments. They list future payment dates and
A New Features in
discounts and can be for information only or to trigger payment.
cXML 1.2.014
For information on scheduled payment documents, see “PaymentProposalRequest”
on page 168.
A New Features in
Buying organizations can now use the new InvoiceIDInfo element to identify invoices in
cXML 1.2.014
StatusUpdateRequest documents. This element identifies invoices by invoiceID and
invoiceDate. Previously, buying organizations could identify invoices only by payloadID.
Index
A AirLeg element 138
Accounting element 154 about 138
AccountingSegment element 154 AirLeg attributes 140
Address element 121 Airport element 141
addressID attribute 121 arrivalTime attribute 140
agreementDate attribute 203 BookingClassCode element 141
agreementID attribute 203 departureTime attribute 140
OrderRequestHeader element 120 equipment attribute 140
agreementItemNumer attribute 127 flightNumber attribute 140
AgreementItemOut element 204 Meal element 142
agreementPayloadID attribute Rate element 142
OrderRequestHeader element 120 seatNumber attribute 140
AirDetail element seatType attribute 140
about 138 stops attribute 140
AirLeg element 138 travelSegment attribute 140
AirLegDestination element 140 upgrade attribute 140
AirLegOrigin element 140 Vendor element 140
Index
TripType element 138 alternateAmount attribute 57
type attribute of TripType 138 alternateCurrency attribute 57
< through &apos entities 40
ApprovalInfo element 195
approvedDate attribute 195
arrivalTime attribute
AirLeg element 140
HotelDetail element 146
RailLeg element 149
Index
Attachment element 125
attachments to purchase orders 156
attachments, signing 336
AvailablePrice element
CarRentalDetail element 146
Index
Index
deploymentMode attribute 46, 52 FeeDetail element
Description element 81, 110 about 151
Meal element 136 flightNumber attribute
Dimension element 235 AirLeg element 140
direct marketplace 157 Followup element 60, 125
direct PunchOut 111 form encoding 53, 96
CredentialMac 63 From element 83
ProfileResponse 63 From, To, and Sender elements 43
Direct.AuthenticationMethod attributes 63 Fulfill.dtd 25
Index
Distribution element 154
Document Type Definitions (DTDs) 24
DocumentReference element 125, 159, 195, G
207 GetPendingRequest element 304
domain attribute 153 GetPendingResponse 305
CarrierIdentifier element 232
Credential element 44
dropoffTime attribute H
CarRentalDetail element 143 Hazard element 235
ds ConfirmationHeader 219
Signature element 334 Header element 42
DTDs (Document Type Definitions) 24 PunchOutSetupRequest 100
HotelDetail element
about 146
E Address element 147
earlyCheckinAllowed attribute attributes 146
HotelDetail element 146 attributes of RoomType element 147
EDI (X.12 Electronic Data Interchange) 21 AvailablePrice element 148
Index
editors for XML 26 BookingClassCode 148
effectiveDate attribute 61, 203 Meal element 148
encoding Rate element 148
character 32 RoomType element 147
entities 39 Vendor element 147
equipment attribute HTML form encoding 53, 96
AirLeg element 140
error codes for digital signatures 337
expirationDate attribute 203 I
Index
Extrinsic element 86, 98, 103, 314, 315 Id attribute 335
about 126 id attribute 155
ConfirmationHeader element 220 Index element 280
of SpendDetail element 153 IndexItemAdd element 281
ShipNoticePortion element 234 IndexItemDelete element 281
IndexItemDetail element 282
IndexItemPunchout element 281
F indirect marketplace 157
Fax element 124
Index
inReplyTo attribute 52
Index
minReleaseQuantity element 204 P
Money element 57 PackageIdentification element 232
multiple credentials 45 Packaging element 234
PackagingCode element 235
parentAgreementPayloadID attribute 203
N
Path element 158
Name element 121 of an ItemOut 129
new elements path routing 157–166
PaymentTerm 246
Index
payInNumberOfDays attribute 122
non-catalog (ad-hoc) items 127 payloadID 159
noticeDate attribute 216, 228 payloadID attribute 38, 83, 207, 335
numberOfBed attribute Payment element
RoomType element 147 about 122
payment, RequestToPay 208
paymentDate 250
O PaymentProposalRequest 168
operation attribute 83, 102, 203 PaymentRemittance.dtd 25
ConfirmationHeader element 217 PaymentTerm element
ShipNoticeHeader element 228 about 122
operationAllowed attribute 107 attribute 122
Order Receiver Page 97 InvoiceDetailRequestHeader 246
orderDate attribute Period element 152, 193
OrderReference element 213, 236 pickupTime attribute
OrderRequestHeader element 120 CarRentalDetail element 143
orderID attribute 213 pnrLocator attribute
OrderReference element 213, 236 TravelDetail element 131
OrderRequestHeader element 120
Index
preferredLang attribute 245
OrderInfo element 193 Profile transaction 26
OrderMethods element 280 ProfileRequest element 60
OrderReference element 213, 236 ProfileResponse element 60
ShipNoticePortion element 233 Provider PunchOut 311
OrderRequest documents 114 ProviderDoneMessage 318
OrderRequest element ProviderSetupRequest 312
diagram 115 ProviderSetupRequest element 314
example 116 ProviderSetupResponse 316
structure 115
Index
PunchOut index catalog 80, 104
OrderRequestHeader element 118 PunchoutDetail element 283
attributes 120 PunchOutOrderMessage document 87
example 118 PunchOutOrderMessage element 106
orderVersion attribute PunchOutOrderMessageHeader element 107
OrderRequestHeader element 120 PunchOutSetupRequest document 81
OriginalDocument element 159 PunchOutSetupRequest element 101
OriginatorCookie element 314 PunchOutSetupResponse document 86
PunchOutSetupResponse element 105
Index
Index
stops attribute trainNumber attribute
AirLeg element 140 RailLeg element 149
storeFrontURL attribute 278 Transaction element 64
SubmitterInfo element 195 TravelDetail
Subscription element 291 Money element of AvailablePrice 134
SubscriptionContentRequest element 293 TravelDetail element
SubscriptionContentResponse element 293 about 130
SubscriptionListRequest element 292 AirDetail element 138
SubscriptionListResponse element 292 Airport element, about 136
Index
subsequentBuyer role 250 attributes 131
Supervisor element 153 AvailablePrice element 134
supplier and buyer cookies 88, 98 BookingClassCode, about 135
Supplier element 278 CarRentalDetail element 142
SupplierChangeMessage element 290 common elements in 131
SupplierDataRequest element 288 HotelDetail element 146
SupplierDataResponse element 289 Meal element, about 136
SupplierID element 80 RailDetail element 148
SupplierListRequest element 288 SupplierID element 132
SupplierListResponse element 288 TermsAndConditions element 132
SupplierLocation element 279 type attribute of AvailablePrice element
SupplierOrderInfo element 125 134
SupplierPartAuxiliaryID element (Supplier Vendor element 132
Cookie) 88, 98, 282 travelSegment attribute
SupplierSetup element 85, 105 AirLeg element 140
CarRentalDetail element 143
HotelDetail element 146
T RailLeg element 149
Index
Tax element TriangularTransactionLawReference 251
about 122 type attribute
taxPointDate 250 ConfirmationHeader element 215
TelephoneNumber element 124 ConfirmationStatus element 223
text attribute 317 Credential element 44
time and date format 39, 132 Dimenstion element 235
TimeCard element 191, 192 OrderRequestHeader element 120
TimeCardTimeInterval element 194 TripType element 138
duration attribute 194 type definitions 283–287
Index
isNonBillable attribute 194
payCode attribute 194
TimeRange element 194 U
endDate attribute 195 Unit of Measure 57, 89
startDate attribute 195 UnitOfMeasure element 253
timestamp attribute 38, 83 UnitPrice element 253
To element 83 UnitRate element 152, 253
To, From, and Sender elements 43 upgrade attribute
tools for working with XML 26 AirLeg element 140
Index
V
validating cXML 24
Vendor element
attribute 132
CarRentalDetail element 143, 147, 149
version attribute 38
W
W3C XML Digital Signatures 333
WorkLocation element 153
X
XAdES, using 336
xml
lang attribute 38
xml:lang 90
xmllanguageCode element 56
Index
Index
Index
Index
Index