cXML 1.2.021 E-commerce Messaging Protocol User's Guide

cXML User’s Guide

V E R S I O N 1 . 2 . 0 2 1

N O V E M B E R 2 0 0 9

cXML License Agreement

IMPORTANT: PLEASE CAREFULLY READ THIS cXML LICENSE AGREEMENT (“LICENSE”)

BEFORE USING THE cXML SPECIFICATION (“SPECIFICATION”). BY USING THE SPECIFICATION,

YOU AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. IF YOU DO NOT AGREE TO THE

TERMS OF THIS LICENSE, DO NOT USE OR ACCESS THE SPECIFICATION. Licensor may publish new versions (including revisions) of this Agreement from time to time on the cXML site (www.cxml.org).

The rights granted under this license with respect to the Specification are subject to the version of the

Agreement in effect at the time it was downloaded or accessed by you.

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.

5. Limitation of Liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, UNDER NO

CIRCUMSTANCES SHALL LICENSOR BE LIABLE FOR ANY DAMAGES WHATSOEVER RELATING

TO THIS LICENSE OR YOUR USE OF THE SPECIFICATION (INCLUDING BUT NOT LIMITED TO

INCIDENTAL, SPECIAL, PUNITIVE, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES),

REGARDLESS OF WHETHER A CLAIM IS BASED ON TORT, CONTRACT, OR OTHER THEORY OF

LIABILITY, AND EVEN IF LICENSOR IS ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. To the

extent your jurisdiction does not allow any of the above exclusions of damages, in such case you agree that

Licensor's total liability to you for all damages under this License shall not exceed the amount of ten dollars

($10.00). 6. Government End Users. If the Specification is supplied to the United States Government, the

Specification is classified as “restricted computer software” as defined in clause 52.227-19 of the FAR. The

United States Government's rights to the Specification are as provided in clause 52.227-19 of the FAR.

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

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

cXML User’s Guide v

Table of Contents

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

Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

One-Way (Asynchronous) Model . . . . . . . . . . . . . . . . . . . . . . . . 52

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Transport Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Service Status Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Basic Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Type Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Base Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 3

Profile Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Introduction to the Profile Transaction . . . . . . . . . . . . . . . . . . . . . . . . 61

ProfileRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

ProfileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Option Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

From Buyer to Supplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

From Buyer to the Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

From a Network Hub to Supplier . . . . . . . . . . . . . . . . . . . . . . . . 70

From a Network Hub to Service Provider . . . . . . . . . . . . . . . . . . 71

From a Network Hub to Buyer . . . . . . . . . . . . . . . . . . . . . . . . . . 72

From Service Provider to Buyer . . . . . . . . . . . . . . . . . . . . . . . . . 72

vi cXML User’s Guide 1.2.021 November 2009

Table of Contents

Chapter 4

PunchOut Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

PunchOut Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Buying Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Suppliers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

PunchOut Event Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Steps 1 & 2: PunchOut Request . . . . . . . . . . . . . . . . . . . . . . . . . 77

Step 3: Product Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Step 4: Check Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Step 5: Transmittal of Purchase Order. . . . . . . . . . . . . . . . . . . . . 81

PunchOut Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

PunchOut Index Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

PunchOutSetupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

PunchOutSetupResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

PunchOutOrderMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Modifications to the Supplier’s Web Pages . . . . . . . . . . . . . . . . . . . . 91

Launch Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Start Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Sender Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Order Receiver Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

PunchOut Website Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Implementation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Buyer and Supplier Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Personalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

PunchOut Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Sourcing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

PunchOutSetupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

PunchOutSetupResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

PunchOutOrderMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Direct PunchOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Authentication Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

ProfileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

cXML User’s Guide vii

Table of Contents

Chapter 5

Purchase Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Purchase Order Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

OrderRequest Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

OrderRequestHeader Element . . . . . . . . . . . . . . . . . . . . . . . . . . 120

ItemOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Response to an OrderRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Accepting Order Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Chapter 6

Path Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Overview of Path Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Path Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Router Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Copy Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Adding Nodes to PunchOutOrderMessage. . . . . . . . . . . . . . . . . . . . 164

Path Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Creating OrderRequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Path Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Other Routable Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

PunchOutSetupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

ConfirmationRequest and ShipNoticeRequest . . . . . . . . . . . . . 168

CopyRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

viii cXML User’s Guide 1.2.021 November 2009

Table of Contents

Chapter 7

Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Overview of Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

PaymentRemittance DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Payment Document Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . 172

PaymentProposalRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

PayableInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

PaymentMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

PaymentPartner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Contact. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

GrossAmount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

DiscountAmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

AdjustAmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

NetAmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

PaymentRemittanceRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

PaymentRemittanceRequestHeader. . . . . . . . . . . . . . . . . . . . . . 182

PaymentRemittanceSummary . . . . . . . . . . . . . . . . . . . . . . . . . . 184

RemittanceDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

PaymentRemittanceStatusUpdateRequest . . . . . . . . . . . . . . . . . . . . 187

DocumentReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

PaymentRemittanceStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Example Payment Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

PaymentProposalRequest Example . . . . . . . . . . . . . . . . . . . . . . 189

PaymentRemittanceRequest Example . . . . . . . . . . . . . . . . . . . . 191

PaymentRemittanceStatusUpdateRequest Example . . . . . . . . . 193

Chapter 8

TimeCard Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

TimeCard Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Supplier to Buyer Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Buyer to Supplier Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

TimeCard Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

OrderInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Contractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

ReportedTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

SubmitterInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

ApprovalInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

DocumentReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

TimeCard Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

cXML User’s Guide ix

Table of Contents

Chapter 9

Master Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Overview of Master Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

MasterAgreementRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

MasterAgreementRequestHeader Element . . . . . . . . . . . . . . . . 207

AgreementItemOut Element . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Chapter 10

Later Status Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Overview of Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

StatusUpdateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

DocumentReference Element . . . . . . . . . . . . . . . . . . . . . . . . . . 211

PaymentStatus Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

SourcingStatus Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

InvoiceStatus Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Extrinsic Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

ConfirmationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

OrderReference Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

ConfirmationHeader Element . . . . . . . . . . . . . . . . . . . . . . . . . . 218

ConfirmationItem Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

ShipNoticeRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

ShipNoticeHeader Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

ServiceLevel Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Route Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

CarrierIdentifier Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

ShipmentIdentifier Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

PackageIdentification Element . . . . . . . . . . . . . . . . . . . . . . . . . 237

ShipNoticePortion Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

ShipNoticeItem Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

OrderReference Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

x cXML User’s Guide 1.2.021 November 2009

Table of Contents

Chapter 11

Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Overview of Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Early InvoiceRequest Document . . . . . . . . . . . . . . . . . . . . . . . . 244

Debit and Credit Amounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Shipping Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Types of Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Invoice DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

InvoiceDetailRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

InvoiceDetailRequestHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

InvoiceDetailOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

InvoiceDetailHeaderOrder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

InvoiceDetailSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Invoice Status Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Example Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Standard Header Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Standard Detail Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Service Invoice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Marketplace Invoice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Chapter 12

Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Catalog Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Supplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

TypeProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

TypeAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

PrimitiveType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Subscription Management Definitions . . . . . . . . . . . . . . . . . . . . . . . 296

Supplier Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Supplier Profile Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Catalog Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Catalog Upload Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

CatalogUploadRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

cXML User’s Guide xi

Table of Contents xii

Chapter 13

Get Pending/Data Download Transaction . . . . . . . . . . . 315

Introduction to Get Pending/Data Download Transaction . . . . . . . . 315

GetPendingRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

GetPendingResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

No Documents Waiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Documents Waiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

DataRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

DataResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Chapter 14

Provider PunchOut Transaction . . . . . . . . . . . . . . . . . . . 323

Message Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

ProviderSetupRequest Document . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

ProviderSetupResponse Document. . . . . . . . . . . . . . . . . . . . . . . . . . 328

Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

ProviderDoneMessage Document . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

OriginatorCookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

ReturnData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

ReturnValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Chapter 15

Alternative Authentication Methods . . . . . . . . . . . . . . . . 335

Message Authentication Code (MAC) . . . . . . . . . . . . . . . . . . . . . . . 335

Overview of MACs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Computation Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Creation and Expiration Dates. . . . . . . . . . . . . . . . . . . . . . . . . . 336

Computation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

ProfileResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

CredentialMac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Auth Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

AuthRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

AuthResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

cXML User’s Guide 1.2.021 November 2009

Table of Contents

Chapter 16 cXML Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . 345

Digital Signature Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Options for Signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Signing cXML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 cXML Digital Signatures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Error Status Codes for Digital Signatures . . . . . . . . . . . . . . . . . 349

Digital Signature Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Appendix A

New Features in cXML 1.2.021 . . . . . . . . . . . . . . . . . . . . .353

exemptDetail Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Extrinsic Element Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

cXML User’s Guide xiii

Table of Contents xiv cXML User’s Guide 1.2.021 November 2009

Preface

This document describes how to use cXML (commerce eXtensible Markup

Language) for communication of data related to electronic commerce.

Audience and Prerequisites

This document is intended for application developers who design cXML-enabled applications.

cXML is an open versatile language for the transaction requirements of:

•

Network e-commerce hubs

•

Electronic product catalogs

•

PunchOut catalogs

•

Procurement applications

•

Buyers

•

Suppliers

•

E-commerce service providers

Readers should have a working knowledge of e-commerce concepts, the HTTP

Internet communication standard, and XML format.

This document does not describe how to use specific procurement applications or commerce network hubs.

cXML User’s Guide xv

Which Chapters to Read Preface

Which Chapters to Read

•

E-commerce Business Managers—For an overview of cXML capabilities, read

Chapter 1, “Introduction to cXML.”

•

Web Programmers—Web programmers who implement e-commerce sites should read all chapters.

•

Catalog Creators—Suppliers creating cXML catalogs should read Chapter 12,

“Catalogs.”

•

PunchOut Site Implementors—Web programmers creating PunchOut websites

should read Chapter 4, “PunchOut Transaction.”

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:

Typeface or Symbol

<AaBbCc123>

AaBbCc123

AaBbCc123

AaBbCc123

Meaning

Text you need to change is italicized, and appears between angle brackets

The names of user interface controls, menus, and menu items

Files and directory names, parameters, fields in CSV files, command lines, and code examples

Book titles

Example

http://<server>:<port>/ inspector

Choose Edit from the File menu.

There is one line in

ReportMeta.csv for each report in the system.

For more information, see

Acme Configuration

Overview.

xvi cXML User’s Guide 1.2.021 November 2009

Chapter 1

Introduction to cXML

This chapter introduces cXML (commerce eXtensible Markup Language) for electronic-commerce transactions.

This chapter describes:

•

cXML, an XML Implementation

•

cXML Capabilities

•

Types of Applications that Use cXML

•

Content Delivery Strategy

•

cXML DTDs

•

Profile Transaction

•

Service Status Response

•

XML Utilities

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.

XML documents contain data in the form of tag/value pairs, for example:

<DeliverTo>Joe Smith</DeliverTo>

XML has a structure similar to HTML (HyperText Markup Language), which is an implementation of SGML, XML’s parent meta language. Applications can extract and use data from XML documents more easily than from HTML documents, however, because XML data is tagged according to its purpose. XML contains only data, while HTML contains both data and presentation information.

cXML User’s Guide 17

cXML Capabilities Chapter 1 Introduction to cXML

Each cXML document is constructed based on XML Document Type Definitions

(DTDs). Acting as templates, DTDs define the content model of a cXML document, for example, the valid order and nesting of elements, and the data types of attributes.

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.

Successful business-to-business electronic commerce (B2B e-commerce) portals depend upon a flexible, widely adopted protocol. cXML is a well-defined, robust language designed specifically for B2B e-commerce, and it is the choice of high volume buying organizations and suppliers.

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.

The most commonly used types of cXML documents are:

•

Catalogs

•

PunchOut

•

Purchase Orders

The following subsections describe these cXML documents.

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.

18 cXML User’s Guide 1.2.021 November 2009

Chapter 1 Introduction to cXML cXML Capabilities

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 approves a catalog, that content is visible to users, who can choose items and add them to purchase requisitions.

Sending product and service content to a buying organization

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.

PunchOut

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.

There are three types of PunchOut:

•

Procurement PunchOut

•

PunchOut Chaining

•

Provider PunchOut

cXML User’s Guide 19

cXML Capabilities Chapter 1 Introduction to cXML

For more information:

Chapter 4, “PunchOut

Transaction.”

Procurement PunchOut

Procurement PunchOut gives suppliers an alternative to static catalog files. PunchOut sites are live, interactive catalogs running on a website.

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 PunchOut sites, procurement applications display a button instead of product or pricing details. When users click this button, their Web browsers display pages from the supplier’s local website. Depending on how the supplier implements these pages, users can browse product options, specify configurations, and select delivery methods. 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.

Interactive PunchOut session between a user and a supplier website

Suppliers’ websites can offer previously agreed-upon contract products and prices.

20 cXML User’s Guide 1.2.021 November 2009

Chapter 1 Introduction to cXML cXML Capabilities

PunchOut Chaining

PunchOut chaining is Procurement PunchOut that involves more than one PunchOut. cXML Path Routing enables this functionality.

Buyer

Marketplace Supplier 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.

Provider PunchOut

Provider PunchOut enables applications to punch out to a remote applications that supply services to the originating application, such as credit card validation, user authentication, or self-registration.

Purchase Orders

Buying organizations send purchase orders to suppliers to request fulfillment of a contract.

For more information:

Chapter 5, “Purchase

Orders.”

Purchase order communicated to a supplier

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.

cXML User’s Guide 21

Types of Applications that Use cXML Chapter 1 Introduction to cXML

Types of Applications that Use cXML

Any e-commerce application can use cXML. Buying organizations, vertical and horizontal buying communities, suppliers, and application vendors currently use cXML. The following subsections describe the main types of applications that currently use 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.

Ariba Marketplace, Network Edition, is an Internet-based service that allows the creation of buying communities composed of many small- to medium-sized businesses.

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

Commerce network hubs, such as the Ariba Supplier Network, are Web-based services for connecting buyers and suppliers. These Web services provide features such as catalog validation and versioning, catalog publishing and subscription, automated purchase order routing, and purchase order history.

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.

22 cXML User’s Guide 1.2.021 November 2009

Chapter 1 Introduction to cXML Content Delivery Strategy

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.

For more information:

Chapter 4, “PunchOut

Transaction.”

PunchOut catalogs accept PunchOut requests from procurement applications, identify the buying organization, and display the appropriate products and prices in HTML format. Users then select items, configure them, and select options if appropriate.

At the end of the PunchOut session, the PunchOut site sends descriptions of the users’ selections, in cXML format, to the procurement applications.

Order-Receiving Systems

For more information:

Chapter 5, “Purchase

Orders.”

Order-receiving systems are applications at supplier sites that accept and process purchase orders sent by buying organizations. Order-receiving systems can be any automated system, such as inventory management systems, order-fulfillment systems, or order-processing systems.

Because it is simple to extract information from cXML purchase orders, it is relatively easy to create the adapters that enable existing order-receiving systems to accept them.

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 presentation is critical to their sales process. Buying organizations want to make content easily accessible and searchable to ensure high contract compliance.

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.

cXML User’s Guide 23

cXML DTDs Chapter 1 Introduction to cXML

The following table lists example categories of commonly procured products and services, and their preferred content delivery methods.

Commodities

Office Supplies,

Internal Supplies

Lab Supplies,

MRO (Maintenance,

Repair, and Operations),

Electronic Parts

Books,

Chemicals

Computers,

Network Equipment,

Peripherals

Services,

Printed Materials

Properties

Static content, stable pricing

Requires normalization to be useful

Large number of line

Items

Many possible configurations

Content has highly variable attributes

Content Delivery Method

Static catalogs

PunchOut to a vertical commodity portal

PunchOut to a supplier hosted site

PunchOut to a supplier hosted configuration tool

PunchOut to an electronic form at a supplier site

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, it is thoroughly defined by a set of Document

Type Definitions (DTDs). These DTDs are text files that describe 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.

24 cXML User’s Guide 1.2.021 November 2009

Chapter 1 Introduction to cXML cXML DTDs

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

Basic cXML documents

DTD

http://xml.cXML.org/schemas/cXML/<version>/cXML.dtd

Confirmation and Ship Notice http://xml.cXML.org/schemas/cXML/<version>/Fulfill.dtd

Invoice http://xml.cXML.org/schemas/cXML/<version>/InvoiceDetail.dtd

Type Definition http://xml.cXML.org/schemas/cXML/<version>/Catalog.dtd

Payment

Remittance http://xml.cXML.org/schemas/cXML/<version>/PaymentRemittance.dtd

where <version> is the full cXML version number, such as 1.2.020.

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

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

In some environments, cXML applications might not be allowed to automatically 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 for them locally, not at cXML.org. However, generated cXML documents must point to the DTDs at cXML.org, not the local DTDs.

cXML User’s Guide 25

Profile Transaction Chapter 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.

This transaction consists of two documents, ProfileRequest and ProfileResponse.

Together, they retrieve server capabilities, including supported cXML version, supported transactions, and options to those transactions.

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.

Service Status Response

A response with a status code of 200 from an URL that accepts POSTed cXML is up and running. When an HTTP

GET

is sent to a service location, the service responds with a valid, dynamically generated cXML Response document. A service can be any

HTTP URL at which cXML Request documents are received.

26 cXML User’s Guide 1.2.021 November 2009

Chapter 1 Introduction to cXML XML Utilities

XML Utilities

Utilities for editing and validating XML files are available free and for purchase on the Web. The following 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

•

Turbo XML from TIBCO Software. An Integrated Development Environment

(IDE) for creating, validating, converting and managing XML assets.

www.tibco.com/software/metadata/turboxml.jsp

•

XML Spy from Altova. A tool for maintaining DTDs and XML files with a grid, source and browser view.

www.altova.com

•

XMLwriter from Wattle Software. A graphical XML authoring tool designed to manage XML projects.

www.xmlwriter.net

In addition, the following websites list more XML tools: www.xml.com

www-128.ibm.com/developerworks/xml/library/x-matters21/

cXML User’s Guide 27

XML Utilities Chapter 1 Introduction to cXML

28 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics

This chapter describes the basic protocol and data formats of cXML. It contains information needed to implement all transactions.

This chapter describes:

•

Protocol Specification

•

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 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:

A B

Request

One HTTP

POST/Response

B Performs

Request

Response

A Request-Response

Transaction

cXML User’s Guide 29

Protocol Specification

30

Chapter 2 cXML Basics

This transaction contains the following steps:

1.

Site A initiates an HTTP/1.x connection with Site B on a predetermined URL that represents Site B’s address.

2.

Site A uses a POST operation to send the cXML document through the

HTTP connection. Site A then waits for a response.

3.

Site B has an HTTP/1.x-compliant server that dispatches the HTTP Request to the resource specified by the URL used in step 1. This resource can be any valid location known to Site B’s HTTP server, for example, a CGI program or an ASP page.

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.

8.

Site A closes the HTTP connection established in step 1.

This process is then repeated for further Request/Response cycles.

To simplify the work in the above steps, cXML documents are divided into two distinct parts:

•

Header—Contains authentication information and addressing.

•

Request or Response data—Contains a specific request or response and the information to be passed.

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>

cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

The following example shows the structure of a cXML Response document:

<cXML>

<Response>

Response information

</Response>

</cXML>

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 composed of street, city, and country. cXML also uses attributes, which modify elements or provide context.

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:

Elements:

Sender

,

Credential

,

Payment

,

ItemDetail

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.

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">

<cXML xml:lang="en-US" payloadID=”[email protected]" timestamp="2002-01-09T01:36:05-08:00">

cXML User’s Guide 31

Protocol Specification Chapter 2 cXML Basics

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

32 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

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

Connection: Keep-Alive

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

…

Attachments

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

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.

cXML User’s Guide 33

Protocol Specification Chapter 2 cXML Basics

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

Content-type: multipart/mixed; boundary=something unique

--something unique

Content-type: text/xml; charset="UTF-8"

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

…

<Attachment>

<URL>cid:[email protected]</URL>

…

</Attachment>

--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]>

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

…

<Attachment>

<URL>cid:[email protected]</URL>

…

</Attachment>

--something unique

Content-type: image/jpeg

Content-ID: <[email protected]>

…

--something unique--

34 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

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

The following example shows a

CatalogUploadRequest

with an attached catalog:

First MIME body part header

ID of MIME attachment

Second MIME body part header

POST /cXML HTTP/1.0

Content-type: multipart/related; boundary=kdflkajfdksadjfk; type="text/xml"; start="<[email protected]>"

--kdflkajfdksadjfk

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">

<Identity>AN01000000001</Identity>

</Credential>

</To>

<Sender>

<Credential domain="DUNS">

<Identity>123456789</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

</Sender>

</Header>

<Request>

<CatalogUploadRequest operation="new">

<CatalogName xml:lang="en">Winter Prices</CatalogName>

<Description xml:lang="en">premiere-level prices</Description>

<Attachment>

<URL>cid:[email protected]</URL>

</Attachment>

</CatalogUploadRequest>

</Request>

</cXML>

--kdflkajfdksadjfk cXML User’s Guide 35

Protocol Specification Chapter 2 cXML Basics

MIME trailer

Content-type: text/plain; charset=US-ASCII

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",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

--kdflkajfdksadjfk--

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.

36 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

The following example shows a

CopyRequest

forwarding a cXML document with attachments using cXMLAttachment

. For more information about

CopyRequest

, see

“CopyRequest” on page 169.

Content-Type: Multipart/Related; boundary=outer-boundary

[Other headers]

--outer-boundary

Content-Type: text/xml; charset=UTF-8

Content-ID: <[email protected]>

[Other headers]

<?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="2003-11-20T23:59:45-07:00">

<Header>

<From>

<!-- Sender -->

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

</Credential>

</From>

<To>

<!-- Recipient -->

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

</Credential>

</To>

<Sender>

<!-- Sender -->

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>Sender Application 1.0</UserAgent>

</Sender>

</Header>

<Request deploymentMode="production">

<CopyRequest>

<cXMLAttachment>

<Attachment>

<URL>cid:[email protected]</URL>

</Attachment>

</cXMLAttachment>

</CopyRequest>

</Request>

</cXML>

--outer-boundary

cXML User’s Guide 37

Protocol Specification Chapter 2 cXML Basics

Content-Type: Multipart/Related; boundary=inner-boundary

Content-ID: <[email protected]>

[Other headers]

--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]

--inner-boundary

[Attachment 2 of the forwarded cXML]

--inner-boundary--

--outer-boundary--

More Information About MIME

For more information about the MIME standard, see the following websites: 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 128.

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">

38 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

cXML

has the following attributes:

version

(deprecated)

xml:lang

(optional)

payloadID timestamp signatureVersion

This attribute was deprecated in cXML 1.2.007; do not use it in new cXML documents.

Specifies the version of the cXML protocol. A validating XML parser could also determine the version attribute from the referenced DTD.

Because this version number also appears in the SYSTEM identifier in the cXML document, you should omit this attribute.

The locale used for all free text sent within this document. The receiver should reply or display information in the same or a similar locale. For example, a client specifying xml:lang=“en-UK” in a request might receive “en” data in return. Specify the most descriptive and specific locale possible.

A unique number with respect to space and time, used for logging purposes to identify documents that might have been lost or had problems. This value should not change for retry attempts.

The recommended implementation is: datetime.process id.random number@hostname

The date and time the message was sent, in ISO 8601 format.

This value should not change for retry attempts.

The format is YYYY-MM-DDThh:mm:ss-hh:mm (for example,

1997-07-16T19:20:30+01:00).

If present, implies that the document is digitally signed, that is, that the document contains one or more valid ds:Signature elements immediately following the Request, Response, or

Message element. The only valid value for the attribute is 1.0; other values are reserved for future use. For more information,

see Chapter 16, “cXML Digital Signatures.”

cXML User’s Guide 39

Protocol Specification Chapter 2 cXML Basics

Locale Specified by xml:lang

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

Date, Time, and other Data Types

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

Further references for the date, time, and other data type formats used by cXML are:

•

Microsoft’s XML Data Types Reference,

msdn.microsoft.com/library/ default.asp?url=/library/en-us/xmlsdk/html/b24aafc2-bf1b-4702-bf1cb7ae3597eb0c.asp

•

The original XML Data proposal to the Word Wide Web Consortium (W3C), www.w3c.org/TR/1998/NOTE-XML-data-0105

40 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

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.

XML defines the following built-in character entities:

Entity

&lt;

&gt;

&amp;

&quot;

&apos; ‘

“

&

Character

<

>

For characters outside of the encoding you use, use the Unicode number of the character (decimal or hexadecimal), preceded by pound (#). For example,

&#174;

and

&#xAE;

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 &#174;</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.

W

To handle special characters in documents:

1.

Use a template that only uses single quotes to delimit attributes.

2.

Add values to the template by doing one of the following:

•

If the document is a PunchOutOrderMessage to be transmitted by the cxml-urlencoded hidden field, fill the values in the template using US-

ASCII encoding. This encoding requires XML character entities for all characters beyond that encoding. For example, as described above, enter the registered trademark symbol, which is not available in US-ASCII, as

&#174;

.

cXML User’s Guide 41

Protocol Specification Chapter 2 cXML Basics

•

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

The following steps are required if you are transmitting the document in a

PunchOutOrderMessage.

4.

Pay attention to all characters that browsers interpret:

a.

If you are using a cxml-urlencoded hidden field, convert all double quotes to

&#34;

.

b.

Further (for the cxml-urlencoded field), escape all ampersands that appear in contexts significant to HTML with

&amp;

. To be safe, you can escape all ampersands. For example, escape

&amp;

as

&amp;amp; and

&apos; as

&amp;apos;

. Escape the trademark symbol

&#174;

as

&amp;#174;

.

c.

Otherwise, if you are using a cxml-base64 hidden field, base64 encode the entire cXML document.

5.

Embed the document in the HTML form with double quotes around the 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='&#174;&#xAE;&apos;"&#34;&quot;&amp;&lt;>&gt;'>

&#174;&#xAE;'&apos;"&#34;&quot;&amp;&lt;>&gt;</Money> 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='&amp;#174;&amp;#xAE;&amp;apos;&#34;&amp;#34;

&amp;quot;&amp;amp;&amp;lt;>&amp;gt;'>&amp;#174;&amp;#xAE;'&amp;apos;

&#34;&amp;#34;&amp;quot;&amp;amp;&amp;lt;>&amp;gt;</Money>">

<!-- Best choice: Base64 encode the value. Don't have to worry about what -->

<!-- the browser interprets. -->

42 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

<Input type="Hidden" name="cXMLbase64"value="PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4K

PCFET0NUWVBFIE1vbmV5IFNZU1RFTSAnU3BlY2lhbENoYXJzLmR0ZCc+CjxNb

25leSBhbHRlcm5hdGVBbW91bnQ9JyYjMTc0OyYjeEFFOyZhcG9zOyImIzM0OyZxd

W90OyZhbXA7Jmx0Oz4mZ3Q7Jz4KJiMxNzQ7JiN4QUU7JyZhcG9zOyImIzM0OyZx dW90OyZhbXA7Jmx0Oz4mZ3Q7PC9Nb25leT4K">

The preceding examples illustrate alternatives for encoding the cXML-urlencoded field. They avoid XML escaping a few characters, such as angle brackets, that are not special to XML in all contexts. A direct implementation of the previous steps would result in an HTML field such as:

<Input type="Hidden" name="cXML-urlencoded" value="<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>

<Money alternateAmount='&amp;#174;&amp;#174;&amp;apos;&#34;&#34;&#34;

&amp;amp;&amp;lt;&amp;gt;&amp;gt;'>&amp;#174;&amp;#174;''&#34;&#34;&#34;

&amp;amp;&amp;lt;&amp;gt;&amp;gt;</Money>"> or the XML document:

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

<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>

<Money alternateAmount='&#174;&#174;&apos;"""&amp;&lt;&gt;&gt'>

&#174;&#174;''"""&amp;&lt;&gt;&gt;</Money>

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.

The following example shows the

Header

element:

<Header>

<From>

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

</Credential>

</From>

<To>

<Credential domain="DUNS">

<Identity>012345678</Identity>

</Credential>

</To>

<Sender>

cXML User’s Guide 43

Protocol Specification Chapter 2 cXML Basics

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>Network Hub 1.1</UserAgent>

</Sender>

</Header>

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

This element identifies the originator of the cXML request.

To

This element identifies the destination of the cXML request.

Sender

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.

This should be a unique per-product string, and ideally, per-version. Analogous to

UserAgent

for HTTP conversations.

44 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

Credential

This element contains identification and authentication values.

Credential

has the following attributes:

domain type

(optional)

Specifies the type of credential. This attribute allows documents to contain multiple types of credentials for multiple authentication domains.

For messages sent on the Ariba Supplier Network, for instance, the domain can be AribaNetworkUserId to indicate an email address, DUNS for a D-U-N-S number, or NetworkId for a preassigned ID.

Requests to or from a marketplace identify both the marketplace and the member company in From or To Credential elements. In this case, the credential for the marketplace uses the type

attribute, which is set to the value “ marketplace

”.

Credential

contains an

Identity

element and optionally a

SharedSecret

or a

CredentialMac element. The

Identity

element states who the

Credential

represents, while the optional authentication elements verify the identity of the party.

SharedSecret

The

SharedSecret

element is used when the

Sender

has a password that the requester recognizes.

Note:

Do not use authentication elements in documents sent through oneway communication. One-way transport routes through users’ browsers, so users would be able to see the document source, including

Credential elements.

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

cXML User’s Guide 45

Protocol Specification Chapter 2 cXML Basics

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.

To learn how to compute the MAC value, see

“Message Authentication Code

(MAC)” on page 335.

CredentialMac has the following attributes:

type algorithm creationDate expirationDate

Identifies the data being authenticated and the method in which it is formatted for authentication. The only supported value is

"FromSenderCredentials"

.

Identifies for the MAC algorithm used on the data. The only supported value is “HMAC-SHA1-96” .

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. Receivers can optionally reject unexpired

MACs. For example, a receiver might reject MACs that are scheduled to expire in less than an hour.

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” expirationDate=”2003-01-15T11:42:46-0800”>

MnXkusp8Jj0lw3mf

</CredentialMac>

<UserAgent>Procurement Application 8.1</UserAgent>

</Credential>

</Sender>

Multiple Credentials

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.

46 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

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.

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.

Correspondent

The

From

and

To

elements can each optionally contain a

Correspondent

element.

Correspondent

elements are used in cases where a party or a connecting hub does not know the originating or receiving organization. The sender, receiver, or connecting hub can use the information in the

Correspondent

element to identify the unknown organization.

Correspondent has the following attribute:

preferredLanguage

(optional)

The preferred language of the organization, if it is known.

Identify the unknown organization by using a

Contact

element. For more information, see

“Contact” on page 60,

Request

Clients send requests for operations. Only one

Request

element is allowed for each cXML

envelope element, which simplifies the server implementations, because no demultiplexing needs to occur when reading cXML documents. The

Request

element can contain virtually any type of XML data.

Typical Request elements are:

• OrderRequest

• ProfileRequest

• PunchOutSetupRequest

• StatusUpdateRequest

• GetPendingRequest

• ConfirmationRequest

• ShipNoticeRequest

• ProviderSetupRequest

• PaymentRemittanceRequest

cXML User’s Guide 47

Protocol Specification Chapter 2 cXML Basics

Request

has the following attributes:

deploymentMode

(optional)

Id

Indicates whether the request is a test request or a production request. Allowed values are “production” (default) or “test”.

This attribute can be used to call out an element and all its children as a target for a digital signing. For more information

about digital signatures, see Chapter 16, “cXML Digital

Signatures.”

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.

The typical Response elements are:

• ProfileResponse

• PunchOutSetupResponse

• GetPendingResponse

Response

has the following attribute:

Id

This attribute can be used to call out an element and all its children as a target for a digital signing. For more information

about digital signatures, see Chapter 16, “cXML Digital

Signatures.”

Status

This element conveys the success, transient failure, or permanent failure of a request operation.

Status

has the following attributes:

code text xml:lang

(optional)

The status code of the request. For example, 200 represents a successful request. See the table of codes, below.

The text of the status. This text aids user readability in logs, and is a canonical string for the error in English.

The language of the data in the Status element. Optional for compatibility with cXML 1.0. Might be required in future versions of cXML.

48 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

The attributes of the

Status

element indicate what happened to the request. For example:

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

The following table describes the cXML status code ranges:

Range

2xx

4xx

5xx

Meaning

Success

Permanent error. Client should not retry. The error prevents the request from being accepted.

Transient error. Typically a transport error. Client should retry. The recommended number of retries is 10, with a frequency of one hour. At a minimum a six hour retry window is recommended. For high priority requests, such as rush orders, you might want to increase the retry frequency.

Servers should not include additional Response elements (for example, a

PunchOutSetupResponse

element) unless the status code is in the cXML

200

range (for example, cXML

200/OK

).

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

.

cXML User’s Guide 49

Protocol Specification Chapter 2 cXML Basics

The following table includes possible cXML status codes:

Status

200

201

204

280

281

400

401

402

Text

OK

Accepted

No Content

Bad Request

Unauthorized

Meaning

The server was able to execute the request or deliver it to the final recipient. The returned Response might contain application warnings or errors: the cXML

Request itself generated no errors or warnings, however, this status does not reflect any errors or warnings that might be generated afterward by the application itself. You will receive no further status updates, unless an error occurs during later processing.

The request has been accepted for forwarding by an intermediate hub, or has been accepted by its ultimate destination and not yet been examined. You will receive updates on the status of the request, if a mechanism to deliver them is available.

As mentioned in “StatusUpdateRequest” on page 210,

the client should expect later StatusUpdate transactions.

All

Request

information was valid and recognized. The server has no

Response

data of the type requested.

In a PunchOutOrderMessage , this status indicates that the

PunchOut session ended without change to the shopping cart (or client requisition).

The request has been forwarded by an intermediate hub. You will receive at least one more status update.

This status could mean that the request was delivered to another intermediary or to the final recipient with 201 status, or that it was forwarded via a reliable non-cXML transport.

The request has been forwarded by an intermediate hub using an unreliable transport (such as email). You might receive status updates; however, if you do not received status updates, there is not necessarily a problem.

Request unacceptable to the server, although it parsed correctly.

Credentials provided in the

Request

(the

Sender

element) were not recognized by the server.

This Request must include a complete Payment element.

403

Payment

Required

Forbidden

406

409

Not Acceptable

Conflict

The user has insufficient privileges to execute this

Request .

Request unacceptable to the server, likely due to a parsing failure.

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.

50 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

Status

412

417

450

475

476

477

500

550

551

Text

Precondition

Failed

Expectation

Failed

Not

Implemented

Signature

Required

Signature

Verification

Failed

Signature

Unacceptable

Internal Server

Error

Unable to reach cXML server

Unable to forward request

Meaning

A precondition of the

Request

(for example, a PunchOut 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 ).

Request implied a resource condition that was not met.

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.

The server does not implement the particular Request .

For example,

PunchOutSetupRequest

or the requested operation might not be supported. This status normally implies the client has ignored the server’s profile.

The receiver is unwilling to accept the document because it does not have a digital signature.

The receiver is unable to validate the signature, possibly because the document was altered in transit, or the receiver does not support one or more algorithms used in the signature.

The signature is technically valid, but is not acceptable 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.

Server was unable to complete the Request .

Unable to reach next cXML server to complete a transaction requiring upstream connections. An intermediate hub can return this code when a supplier site is unreachable. If upstream connections complete, intermediate hubs should return errors directly to the client.

Unable to forward request because of supplier misconfiguration. For example, an intermediate hub failed to authenticate itself to a supplier. Clients cannot rectify this error, but this error might be resolved before the client retries.

For example, a server might be down for maintenance.

The client should retry later.

560 Temporary server error

For status codes related to catalog uploading, see “Response” on page 312.

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.

cXML User’s Guide 51

Protocol Specification Chapter 2 cXML Basics

One-Way (Asynchronous) Model

Unlike Request-Response transactions, One-Way messages are not restricted to the

HTTP transport. One-way messages are for situations when an HTTP channel (a synchronous request-response type operation) is not appropriate. The following figure shows an example of how A and B might communicate with messages instead of the

Request-Response transaction.

A B

Message

One-Way Message

(Asynchronous)

In this case, a possible scenario would be:

1.

A formats and encodes a cXML document in a transport that B understands.

2.

A sends the document using the known transport. A does not (and cannot) actively wait for a response to come back from B.

3.

B receives the cXML document and decodes it out of the transport stream.

4.

B processes the document.

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.

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

.

One-way messages have a similar structure to the Request-Response model:

<cXML>

<Header>

Header information here…

</Header>

<Message>

Message information here…

</Message>

</cXML>

52 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

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

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.

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.

Message

has the following attributes:

deploymentMode

(optional)

inReplyTo

(optional)

Id

Indicates whether the request is a test request or a production request. Allowed values are “production” (default) or “test”.

Specifies to which Message this Message responds. The contents of the inReplyTo attribute would be the payloadID of a

Message

that was received earlier. This would be used to construct a two-way conversation with many messages.

This attribute can be used to call out an element and all its children as a target for a digital signing. For more information

about digital signatures, see Chapter 16, “cXML Digital

Signatures.”

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.

cXML User’s Guide 53

Protocol Specification Chapter 2 cXML Basics

HTTP

Procurement applications pull information using one-way HTTP communication. The one type of transaction that uses one-way HTTP communication is

GetPendingRequest

,

discussed on page 316.

HTTPS is preferred, because it encrypts transmitted data for security.

URL-Form-Encoding

URL-Form-Encoding enables integration between remote websites and procurement applications. It also serves as a way to avoid requiring a listening server on the buyer’s system that is directly accessible through the Internet. This transport is best understood by examining how the

PunchOutOrderMessage

transaction works.

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:

Web

Browser

Internet

1

Remote

Website

2

User clicks Submit button, Form is sent to URL specified by

Originating

System

Originating

System

HTML page with

Form-encoded cXML message

3

Form is decoded, cXML message extracted and passed to

Originating System as a new cXML

Request

54 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

The semantics of packing and unpacking are described below.

Form Packing

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">

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

The names cXML-urlencoded and cXML-base64 are case insensitive.

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 HTMLencode the field value, escaping quotation marks and other special characters, so that the form will display correctly.

Note:

Suppliers should never URL encode the cXML-urlencoded field.

This field is automatically URL-encoded by the web browser.

cXML User’s Guide 55

Protocol Specification Chapter 2 cXML Basics

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

The cXML-base64

hidden field supports international documents. cXML documents containing symbols outside of “us-ascii” should use this field instead of the cXMLurlencoded

hidden field. This alternative has almost identical semantics, but the entire document is base64-encoded throughout transport and not HTML-encoded to the browser or URL-encoded to the receiving Web server. Base64-encoding is described in RFC 2045 “Multipurpose Internet Mail Extensions (MIME) Part One: Format of

Internet Message Bodies.”

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

.

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.

Form Unpacking and Processing

The procurement application, which previously provided the appropriate URL, receives an HTML Form POST containing the Form data as described above. The

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.

56 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Protocol Specification

The implied media type of the document after decoding varies, with different possible character encodings:

•

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.

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.

Service Status Response

This transaction determines whether a particular service is currently available. When an HTTP

GET

is sent to a service location, the service responds with a valid, dynamically generated cXML Response document. A service can be any HTTP URL at which cXML Request documents are received.

For example, an HTTP

GET

sent to https://service.ariba.com/service/transaction/cxml.asp

yields the following response:

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

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

<cXML timestamp="2001-01-08T10:47:01-08:00" payloadID="978979621537--

[email protected]">

<Response>

<Status code="200" text="OK">Ping Response Message</Status>

</Response>

</cXML>

Note:

This combination of transport (HTTP) and protocol (cXML) levels should be used only for the case described above.

cXML User’s Guide 57

Basic Elements Chapter 2 cXML Basics

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

An ISO Language Code from the ISO 639 standard.

isoCountryCode

An ISO Country Code from the ISO 3166 standard.

xmlLangCode

A language code as defined by 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.

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.

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.

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

.

58 cXML User’s Guide 1.2.021 November 2009

Chapter 2 cXML Basics Basic Elements

URL

A URL (Uniform Resource Locator) as defined by the HTTP/1.1 standard.

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

TermReference

element, see page 155.

Money

The

Money

element has three possible attributes: currency

, alternateAmount

, alternateCurrency.

The attributes currency and

alternateCurrecy must be a three-letter ISO

4217 currency code. The content of the

Money

element and of the aternateAmount attribute should be a numeric value. For example:

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

Note:

You can optionally use commas as thousands separators. Do not use commas as decimal separators.

Country

Contains the name of the country in a location. Contained by the

PostalAddress element.

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.

cXML User’s Guide 59

Basic Elements Chapter 2 cXML Basics

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>

60 cXML User’s Guide 1.2.021 November 2009

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

This chapter describes:

•

Introduction to the Profile Transaction

•

ProfileRequest

•

ProfileResponse

•

Scenarios

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.

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 by the manager of a trading community.

cXML User’s Guide 61

ProfileRequest Chapter 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.

An example

Request

of this type is:

<cXML payloadID="9949494" xml:lang="en-US" timestamp="2000-03-12T18:39:09-08:00">

<Header>

Routing, identification, and authentication information.

</Header>

<Request>

<ProfileRequest />

</Request>

</cXML>

ProfileRequest

documents should be sent to the “root” URL of a commerce network hub, which should never change. Sending a

ProfileRequest

to this root URL obtains the

URL location for every other cXML Request type. The

ProfileResponse

from a commerce network hub depends on the

To

element in the

ProfileRequest

.

62 cXML User’s Guide 1.2.021 November 2009

Chapter 3 Profile Transaction ProfileResponse

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">

<URL>http://www.workchairs.com/cXML/PunchOut.asp</URL>

<Option name="operationAllowed">create inspect</Option>

<Option name="dynamic pricing">0</Option>

…

</Transaction>

…

</ProfileResponse>

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">

<URL>http://workchairs.com/cgi/PunchOut.cgi</URL>

<Option name=”service”>workchairs.signin</Option>

</Transaction>

</ProfileResponse>

ProfileResponse

has the following attributes:

effectiveDate

The date and time when these services became available.

Dates should not be in the future.

lastRefresh

Indicates when the profile cache was last refreshed. When an application receives a ProfileResponse from a profile caching server, it will know the age of the data in the cache.

cXML User’s Guide 63

ProfileResponse Chapter 3 Profile Transaction

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:

name

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 receiving a ProfileResponse document.

Currently defined values for name are service, attachments, changes, and requestNames.

MAC Options

If the

ProfileResponse

document is sent by a trusted third party (such as a network commerce hub) and it lists transactions that rely on MAC authentication, it should contain

Option

elements that list MAC authentication values. The client will insert these values in a

CredentialMac

element in documents it sends directly to the server.

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

Service

For more information about MACs, see “Message Authentication Code (MAC)” on page 335.

The Profile transaction can return multiple variations of a single transaction type.

If a cXML server supports multiple implementations of a particular transaction,

ProfileResponse

can distinguish them. For example, a marketplace might provide two services within the

ProviderSetupRequest

transaction: marketplace.signin and marketplace.console. The

ProfileReponse

must list them in a way that differentiates them:

64 cXML User’s Guide 1.2.021 November 2009

Chapter 3 Profile Transaction ProfileResponse

ProfileResponse

can uniquely identify a specific location for each variation of a transaction. In the case of

ProviderSetupRequest

, the variation is the service name.

ProfileResponse

uses the

Option

element to include the service name and value, for example:

<Transaction requestName=”ProviderSetupRequest”>

<URL>http://service.hub.com/signin</URL>

<Option name="service">signin</Option>

</Transaction>

<Transaction requestName=”ProviderSetupRequest”>

<URL>http://service.hub.com/console</URL>

<Option name="service">console</Option>

</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, 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.

PunchOutSetupRequest Options

When

PunchOutSetupRequest

is returned as a supported transaction, three options can be specified to indicate that direct PunchOut is supported. These options inform clients that they can send

PunchOutSetupRequest

documents directly to servers, without going through network commerce hubs for authentication, and which authentication methods are supported:

•

To specify the URL for receiving direct

PunchOutSetupRequest

documents:

<Option name="Direct.URL">https://asp.workchairs.com/directPunchout</Option>

•

To indicate that the server supports Message Authentication Code (MAC) authentication:

<Option name="Direct.AuthenticationMethod.CredentialMac">Yes</Option>

cXML User’s Guide 65

ProfileResponse Chapter 3 Profile Transaction

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 appear within the

ProfileResponse

element for profiles sent by trusted third parties,

see “MAC Options” on page 64. For information about MAC authentication, see

“Message Authentication Code (MAC)” on page 335.

•

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

PunchOut requests. For information about the Auth transaction, see

“Auth

Transaction” on page 340.

These options are not used for regular PunchOut.

For more information about direct PunchOut, see

“Direct PunchOut” on page 114.

OrderRequest Options

When

OrderRequest

is returned as a supported transaction, two options must be specified: attachments

and changes

. The attachments

option indicates whether attachments are accepted. The changes

option specifies if change and delete orders are accepted. To specify acceptance of attachments:

<Option name = "attachments">Yes</Option>

To specify acceptance of change orders:

<Option name = "changes">Yes</Option>

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

When

SessionStatusRequest

is returned as a supported transaction, one option must be specified: requestNames

. There is no default. This option informs the client that the server supports session checks and updates when performing any of the transactions specified in the content of the

Option

element. This content must be a space-separated list from the set “

OrderStatusSetupRequest

,” “

ProviderSetupRequest

” and

“

PunchOutSetupRequest

.”

Transaction

elements for each of the listed requests must also be included in the

ProfileResponse

document.

66 cXML User’s Guide 1.2.021 November 2009

Chapter 3 Profile Transaction Scenarios

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.

The

Transaction

element must contain a

URL

element.

Transaction

has the following attribute:

requestName

A specific request that this server accepts at the given URL.

Values can be the name of any Request document defined by cXML.

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.

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.

Profile Request Profile Request

Buyer Network

Supplier

Profile Response

Profile Response

The supplier returns in the

ProfileResponse

the transactions that it supports. For example:

•

OrderRequest

•

PunchOutSetupRequest

The

ProfileResponse

sent to the buyer can include capabilities offered by the network on behalf of that supplier.

cXML User’s Guide 67

Scenarios Chapter 3 Profile Transaction

From Buyer to the Network

A

ProfileRequest

document is sent from a buyer to the network.

Buyer

Profile Request

Profile Response

Network

The network returns in the

ProfileResponse

the transactions that it supports. For example:

•

SupplierDataRequest

•

SubscriptionListRequest

•

SubscriptionContentRequest

•

GetPendingRequest

•

OrderStatusSetupRequest

•

SupplierListRequest

•

ProviderSetupRequest

•

SessionStatusSetupRequest

Example

ProfileRequest

document:

<?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:09-08:00">

<Header>

<From>

<Credential domain="NetworkId">

<Identity>AN01001010101</Identity> <!-- marketplace's id -->

</Credential>

</From>

<To>

<Credential domain="NetworkId">

<Identity>AN01000000001</Identity> <!-- Network -->

</Credential>

</To>

<Sender>

<Credential domain="NetworkId">

<Identity>AN01001010101</Identity>

<!-- marketplace's shared secret -->

<SharedSecret>abracadabra</SharedSecret>

68 cXML User’s Guide 1.2.021 November 2009

Chapter 3 Profile Transaction Scenarios

</Credential>

<UserAgent>Marketplace 7.5</UserAgent>

</Sender>

</Header>

<Request>

<ProfileRequest />

</Request>

</cXML>

Example

ProfileResponse

document:

<?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">

<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">

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

</Transaction>

<Transaction requestName="SessionStatusRequest">

<URL>https://superduper.com/d/SessionStatus</URL>

<Option name="requestNames">OrderStatusSetupRequest</Option>

</Transaction>

</ProfileResponse>

</Response>

</cXML>

cXML User’s Guide 69

Scenarios Chapter 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.

Network

Profile Request

Profile Response

Supplier

The supplier returns in the

ProfileResponse

document the transactions that it supports.

For example:

•

OrderRequest

•

PunchOutSetupRequest

Example

ProfileRequest

document:

<?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:09-08:00">

<Header>

<From>

<Credential domain="NetworkId">

<Identity>AN01001010101</Identity> <!-- Network's id -->

</Credential>

</From>

<To>

<Credential domain="NetworkId">

<Identity>AN01234663636</Identity> <!-- any supplier's id -->

</Credential>

</To>

<Sender>

<Credential domain="NetworkId">

<Identity>AN01001010101</Identity>

<!-- Network's sharedscret -->

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>Marketplace 7.5</UserAgent>

</Sender>

</Header>

<Request>

<ProfileRequest />

</Request>

</cXML>

70 cXML User’s Guide 1.2.021 November 2009

Chapter 3 Profile Transaction Scenarios

Example

ProfileResponse

document:

<?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">

<Transaction requestName="PunchOutSetupRequest">

<URL>https://www.acme.com/cxml/PunchOutSetup</URL>

</Transaction>

<Transaction requestName="OrderRequest">

<URL>https:// www.acme.com/cxml /Order</URL>

<Option name="attachments">yes</Option>

<Option name="changes">yes</Option>

</Transaction>

</ProfileResponse>

</Response>

</cXML>

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.

Network

Profile Request

Profile Response

Provider

The service provider returns in the

ProfileResponse

document the transactions that it supports. For example:

•

ProviderSetupRequest

•

SessionStatus

•

OrderRequest

cXML User’s Guide 71

Scenarios Chapter 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.

Network

Profile Request

Profile Response

Buyer

Buyers return in the

ProfileResponse

document the transactions that they support. For example:

•

StatusUpdateRequest

•

InvoiceDetailRequest

From Service Provider to Buyer

A

ProfileRequest

is sent from a service provider to a buyer and routed through a network commerce hub. This scenario is a replacement for the

Followup

element. The network commerce hub queries the buyer periodically, and caches the information.

Later, this information about the buyer is used in

ProfileResponse

documents sent to service providers.

Profile Request Profile Request

Provider Network

Buyer

Profile Response

Profile Response

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

72 cXML User’s Guide 1.2.021 November 2009

Chapter 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 describes:

•

PunchOut Requirements

•

PunchOut Event Sequence

•

PunchOut Documents

•

Modifications to the Supplier’s Web Pages

•

PunchOut Website Suggestions

•

PunchOut Transaction

•

Direct PunchOut

PunchOut Requirements

Before buying organizations configure their procurement applications for PunchOut, 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 PunchOutenabled supplier can be completed in less than one day.

cXML User’s Guide 73

PunchOut Requirements Chapter 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:

•

Do requisitioners and approvers have Internet access? If not, would controlled access to the Internet be allowed?

•

Does the buying organization want their suppliers to create and maintain catalog content (including pricing)?

•

Do requisitioners currently procure goods on the Internet? If so, do these goods require a supplier-side configuration tool or contain unique attributes that cannot conform to a static content model?

•

Does the buying organization use content aggregators for catalogs (for example,

Aspect, TPN Register, or Harbinger)?

•

Does the buying organization currently procure services (for example, consultants, temp services, or maintenance) through the Internet?

•

Does the buying organization currently conduct online sourcing?

If the answer to any of the above questions is yes, PunchOut might be appropriate for the buying organization.

Technical Issues

Buying organizations must meet the following technical requirements:

•

Direct Internet Access—Users within buying organizations must have direct

Internet access. PunchOut relies on regular Web browser sessions where the user interacts with live supplier websites. This communication occurs through regular intranet/Internet infrastructure, not through the procurement application.

•

Reliable Internet Connection—Internet access must be constantly operational and reliable. If users cannot procure products because of Internet outages, they are likely to make rogue purchases.

•

Contracts with PunchOut Suppliers—Purchasing agents must have established contracts with PunchOut-enabled suppliers. PunchOut websites allow access only to known, authenticated buying organizations.

74 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Requirements

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.

Example products and services include:

•

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

Suppliers should consider the following questions:

•

Does the supplier currently sell the supplier’s products or services through the

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)

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.

cXML User’s Guide 75

PunchOut Requirements Chapter 4 PunchOut Transaction

Technical Issues

Suppliers must meet the following technical requirements:

•

Reliable Internet Connection—The Web server infrastructure and Internet connection must be extremely reliable. If users cannot access remote content, they are likely to go to another supplier.

•

Competent website Administrators—The PunchOut website and supporting applications will require periodic maintenance and modification. Users’ needs and the supplier’s product offerings will change, so the supplier needs personnel to modify the supplier’s PunchOut infrastructure.

•

Support for Basic Transactions—PunchOut websites do not need to support all cXML functionality, but they must support the following required transactions:

Profile Transaction

PunchOutSetupRequest

PunchOutSetupResponse

PunchOutOrderMessage

Work Estimate

The following table lists estimates of work required for cXML PunchOut integration based on estimates from suppliers:

Level of Pre-existing Infrastructure

cXML enabled and integrated with network commerce hub

Transactive site with XML infrastructure

Transactive site without XML infrastructure

Estimated Time for Completion

1-2 weeks with in-house IT staff

2-3 weeks with contractors

3 weeks with in-house IT staff

3-4 weeks with contractors

4 weeks with in-house IT staff

4-5 weeks with contractors

Understanding XML

The first step to becoming PunchOut enabled is to understand XML. For an

explanation of XML, see “cXML, an XML Implementation” on page 17. To

implement a PunchOut website, the supplier must have a fundamental understanding of how to create, parse, query, receive, and transmit XML data to and from a remote source.

76 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Event Sequence

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

PunchOut Event Sequence

A PunchOut session is composed of several distinct steps.

Steps 1 & 2: PunchOut Request

Users log in to a procurement application and open new purchase requisitions. They find desired items by searching their local catalogs by commodity, supplier, or product description. When they select a PunchOut item, the procurement application opens a new browser window and logs them into their accounts at the supplier’s website.

The following figure illustrates the PunchOut request steps:

1. Requisitioner selects supplier for PunchOut.

Procurement application makes request to e-commerce network hub.

2. E-commerce network hub authenticates buying organization and opens secure HTTP session with supplier.

cXML User’s Guide 77

PunchOut Event Sequence Chapter 4 PunchOut Transaction

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.

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:

• create

– Initiates a new PunchOut session

• edit

– Re-opens a PunchOut session for editing

• inspect

– Re-opens a PunchOut session for inspection (no changes can be made to the data)

• source

– Initiates a PunchOut session for a RFQ (Request for Quote) create/edit session in a sourcing application

After the supplier’s website receives a request, it sends back a

PunchOutSetupResponse containing a URL that tells the procurement application where to go to initiate a browsing session on the supplier’s website.

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

78 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Event Sequence

Step 3: Product Selection

Users select items from the supplier’s inventory using all the features and services provided by the supplier’s website:

3. Requisitioner uses supplier site to find and configure products.

Depending on the product or customer, these features might include the following:

•

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

Step 4: Check Out

The supplier’s website calculates the total cost of the user’s selections, including tax, freight, and customer-specific discounts. Users then click the supplier’s website’s

“Check Out” button to send the contents of the shopping cart to the their purchase requisitions within the procurement application.

cXML User’s Guide 79

PunchOut Event Sequence

The following figure illustrates the check-out steps:

Chapter 4 PunchOut Transaction

Items then appear in purchase requisition in procurement application.

80

4. Requisitioner checks out of your site.

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.

cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Event Sequence

Step 5: Transmittal of Purchase Order

After the contents of the shopping cart have been passed from the supplier’s website to the user's purchase requisition, the procurement application approval processes take over. When the purchase requisition is approved, the procurement application converts it into a purchase order and sends it back to the supplier’s website for fulfillment. Purchasing card data can be transmitted along with the order, or the supplier can invoice the order separately.

The following figure illustrates purchase order transmittal:

5. When request is fully approved, order is sent to supplier through e-commerce network hub.

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 following reasons:

•

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.

•

PunchOut-enabled suppliers are cXML-aware, so accepting cXML purchase orders is a small incremental effort.

Purchase orders are discussed in detail in Chapter 5, “Purchase Orders.”

cXML User’s Guide 81

PunchOut Documents Chapter 4 PunchOut Transaction

PunchOut Documents

There are four types of cXML documents:

•

PunchOut Index Catalog

•

PunchOutSetupRequest

•

PunchOutSetupResponse

•

PunchOutOrderMessage

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.

PunchOut Index Catalog

PunchOut index catalogs are files that list PunchOut items and point to the supplier’s

PunchOut website.

Type of cXML document and URL of DTD

The supplier’s identifier for the PunchOut item

URL of the PunchOut website (launch page) if not configured elsewhere

The following example shows a PunchOut index catalog:

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

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

<Index>

<SupplierID domain="DUNS">83528721</SupplierID>

<IndexItem>

<IndexItemPunchout>

<ItemID>

<SupplierPartID>5555</SupplierPartID>

</ItemID>

<PunchoutDetail punchoutLevel="shelf">

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

<Description xml:lang="fr-FR">Chaises de Bureau</Description>

<URL>http://www.workchairs.com/punchout.asp</URL>

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

</PunchoutDetail>

</IndexItemPunchout>

</IndexItem>

</Index>

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

.

82 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Documents

punchoutLevel

is an optional attribute that allows suppliers to specify how procurement applications should present the PunchOut item to users. This attribute can have the values store

, aisle

, shelf

, or product

. Procurement applications might display PunchOut items differently, depending on how they are tagged by suppliers. For example, they might display store-level items differently than product-level items.

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, see www.unspsc.org

.

Creating and Publishing Index Catalogs

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.

Users see the contents of the supplier’s PunchOut index catalogs alongside regular, static catalog items.

PunchOut Item Granularity

The supplier can create store-level, aisle-level, or product-level catalogs.

•

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.

•

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.

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.

cXML User’s Guide 83

PunchOut Documents Chapter 4 PunchOut Transaction

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.

Originator (buying organization)

Destination (supplier)

Previous relaying entity

(Network hub in this case)

Type of request

Destination for final

PunchOutOrderMessage

Following is a sample PunchOutSetupRequest document:

<?xml version="1.0"?>

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

<cXML xml:lang="en-US" payloadID="933694607118.1869318421@jlee" timestamp="2002-08-15T08:36:47-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>Procurement System 2.0</UserAgent>

</Sender>

</Header>

<Request>

<PunchOutSetupRequest operation="create">

<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=NAwl4Jo</URL>

</BrowserFormPost>

<SupplierSetup>

<URL>http://www.workchairs.com/punchout.asp</URL>

</SupplierSetup>

<ShipTo>

<Address addressID="1000467">

<Name xml:lang="en">1000467</Name>

<PostalAddress>

<DeliverTo>John Smith</DeliverTo>

<Street>123 Main Street</Street>

84 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Documents

Item selected by user

<City>Sunnyvale</City>

<State>CA</State>

<PostalCode>94089</PostalCode>

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

</PostalAddress>

</Address>

</ShipTo>

<SelectedItem>

<ItemID>

<SupplierPartID>5555</SupplierPartID>

</ItemID>

</SelectedItem>

</PunchOutSetupRequest>

</Request>

</cXML>

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 the Ariba Supplier

Network) change the

Sender

element.

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

.

Create, Edit, Inspect, and Source Operations

The operation

attribute specifies the type of session the buyer initiates. It can create

, edit

, inspect, or

source

.

•

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

cXML User’s Guide 85

PunchOut Documents

86

Chapter 4 PunchOut Transaction

The following example lists an edit

request:

<?xml version="1.0"?>

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

<cXML xml:lang="en-US" payloadID="933695135608.677295401@jlee" 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.

cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Documents

Authentication by an E-commerce Hub

PunchOutSetupRequest

documents route through an e-commerce hub for authentication and to look up the URL of the supplier’s PunchOut website. The steps are:

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

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

7.

The supplier can use the

Contact

and extrinsic data in the body of the request to uniquely identify the user (for example, John Smith in Finance at acme.com).

The

PunchOutSetupRequest

and

PunchOutSetupResponse

documents pass through the e-commerce hub for authentication. The

PunchOutOrderMessage

document (returning the contents of the shopping basket to the procurement application) travels directly between the supplier’s website and the procurement application through standard

HTML Form submission.

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

Supplier Setup URL and SelectedItem

In previous cXML releases, the

SupplierSetup

element provided the only way to specify the URL of the supplier’s PunchOut website. Beginning with cXML 1.1, the ecommerce 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.

cXML User’s Guide 87

PunchOut Documents Chapter 4 PunchOut Transaction

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.

Contact Data and Extrinsic Data for User Identification

The

PunchoutSetupRequest

document can contain detailed user information in the

Contact

element that the supplier’s website can use to authenticate and direct users, such as:

•

User name and role

•

E-mail address

In addition, the

PunchOutSetupRequest

might also contain extrinsic data, data that the supplier can use to further identify users, such as:

•

User cost center and subaccount

•

Region

•

Supervisor

•

Default currency

Buying organizations configure their procurement applications to insert contact

and extrinsic data. Ask the supplier’s customers what data the supplier can expect to receive.

PunchOutSetupResponse

After receiving a PunchOutSetupRequest, the supplier’s website sends a

PunchOutSetupResponse

. The PunchOutSetupResponse document serves two functions:

•

It indicates that the PunchOutSetupRequest was successful.

•

It provides the procurement application with a redirect URL to the supplier’s Start

Page.

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.

88 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Documents

The following example lists a PunchOutSetupResponse document:

<?xml version="1.0"?>

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

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

</StartPage>

</PunchOutSetupResponse>

</Response>

</cXML>

PunchOutOrderMessage

After the user selects items on the supplier’s website, configures them, and clicks the 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.

The following example lists a PunchOutOrderMessage:

<?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>

<To>

<Credential domain="DUNS">

<Identity>65652314</Identity>

</Credential>

</To>

<Sender>

<Credential domain="workchairs.com">

<Identity>website 1</Identity>

cXML User’s Guide 89

PunchOut Documents Chapter 4 PunchOut Transaction

</Credential>

<UserAgent>Workchairs cXML Application</UserAgent>

</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>

BuyerCookie

enables the procurement application to associate a given

PunchOutOrderMessage

with its originating

PunchOutSetupRequest

. Therefore, the supplier’s website should return this element whenever it appears. Do not use the

BuyerCookie

to track PunchOut sessions, because it changes for every session, from create

, to inspect

, to edit

.

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.

90 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction Modifications to the Supplier’s Web Pages

Note:

Procurement applications might use

SupplierPartAuxiliaryID

as part of the unique identifier for items, so PunchOut sites should not change this value during PunchOut edit

or inspect

sessions.

UnitOfMeasure

describes how the product is packaged or shipped. For more

information, see “UnitOfMeasure” on page 58.

Classification

lists the UNSPSC (United Nations Standard Products and Services Code) commodity code for each selected item. These codes are used by back-end systems within buyer and supplier organizations for accounting and report generation. For the list of UNSPSC codes, see www.unspsc.org

.

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:

•

Launch Page

•

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 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 supplier’s Launch Page extracts elements from the document in order to:

1.

Identify the user and determine where to redirect that user.

2.

Compose a

PunchOutSetupResponse

document and return it to the sender.

cXML User’s Guide 91

Modifications to the Supplier’s Web Pages Chapter 4 PunchOut Transaction

The supplier’s Launch Page should store the following data for use by the supplier’s

Start Page:

•

Identity of the requester (

Sender

)

•

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 twoChar( str )

{ var retStr; str = str.toString(); if ( 1 == str.length ) { retStr = "0" + str;

} else { retStr = str;

} return retStr;

}

92 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction Modifications to the Supplier’s Web Pages

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(); milli = milli.toString(); if ( 3 == milli.length ) { str += milli;

} else { str += "0" + twoChar( milli );

} str += "-08:00"; return str;

} 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(); 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;

}

</script>

<%

REM Create data needed in prolog.

Randomize randStr = Int( 100000001 * Rnd ) prologStr = genProlog( "1.0", randStr )

Response.ContentType = "text/xml"

Response.Charset = "UTF-8"

%>

<%

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="

cXML User’s Guide 93

Modifications to the Supplier’s Web Pages Chapter 4 PunchOut Transaction

Dim ret

Dim punch

Dim statusText

Dim statusCode

Dim cookie

Dim url

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

REM This command reads the incoming HTTP cXML request xml = Request.BinaryRead(Request.TotalBytes) for i = 1 to Request.TotalBytes

xmlstr = xmlstr + String(1,AscB(MidB(xml, i, 1)))

Next cookie = elementValue(xmlstr, "<BuyerCookie>") url = elementValue(xmlstr, "<URL>") fromUser = elementValue(xmlstr, "<Identity>") newXMLStr = Right(xmlstr, Len(xmlstr) - (InStr(xmlstr,"<Identity>") + Len("<Identity>"))) toUser = elementValue(newXMLStr, "<Identity>")

%>

REM This formats the cXML PunchOutSetupReponse

<% if IsEmpty(cookie) then %>

<%= prologStr %>

<Response>

<Status code="400" Text="Bad Request">Invalid Document. Unable to extract

BuyerCookie.</Status>

</Response>

</cXML>

<% else %>

<%= prologStr %>

<Response>

<Status code="200" text="OK"/>

<PunchOutSetupResponse>

<StartPage>

<URL>http://<%= Request.ServerVariables("LOCAL_ADDR")%>/<%= dir%>/punchoutredirect.asp?bc=<%= cookie%>&amp;url="<%= url%>"&amp;from=<%= fromUser%>&amp;to=<%= toUser%>&amp;redirect=<%= StartPage%></URL>

</StartPage>

</PunchOutSetupResponse>

</Response>

94 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction Modifications to the Supplier’s Web Pages

</cXML>

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

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

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.

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

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.

cXML User’s Guide 95

Modifications to the Supplier’s Web Pages Chapter 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>

<TR>

<TD><IMG src="UrbanHouses_files/uhjm.gif"> </TD>

<TD><STRONG>Jefferson Memorial</STRONG>- A birdfeeder with a rotunda!

This famous American monument will be a unique addition to any garden or yard. It attracts small to medium sized birds and its dimensions are 11" x 9 1/2" x 8" H.

</TD>

</TR>

</TBODY>

</TABLE><BR>

-Jefferson Memorial<STRONG>

$139.95</STRONG><BR>

<% AddBuyButton 139.95,101,"Bird Feeder, Jefferson Memorial",5 %>

<BR>

<HR>

The

AddBuyButton

function sends the

PunchOutOrderMessage

back to the user.

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=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?>

<!DOCTYPE cXML SYSTEM

&quot;http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd&quot;>

<cXML payloadID=&quot;<%= Now &"@"&

Request.ServerVariables("LOCAL_ADDR")%>&quot; timestamp=&quot;<%= Now

%>&quot;>

<Header>

<From>

<Credential domain=&quot;hub.com&quot;>

<Identity><%= toUser%></Identity>

</Credential>

</From>

<To>

<Credential domain=&quot;hub.com&quot;>

96 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction Modifications to the Supplier’s Web Pages

<Identity><%= fromUser%></Identity>

</Credential>

</To>

<Sender>

<Credential domain=&quot;hub.com&quot;>

<Identity><%= toUser%></Identity>

</Credential>

<UserAgent>PunchoutSite</UserAgent>

</Sender>

</Header>

<Message>

<PunchOutOrderMessage>

<BuyerCookie><%= buyerCookie%></BuyerCookie>

<PunchOutOrderMessageHeader operationAllowed=&quot;edit&quot;>

<Total>

<Money currency=&quot;USD&quot;><%= unitPrice%></Money>

</Total>

</PunchOutOrderMessageHeader>

<ItemIn quantity=&quot;1&quot;>

<ItemID>

<SupplierPartID><%= supPartId%></SupplierPartID>

<SupplierPartAuxiliaryID><%= supPartAuxId%>

</SupplierPartAuxiliaryID>

</ItemID>

<ItemDetail>

<UnitPrice>

<Money currency=&quot;USD&quot;><%= unitPrice%>

</Money>

</UnitPrice>

<Description xml:lang=&quot;en&quot;><%= desc%>

</Description>

<UnitOfMeasure>EA</UnitOfMeasure>

<Classification domain=&quot;SupplierPartID&quot;><%= supPartId%>

</Classification>

</ItemDetail>

</ItemIn>

</PunchOutOrderMessage>

</Message>

</cXML>

<% end function function AddBuyButton(unitPrice, supPartId, supPartAuxId, desc) toUser = Session("toUser") fromUser = Session("fromUser") buyerCookie = Session("buyercookie")

cXML User’s Guide 97

Modifications to the Supplier’s Web Pages Chapter 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>

<% end if end function

%>

The

AddBuyButton

function contains the

FORM POST

that sends the URL-encoded

PunchOutOrderMessage

back to the user.

HTTP Form Encoding

To send a

PunchOutOrderMessage

, the supplier uses HTML form encoding, which is a different transport model from the traditional HTTP request/response model. This different transport facilitates easier integration between the supplier’s website and the procurement application. It also enables buying organizations to receive XML data without requiring them to have a Web server available through a firewall.

Instead of sending a PunchOutOrderMessage directly to the procurement application, the supplier’s website encodes it as a hidden HTML Form field and the user’s browser submits it to the URL specified in the

BrowserFormPost

element of the

PunchOutSetupRequest

. The hidden HTML Form field must be named either cxmlurlencoded

or cxml-base64, both case insensitive. Taken from the above example, the following code fragment inserts a hidden form field named cxml-urlencoded

containing the PunchOutOrderMessage document to be posted:

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

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.

98 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Website Suggestions

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.

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

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:

•

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.

•

Send a unique, temporary URL for the session on redirect.

•

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

(United Nations Standard Products and Services Code).

•

Provide real value to the supplier’s customers. Display product availability, order status, and special promotions.

cXML User’s Guide 99

PunchOut Website Suggestions Chapter 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 customers’ procurement applications.

•

PunchOut transactions produce quotes, not purchase orders. Implement a cXML purchase-order receiving page to accept orders.

Buyer and Supplier Cookies

The buyer and supplier cookies enable both buyers and suppliers to re-instantiate their own line-item data for their back-end systems.

•

The supplier should return the

BuyerCookie element they receive. It should not be changed.

•

Make use of the supplier cookie (

SupplierPartAuxiliaryID

).

The buyer cookie is analogous to a purchase requisition number; it conveys state information that allows the buying organization’s system to maintain the relationship between a requisition and a shopping basket.

Likewise, the supplier cookie is analogous to a quote number; it conveys state information that allows the supplier’s system to maintain a relationship between a shopping basket and the buyer’s requisition and purchase order. Procurement applications pass the supplier cookie back to the supplier in subsequent PunchOut edit or inspect

sessions, and in the resulting purchase order. The supplier’s website should take advantage of the supplier cookie to eliminate the need to pass visible, supplierspecific data back to the buyer.

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.

100 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Transaction

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.

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.

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.

PunchOutSetupRequest

and

PunchOutSetupResponse

are the request/response pair used to set up a PunchOut session to a remote system. The client uses them to identify the 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

P

ROCUREMENT

A

PPLICATION

Network

2. PunchOutSetupResponse

3. PunchOutOrderMessage

S

UPPLIER

cXML User’s Guide 101

PunchOut Transaction Chapter 4 PunchOut Transaction

Sourcing

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.

At the end of each user session, a PunchOutOrderMessage is sent by the sourcing application to the procurement application and contains either a new RFQ, update information for an existing RFQ, or a completed RFQ. For information on using this feature, see

“PunchOutOrderMessage” on page 108.

PunchOutSetupRequest

The PunchOutSetupRequest document contains a

Header

element and a

PunchOutSetupRequest

element.

Header

The

Header

element contains addressing and authentication information. Following is a sample

Header

element in a PunchOutSetupRequest.

<Header>

<From>

<Credential domain="DUNS">

<Identity>65652314</Identity>

</Credential>

</From>

<To>

<Credential domain="DUNS">

<Identity>83528721</Identity>

</Credential>

</To>

<Sender>

<Credential domain="NetworkId">

<Identity>AN12345</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>Procure Software 3.3</UserAgent>

</Sender>

</Header>

From

The buying organization originating the PunchOutSetupRequest.

102 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Transaction

To

The supplier destination of the PunchOutSetupRequest.

Sender

Authentication details of the buying organization including

Identity

,

SharedSecret

(password), and AribaNetworkId, which is specified by

Credential domain

. The

SharedSecret

is the supplier's password or login to the PunchOut site.

UserAgent

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

A

PunchOutSetupRequest

element is contained within the

Request

element. The following diagram shows the structure of the

PunchOutSetupRequest

element.

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>

cXML User’s Guide 103

PunchOut Transaction Chapter 4 PunchOut Transaction

<BrowserFormPost>

<URL>http://orms.acme.com:1616/punchoutexit</URL>

</BrowserFormPost>

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

PunchOutSetupRequest

has the following attribute:

operation

Specifies the type of

PunchOutSetupRequest

: “create”, “inspect”,

“edit” or “source”.

This element also contains the following elements:

BuyerCookie

,

Extrinsic

,

BrowserFormPost

,

Contact

,

ShipTo

,

SelectedItem

,

SupplierSetup

and an

ItemOut

list. Only the

BuyerCookie

element is required. The structure of

Extrinsic

,

Contact,

and

ShipTo

elements

is discussed in more detail in “OrderRequestHeader Element” on page 120. The

ItemOut

element is discussed in “ItemOut” on page 130. In this context (outside of an

OrderRequest

), the

Distribution

and

Comments

elements and lineNumber

, requisitionID

, and requestedDeliveryDate

attributes of an

ItemOut

add little or no value and should not be included. Because PunchOut sessions take place before ordering, this information is not relevant within a

PunchOutSetupRequest

.

104 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Transaction

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 109 and

“Empty Shopping Carts” on page

110). This list can also describe items to be sourced. For more information, see

“Sourcing” on page 102.

The

Credential

of the supplier is used to obtain the PunchOut location from the Ecommerce 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 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.

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

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.

Extrinsic

elements are intended to provide additional machine-readable information.

They extend the cXML protocol to support features not required by all implementations. In the following context, the new data further describes the user initiating the PunchOut request.

cXML User’s Guide 105

PunchOut Transaction Chapter 4 PunchOut Transaction

<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>"

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

,

LaborDetail

, and

ContractItem

elements. These contexts are described further elsewhere in this document.

SelectedItem

An optional

SelectedItem

element allows suppliers to specify PunchOut for an entire store or any subset of product offerings. Suppliers can create their catalogs so that

SelectedItem

leads to store-, aisle-, or product-level PunchOut. Procurement applications can include the

SelectedItem

element in PunchOutSetupRequest documents, and PunchOut sites can use it to determine which products to display to users. The more specific the item is in the catalog, the less searching users have to do at the supplier’s website. If there is no

SelectedItem

, suppliers should present their entire (store-level) product offerings.

A

SelectedItem

contains an

ItemID

, for example:

<SelectedItem>

<ItemID>

<SupplierPartID>5555</SupplierPartID>

</ItemID>

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

This element is usually present in create

operations. Procurement applications that allow users to punch out directly from a supplier listing should leave out

SelectedItem in that case.

106 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Transaction

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.

SelectedItem

should not be used in a source

operation.

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

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:

<PunchOutSetupResponse>

<StartPage>

<URL> http://premier.workchairs.com/store?23423SDFSDF23

</URL>

</StartPage>

</PunchOutSetupResponse>

StartPage

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

.

cXML User’s Guide 107

PunchOut Transaction Chapter 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.

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>

A PunchOutOrderMessage document can be empty, which allows users to end

PunchOut shopping sessions without selecting any items. Suppliers can implement a

Cancel

button that generates an empty PunchOutOrderMessage document. Then, both the PunchOut site and the procurement application know when a user has canceled a shopping session, and they can delete the shopping cart, delete items from the requisition, and perform other housekeeping tasks.

108 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Transaction

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.

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.

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

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.

PunchOutOrderMessageHeader

has the following attributes:

operationAllowed quoteStatus

Specifies the operations allowed in subsequent

PunchOutOrderRequests: create

, inspect

, or edit

.

Optional attribute specifies whether the order is “pending” or

“final”. If quoteStatus is “final”, the transaction is complete.

The operationAllowed

attribute controls whether the user can initiate later PunchOut sessions containing data from this

PunchOutOrderMessage

:

•

operationAllowed="create"

: disallows subsequent PunchOut sessions for these items.

Users cannot inspect or edit these items.

•

operationAllowed="inspect"

: allows subsequent PunchOut sessions only to inspect these items. The items cannot be changed.

•

operationAllowed="edit"

: allows subsequent PunchOut sessions to both inspect and change these items.

cXML User’s Guide 109

PunchOut Transaction Chapter 4 PunchOut Transaction

The quoteStatus

attribute is used for a 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.

Empty Shopping Carts

The PunchOutOrderMessage can contain a list of items corresponding to a shopping cart on the supplier website. It always indicates the end of the interactive PunchOut session. The following list describes a few cases when there are no items in the

PunchOutOrderMessage. These messages allow clients to resume immediately when the user leaves the supplier website.

•

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

.

110 cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Transaction

ItemIn

has the following attributes:

quantity lineNumber

(optional)

The number of items selected by the user on the remote website. Because the supplier site can enforce rules for partial units, the protocol allows fractional quantities. Should never be negative.

The position of this item within an order. Because PunchOut sessions normally take place prior to ordering and the server cannot control placement of items within an order in any case, this attribute is not relevant within a PunchOutOrderMessage.

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 134,

“FeeDetail” on page 154,

“LaborDetail” on page 155, and

“Extrinsic” on page 129.

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

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.

cXML User’s Guide 111

PunchOut Transaction

112

Chapter 4 PunchOut Transaction

If

SupplierPartAuxiliaryID

contains special characters (for example, if it contains additional XML elements not defined in the cXML protocol), they must be escaped properly. Due to the necessity to pass

SupplierPartAuxiliaryID

information through applications and back to the originating supplier, an internal subset containing any 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.

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.

ShortName

is a short (30-character recommended, 50-character maximum) name for the item, which fits product lists presented to users. If provided, clients should present the

ShortName

instead of a truncation of the

Description

text in any restricted fields.

Clients must continue to truncate the

Description

text if no

ShortName

is provided.

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>

cXML User’s Guide 1.2.021 November 2009

Chapter 4 PunchOut Transaction PunchOut Transaction

The

ShortName 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

.

SupplierList

In a sourced RFQ PunchOutOrderMessage, the

ItemOut

and

ItemIn

elements can specify a list of suppliers that can be involved in a sourcing process.

SupplierList contains the

Name

and the list of

SupplierID s for each supplier. The following

ItemOut example shows a

SupplierList

with two suppliers.

<ItemOut quantity="6" lineNumber="1">

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

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

<Supplier>

<Name xml:lang="en">Supplier #2 </Name>

<SupplierID domain="duns">1111111</SupplierID>

<SupplierID domain="duns">2222222</SupplierID>

</Supplier>

</SupplierList>

</ItemOut>

cXML User’s Guide 113

Direct PunchOut Chapter 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 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:

• MAC Authentication

— The server interprets a Message Authentication Code

(MAC) in the

Sender

credential in

PunchOutSetupRequest

documents. This method is

discussed in “Message Authentication Code (MAC)” on page 335.

• Auth Transaction

— The server asks a network commerce hub to authenticate the client’s digital certificate and caches the response for subsequent PunchOut requests. This method is discussed in

“Auth Transaction” on page 340.

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>

For more information about these options, see

“PunchOutSetupRequest Options” on page 65.

114 cXML User’s Guide 1.2.021 November 2009

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

This chapter describes:

•

Purchase Order Process

•

OrderRequest Documents

•

Response to an OrderRequest

•

Accepting Order Attachments

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

cXML User’s Guide 115

OrderRequest Documents Chapter 5 Purchase Orders

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:

116 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

The following example shows the structure of the

OrderRequest

element:

<OrderRequest>

<OrderRequestHeader … >

…

</OrderRequestHeader>

<ItemOut … >

…

</ItemOut>

<ItemOut … >

…

</ItemOut>

</OrderRequest>

cXML User’s Guide 117

OrderRequest Documents Chapter 5 Purchase Orders

The following example shows an

OrderRequest

for an item:

<?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="93369535150910.10.57.136" timestamp="2000-08-

03T08:49:11+07:00">

<Header>

<From>

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

</Credential>

</From>

<To>

<Credential domain="DUNS">

<Identity>114315195</Identity>

</Credential>

</To>

<Sender>

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

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

</Sender>

</Header>

<Request>

<OrderRequest>

<OrderRequestHeader orderID="DO102880" orderDate="2000-08-03T08:49:09+07:00" type="new">

<Total>

<Money currency="USD">4688.00</Money>

</Total>

<ShipTo>

<Address isoCountryCode="US" addressID="1000467">

<Name xml:lang="en">Acme, Inc.</Name>

<PostalAddress name="default">

<DeliverTo>John Q. Smith</DeliverTo>

<DeliverTo>Buyers Headquarters</DeliverTo>

<Street>123 Main Street</Street>

<City>Mountain View</City>

<State>CA</State>

<PostalCode>94089</PostalCode>

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

</PostalAddress>

<Email name="default">[email protected]</Email>

<Phone name="work">

<TelephoneNumber>

<CountryCode isoCountryCode="United States">1</CountryCode>

<AreaOrCityCode>800</AreaOrCityCode>

<Number>5555555</Number>

118 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

</TelephoneNumber>

</Phone>

</Address>

</ShipTo>

<BillTo>

<Address isoCountryCode="US" addressID="12">

<Name xml:lang="en">Acme Accounts Payable</Name>

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

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

<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" lineNumber="1">

<ItemID>

<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&quot; TFT XGA Display

</Description>

<UnitOfMeasure>EA</UnitOfMeasure>

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

<URL>http://www.supplier.com/Punchout.asp</URL>

cXML User’s Guide 119

OrderRequest Documents Chapter 5 Purchase Orders

<Extrinsic name="ExtDescription">Enhanced keyboard</Extrinsic>

</ItemDetail>

<Distribution>

<Accounting name="DistributionCharge">

<AccountingSegment id="7720">

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

<Description xml:lang="en-US">Office Supplies

</Description>

</AccountingSegment>

<AccountingSegment id="610">

<Name xml:lang="en-US">Cost Center</Name>

<Description xml:lang="en-US">Engineering Management

</Description>

</AccountingSegment>

</Accounting>

<Charge>

<Money currency="USD">4688.00</Money>

</Charge>

</Distribution>

</ItemOut>

</OrderRequest>

</Request>

</cXML>

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>

120 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

</Address>

</ShipTo>

<BillTo>

<Address>

<Name xml:lang="en">Acme Corporation</Name>

<PostalAddress name="Finance Building">

<Street>124 Anystreet</Street>

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

</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>

<PaymentTerm payInNumberOfDays="30">

<Discount>

<DiscountPercent percent="2">

</Discount>

</PaymentTerm>

<PaymentTerm payInNumberOfDays="20">

<Discount>

<DiscountPercent percent="3">

</Discount>

</PaymentTerm>

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

cXML User’s Guide 121

OrderRequest Documents Chapter 5 Purchase Orders

</Comments>

<SupplierOrderInfo orderID=12345>

</OrderRequestHeader>

OrderRequestHeader

has the following attributes:

orderID orderDate orderType

(optional)

releaseRequired

(optional)

type

(optional)

orderVersion

(optional)

isInternalVersion

(optional)

agreementID

(optional)

agreementPayloadID

(optional)

parentAgreementID

(optional)

parentAgreementPayloadI

D

(optional)

The identifier for this order. Analogous to the purchase order number.

The date and time this order was placed, in ISO

8601 format.

Type of order: regular

, release

(a release against a master agreement or against a blanket purchase order), or blanket (a blanket purchase order).

Used only if orderType is blanket

to indicate whether the blanket order requires releases

(purchase orders). If “yes” is specified, the blanket order requires separate release orders before the supplier can act. If not specified, the supplier can act on the blanket order itself. The default is unspecified.

Type of request: new (default), update , or delete .

Update and delete orders must use the

DocumentReference

element with the

PayloadId to refer to the original purchase order. See

“DocumentReference Element” on page 211.

Specifies the order version number of change orders, starting with “1” for the original order.

Indicates whether the order includes changes that are relevant only within the buying organization. For example, a minor change was made that does not affect information used by the supplier. Suppliers might not see internal order versions, depending on their customers' configuration.

Used only if orderType is release to indicate the buyer’s identifier for associated master agreement or blanket purchase order.

Used only if orderType is release to indicate the cXML document payload ID for the associated master agreement or blanket purchase order.

Used only if orderType is blanket to indicate the parent blanket order.

Used only if orderType is blanket

to indicate the document reference identifier for the parent blanket order.

122 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents effectiveDate expirationDate

(optional)

requisitionID

(optional)

shipComplete

(optional)

Required if orderType is blanket

to indicate the date the blanket order becomes effective (the date from which releases can be created or invoices submitted for the blanket order).

Used only if orderType is blanket

to indicate the date the blanket order expires. Releases cannot be created against the blanket order after this date.

The buyer’s requisition identifier for this entire order. It might be the same as orderID

, and it might not be included at all. Must not be included if requisitionID is specified in any

ItemOut

elements.

A preference against partial shipments. The only allowed value is “yes”. By default, items are shipped when available.

Because orders might include items with varying

ShipTo

elements, only groups of items with common shipping locations should be held until complete when shipComplete=“yes” .

OrderRequestHeader

and

ItemOut

(when extended with

ItemDetail

) contain similar information. Where

OrderRequestHeader

includes overall billing (

BillTo

) and payment

(

Payment, PaymentTerm

) information,

ItemOut

describes the individual items (in

ItemID

,

ItemDetail, SpendDetail

, and

Distribution

).

Do not use the information in

OrderRequestHeader

as the default for item-specific elements. If present,

ShipTo

,

Shipping

,

Contact

, and each named

Extrinsic

must appear either with every

ItemOut

or in the

OrderRequestHeader

. The

Comments

and

Tax

elements can appear simultaneously at both levels; however, the header-level

Tax

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

The following example shows an

OrderRequestHeader

for a blanket order:

<OrderRequestHeader parentAgreementPayloadID="1184102133611.2058850054.000000002@1zVE0KpzNZL

O9HTrpqF27NebqbI=" parentAgreementID="BPO31" expirationDate="2007-07-

31T23:59:59-07:00" orderDate="2007-07-10T14:37:31-07:00" orderID="BPO36" orderVersion="1" effectiveDate="2007-07-10T00:00:00-07:00" releaseRequired="yes" orderType="blanket" type="new">

Total

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.

cXML User’s Guide 123

OrderRequest Documents Chapter 5 Purchase Orders

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 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:

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

124 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

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.

The

Tax

element supports the

Extrinsic

element for additional tax-related information.

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

InvoiceDetailPaymentTerm

previously defined.

PaymentTerm

defines either the net term

(without discount) or the discount term (with discount).

PaymentTerm

has one attribute:

payInNumberOfDays

Indicates the invoice must be paid in a certain number of days after the invoice effective date.

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

Do not use the

Discount

element if the

PaymentTerm

is a net term.

cXML User’s Guide 125

OrderRequest Documents Chapter 5 Purchase Orders

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 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 provides alternatives to these extrinsics.

Buying organizations might use this element to identify the original 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.

Contact

has the following attributes:

The position of this person within the procurement process.

role

(optional)

addressID

(optional)

An ID for the address. addressID is supports address codes for relationships that require id references.

Possible values for the role

attribute:

role value

endUser administrator purchasingAgent technicalSupport customerService sales supplierCorporate supplierMasterAccount

SupplierAccount buyerCorporate buyerMasterAccount buyerAccount

Description

Contact details about the end user.

Contact details about the administrator.

Contact details about the purchasing agent.

Technical support contact

Customer service contact

Sales contact

Contact details about the supplier.

Contact details about the supplier master account.

Contact details about the supplier account.

Contact details the supplier has about the buying organization.

Contact details about the buyer master account.

Contact details about the buyer account.

126 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents role value

buyer subsequentBuyer

Description

Contact details about the buyer.

Contact details about the subsequent buyer.

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

The

TelephoneNumber

element contains the telephone number of the person or department where the goods are to be shipped or billed. For example, a telephone number in the United States:

<TelephoneNumber>

<CountryCode isoCountryCode="US">1</CountryCode>

<AreaOrCityCode>800</AreaOrCityCode>

<Number>5551212</Number>

</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>"

The following, therefore, is an example for London:

<TelephoneNumber>

<CountryCode isoCountryCode="UK">44</CountryCode>

<AreaOrCityCode>137</AreaOrCityCode>

<Number>2801007</Number>

</TelephoneNumber>

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.

cXML User’s Guide 127

OrderRequest Documents Chapter 5 Purchase Orders

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.

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>

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

Use

Comments to provide local comments specific to the current document.

Followup

The use of the

Followup

element is strongly discouraged. In early implementations,

Followup

was used to specify the URL to which future

StatusUpdateRequest

documents should be posted.

All cXML implementations should use the more robust Profile transaction to retrieve 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.

128 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

DocumentReference

This element provides an exact reference to an earlier document (for example,

OrderRequest,MasterAgreementRequest, or InvoiceReference

). In a

StatusUpdateRequest

,

DocumentReference

identifies the purchase order to be updated.

SupplierOrderInfo

This element is used in

OrderRequestHeader

to define supplier sales order information related to the current order.

SupplierOrderInfo

is used in

OrderRequest

and

InvoiceDetailRequest

documents.

When

SupplierOrderInfo

is used in a

PunchOutOrderMessage

, it indicates that the supplier has created an order associated with the PunchOut order message. The buyer can later cancel the order by sending an

OrderRequest

of type “delete” and including the

SupplierOrderInfo

element in the

OrderRequestHeader

. to refer to the sales order to be deleted.

SupplierOrderInfo

has one attribute:

orderID

Supplier sales order id of this order.

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.

cXML User’s Guide 129

OrderRequest Documents Chapter 5 Purchase Orders

ItemOut

The following example shows a minimum valid

ItemOut

element.

<ItemOut quantity="1" lineNumber=”1”>

<ItemID>

<SupplierPartID>5555</SupplierPartID>

</ItemID>

</ItemOut>

ItemOut

has the following attributes:

quantity lineNumber

(optional)

requisitionID

(optional)

agreementItemNumber

(optional)

requestedDeliveryDate

(optional)

The number of items desired. Fractions are allowed for some units of measure. The value might have already been checked by the supplier during a PunchOut session. This value should never be negative.

Position of the item within an order. This ordinal value increases once per

ItemOut

in a “new”

OrderRequest

.

Clients should always specify this attribute in an

OrderRequest , although it might not be useful in other

ItemOut

contexts.

The buyer’s requisition identifier for this line item. Must not be included if requisitionID is specified in the

OrderRequestHeader .

The buyer’s master agreement identifier for the line item.

isAdHoc

(optional)

The date item was requested for delivery, which allows item-level delivery dates in the OrderRequest . It must be in

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 part numbers. Non-catalog orders usually require special validation and processing.

Users enter non-catalog items to purchase products and services on an ad-hoc basis or because they could not 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.

130 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

The following example shows a more complicated

ItemOut

.

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

cXML User’s Guide 131

OrderRequest Documents Chapter 5 Purchase Orders

</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

</Description>

</AccountingSegment>

</Accounting>

<Charge>

<Money currency="USD">1</Money>

</Charge>

</Distribution>

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

ItemID

The basic

ItemID

element, which provides unique identification of an item.

ItemID is defined at

“ItemID” on page 111.

132 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

Path

The basic

Path

element, which provides node and path information for a document.

Path

is defined at

“Path Element” on page 163.

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

BlanketItemDetail

Provides supplier and commodity level details specific to blanket orders

( orderType=“blanket”

).

BlanketItemDetail

must contain

Description

. Optional elements include

LimitType

,

MaxAmount

,

MinAmount

,

MaxQuantity

,

MinQuantity

,

UnitPrice

,

UnitOfMeasure

, and any number of

Classification

and

Extrinsic

elements.

SupplierID

See “SupplierID” on page 133.

SupplierList

Defines a list of suppliers that might be associated with a quote item in

ItemOut

.

SupplierList

has no attributes.

Supplier

The common

Supplier

element is optional in

ItemOut

.

ShipTo, Shipping, and Tax

The common elements, described elsewhere in this document.

cXML User’s Guide 133

OrderRequest Documents Chapter 5 Purchase Orders

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

SpendDetail

has no attributes.

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

TravelDetail

TravelDetail

describes information about travel line items.

The following diagram shows the structure of

TravelDetail

:

134 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

The following example shows the location of

SpendDetail

and

TravelDetail

within an

OrderRequest

document:

<OrderRequest... >

<OrderRequestHeader >

...

</OrderRequestHeader >

<ItemOut>

<ItemDetail >

...

</ItemDetail>

<SpendDetail>

<TravelDetail>

...

</TravelDetail>

</SpendDetail>

</ItemOut>

</OrderRequest>

TravelDetail

has the following attributes:

confirmationNumber pnrLocator

(optional)

quoteExpirationTime

(optional)

A unique confirmation number that is understood by both the traveler and the vendor who is providing the service for this travel line item. For example, hotel reservation number or e-ticket number from the airline.

Passenger Name Record (PNR) locator used by the travel booking provider.

Date and time that this quote will expire. This value is normally supplied in the PunchoutOrderMessage. If no value is supplied, it is assumed that this quote will not expire.

Common Elements

Several common elements are used throughout

TravelDetail

.

Date and Time in cXML

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/NOTEdatetime-970915.html

. See

“Date, Time, and other Data Types” on page 40

for more information.

cXML User’s Guide 135

OrderRequest Documents Chapter 5 Purchase Orders

Vendor

The common

Vendor

element. When used in

TravelDetail

,

Vendor

provides information about a vendor of a service.

Vendor

can be used in

AirLeg

,

CarRentalDetail

,

HotelDetail

, and

RailLeg

.

Vendor

has one attribute:

preferred

Is this a preferred vendor? yes | no

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.

SupplierID has one required attribute:

domain

(required)

Domain of the supplier ID.

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.

136 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

Description

Text description of terms and conditions. If

TermsAndConditions

is present,

Description

is required.

PolicyViolation

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.

PolicyViolation

has one attribute:

level

The level of the PolicyViolation : warning | violation warning - a non-serious violation violation - a serious violation of company policy

Description

Description is a common free-text element, which provides a textual description of an element, such as

PolicyViolation

.

PolicyViolationJustification

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

Penalty (if any) for this travel segment.

Money

The penalty amount.

Description

Textual description of the cause of the penalty. For example, a change fee associated with an air ticket.

cXML User’s Guide 137

OrderRequest Documents Chapter 5 Purchase Orders

AvailablePrice

The common

AvailablePrice

element describes other available prices that the user did not select.

AvailablePrice has one attribute:

type

Description of the level of compliance with company policy.

Possible values for the type

attribute of

AvailablePrice

:

Value

lowest lowestCompliant highestCompliant highest other

Description

Lowest price available regardless of the travel policies

Lowest price available that is compliant with travel policies

Highest price available that is compliant with travel policies

Highest price available regardless of the travel policies

Other, specify in the

Description

Money

The amount of an available price.

Description

A text description of an available price, including information on how the price was found or particular requirements for the price.

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>

138 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

</UnitRate>

</Rate>

</CarRentalFee type="baseRate">

Rate

has one attribute, which is required:

quantity

The quantity for the rate. For example, a four-night stay at a hotel would be expressed as: 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 a line item must add up to the

Total

for that line item.

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

Description

Textual description for the rate. For a hotel stay, the

Description

could contain

“hotel nightly rate.”

BookingClassCode

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>

cXML User’s Guide 139

OrderRequest Documents Chapter 5 Purchase Orders

For information on car rental codes, see

CarRentalDetail

.

BookingClassCode has the following attributes:

domain code

The domain for this code, for example, IATA.

An industry standard code, or per agreement of buyertravel booking provider pair.

Description

The

Description

element of

BookingClassCode

contains a text description of the code.

Airport

The common

Airport element, which contains the three-letter IATA airport code, is used in

AirLegOrigin, AirLegDestination

,

CarRentalPickup, CarRentalDropoff

,

HotelDetail

,

RailLegOrigin and

RailLegDestination

.

Airport

has one attribute:

airportCode

The three-letter IATA airport code.

For information on the International Air Transport

Association (IATA) standard, see: www.iata.org/nr/ rdonlyres/3346f400-3450-48a6-a543-86a3921c23f7/0/ xml_fuel_transaction_v202.pdf

.

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.

140 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

BookingClassCode

The common

BookingClassCode

element is defined at

“BookingClassCode” on page 139. The

BookingClassCode

of

Meal

defines the code for the meal. For example, airlines typically use the following meal codes:

R

S

V

O

P

K

L

M

N

D

F

G

H

Code

B

C

Description

Breakfast

Complimentary liquor

Dinner

Food for purchase

Food and beverage for purchase

Hot meal

Continental breakfast

Lunch

Meal

No meal service

Cold meal

Liquor for purchase

Refreshments

Snack or brunch

Refreshments for purchase

AirDetail

The

AirDetail element provides information about an air trip. The following diagram shows the structure of

AirDetail:

AirDetail has no attributes.

cXML User’s Guide 141

OrderRequest Documents Chapter 5 Purchase Orders

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.

For example, a

TripType for a round trip would appear as:

<TripType type="round"></TripType>

The

TripType element has the following attribute: type round : round trip oneWay : one-way trip/ multiLeg

: multi-leg or open-jaw trip

AirLeg

Each

AirDetail

must include at least one

AirLeg

element.

The following diagram shows the structure of

AirLeg

:

142

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:

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

...

</Address>

cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

</Vendor>

<AirLegOrigin>

<Airport airportCode="SFO">

<Address>

...

</Address>

</Airport>

</AirLegOrigin>

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

AirLeg has the following attributes:

travelSegment departureTime arrivalTime flightNumber seatNumber

(optional)

seatType

(optional)

upgrade

(optional)

stops

(optional)

equipment

(optional)

Text description to identify this travel segment. This information is specific to the travel booking provider.

Local departure date and time for this air leg.

Local arrival date and time for this air leg.

Flight number for this air leg.

Seat number for this air leg.

Seat type: window

, aisle

, or middle

Is this ticket an upgrade: no (default), or yes

The number of stop for this air leg. Use a numeral for the number of stops, or ‘0’ (zero) for a direct flight. If no numeral is entered, ‘0’ (zero) is implied.

The plane equipment information for this air leg. For example, the model of airplane used.

cXML User’s Guide 143

OrderRequest Documents Chapter 5 Purchase Orders

Vendor

The common

Vendor

element, which provides information about the vendor

of a service, is defined at “Vendor” on page 136.

AirLegOrigin / AirLegDestination

These elements contain the addresses of the

AirLegOrigin

and

AirLegDestination entities on the

AirLeg

.

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>

</Address>

</Airport>

</AirLegOrigin>

<AirLegDestination>

<Airport airportCode="MIA">

<Address>

<Name xml:lang="en">Miami International Airport</Name>

<PostalAddress>

<Street>4200 NW 21 Street>

<City>Miami</City>

<State>FL</State>

<PostalCode>33122</PostalCode>

<Country isoCountryCode="US">UnitedStates</Country>

</PostalAddress>

</Address>

</Airport>

</AirLegDestination>

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

144 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

For information on the International Air Transport Association (IATA) standard, see:

www.iata.org/codes .

BookingClassCode

The common

BookingClassCode element is defined at

“BookingClassCode” on page 139. The

BookingClassCode element of an

AirLeg

defines the class of travel for the

AirLeg according to the de-facto airline standard. The following table shows sample IATA codes:

F, FN, P, R, A

C, CN, D, J, I, Z

Y, YN, B, BN, M, H, V, VN, O, Q, QN, S, K, KN,

L, U, T, W first class business class coach class

The sample codes are not guaranteed to be accurate or current. For information on the International Air Transport Association (IATA) standard, see:

www.iata.org/codes .

Rate

The common

Rate

element is defined at “Rate” on page 138. 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 140.

AvailablePrice

The optional, common

AvailablePrice

element, which defines available prices that the user did not select, is defined at

“AvailablePrice” on page 138. 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 137. The

Penalty element of an

AirLeg

describes extra charges for changes to, or cancellation of, an air travel reservation.

cXML User’s Guide 145

OrderRequest Documents Chapter 5 Purchase Orders

CarRentalDetail

CarRentalDetail

provides information about a single car rental event.

The following diagram shows the structure of the

CarRentalDetail

element.

146

CarRentalDetail has the following attributes:

travelSegment pickupTime dropoffTime

Text description used to identify this travel segment. The description is specific to the travel booking provider.

Intended local pickup date and time.

Intended local drop-off date and time.

Vendor

The common

Vendor

element, which provides information about the vendor of a service, is defined at

“Vendor” on page 136.

CarRentalPickup / CarRentalDropoff

These elements contain the addresses of the

CarRentalPickup

and

CarRentalDropoff entities on the

CarRentalDetail

. Both

CarRentalPickup

and

CarRentalDropoff

require the common

Airport

element, which specifies the airport location.

cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

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:

1st Letter

2nd Letter

3rd Letter

4th Letter

M (Mini)

E (Economy)

C (Compact)

S (Standard)

I (Intermediate)

F (Full size)

P (Premium)

L (Luxury)

V (MiniVan)

X (Special)

B (2 door)

C (2/4 door)

D (4 door)

T (Convertible)

F (Four wheel drive)

V (Van)

W (Wagon)

S (Sport)

X (Special)

A (Automatic)

M (Manual)

R (A/C)

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.

Note:

Use

TermsAndConditions

text to specify conditional charges for items such as extra mileage that are over the mileage limit.

cXML User’s Guide 147

OrderRequest Documents Chapter 5 Purchase Orders

CarRentalFee has one attribute:

type

The type of fee, expressed in the form “baseRate”.

Possible values for the type

of a

CarRentalFee

are:

Value

additionalDriver airportAccessFee baseRate childSeat collisionDamageInsurance dropOffCharge liabilityInsurance

Description

Additional driver fee

Airport access fee

Base rental rate

Child seat charge

Collision damage insurance

Drop off charge

Liability insurance mobilePhone navigationSystem other prepaidGasoline touristTax vehicleLicensingFee

Mobile phone base charge

Navigation system

Other charges

Prepaid gasoline charge

Tourist tax

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

Fee information for individual charges for this

CarRentalFee

.

LimitedMileage

LimitedMileage

specifies the quantity and unit of measure of the mileage limit.

LimitedMileage has one attribute:

quantity

The mileage limit amount, expressed as a numeral

148 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

UnitOfMeasure

Unit of measure, expressed in miles or kilometers. For more information, see

“UnitOfMeasure” on page 58.

AvailablePrice

The optional, common

AvailablePrice

element, which defines available prices that the user did not select, is defined at

“AvailablePrice” on page 138.

HotelDetail

The following diagram shows the structure of the

HotelDetail

element.

IHotelDetaill has the following attributes:

travelSegment arrivalTime departureTime checkinTime checkoutTime earlyCheckinAllowed

(optional)

lateCheckoutAllowed

(optional)

Text information to identify this travel segment. This information is specific to the travel booking provider.

Local date and time of arrival at the hotel. This is used as an advisory to the hotel vendor for the arrival time.

Local date and time of departure from the hotel. This is an advisory to the hotel vendor for the departure time.

Local official hotel checkin time.

Local official hotel checkout time.

Does the hotel allow early checkin?

no

, or yes (default).

Does the hotel allow late checkout?

no , or yes (default)

cXML User’s Guide 149

OrderRequest Documents Chapter 5 Purchase Orders

Vendor

The common

Vendor

element, which provides information about the vendor of a

service, is defined at “Vendor” on page 136. For

HotelDetail,

the

Vendor

element defines the hotel provider.

Address

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

Information about the type of hotel room reserved.

RoomType

has the following attributes:

smoking numberOfBed

(optional)

bedType

(optional)

Smoking or non-smoking room: yes | no

The number of beds in the room.

The type of bed in the room: king | queen | full | double | single | other

Description

Text description of the hotel room.

Amenities

Text description of amenities. For example, DSL connection, two telephone lines, and other information about a hotel room.

Amenities

has no attributes.

Description

Text description of the amenities. For example, DSL connection, two telephone lines, and other information about the hotel room.

150 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

BookingClassCode

The common

BookingClassCode

element is defined at

“BookingClassCode” on page

139. Each buyer-travel booking provider pair can use any standard they choose.

Meal

The common

Meal

element is defined at “Meal” on page 140. 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 138. The

Rate

element of

HotelDetail

defines one or more rates for the hotel stay. For example, the nightly rate or valet parking rate.

AvailablePrice

The common

AvailablePrice

element is defined at

“AvailablePrice” on page 138. The

AvailablePrice

element of

HotelDetail

defines other available prices that the user did not pick. Available prices can be from the same vendor or another vendor.

RailDetail

The following diagram shows the structure of the

RailDetail

element.

RailDetail

has no attributes.

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.

cXML User’s Guide 151

OrderRequest Documents Chapter 5 Purchase Orders

For example, a

TripType for a round trip would appear as:

<TripType type="round"></TripType>

Possible values for the type

attribute of

TripType

:

Value

round oneWay multiLeg

Description

round trip one-way trip 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

.

The following diagram shows the structure of

RailLeg:

152

RailLeg

has the following attributes:

travelSegment departureTime arrivalTime trainNumber seatNumber carType

Text information to identify this travel segment. This information is specific to the travel booking provider.

Local date and time of departure from the originating location.

Local date and time of arrival at the destination location.

Train number.

Seat number.

The type of the rail car.

cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

Vendor

The common

Vendor

element, which provides information about the vendor

of a service, is defined at “Vendor” on page 136. For

RailLeg

, the

Vendor element defines the rail travel provider, such as Amtrak.

RailLegOrigin / RailLegDestination

RailLegOrigin

and

RailLegDestination have two possible elements, of which exactly one must be included:

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

For information on the International Air Transport Association (IATA) standard, see: www.iata.org/codes

.

Address

The physical address of the rail station.

Neither

RailLegOrigin

nor

RailLegDestination has any attributes.

BookingClassCode

The common

BookingClassCode element is defined at

“BookingClassCode” on page 139. The

BookingClassCode element of a

RailLeg

element defines the class of travel for the

RailLeg according to a rail standard agreed upon by the buyertravel booking provider pair.

Rate

The common

Rate

element is defined at “Rate” on page 138. Rate

information for this rail leg. If specified, all the rates in all rail legs must add up to the total at the travel line item level.

Meal

The common

Meal

element is defined at “Meal” on page 140. The

Meal element of

HotelDetail

defines any complimentary meals that are included with the room, such as complimentary continental breakfast.

cXML User’s Guide 153

OrderRequest Documents Chapter 5 Purchase Orders

AvailablePrice

The common

AvailablePrice

element is defined at

“AvailablePrice” on page 138. The

AvailablePrice

element of

RailDetail

defines other available prices that the user did not pick. Available prices can be from the same vendor or another vendor.

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 137. The

Penalty element of

RailLeg

defines extra charges for changes to, or cancellation of, a rail travel reservation.

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

.

FeeDetail

has the following attribute:

isRecurring

(optional)

Indicates that the fee is recurring.

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.

Period

Defines the period covered by the

FeeDetail

.

154 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

LaborDetail

.

LaborDetail

contains information about an item related to temporary labor. The following diagram shows the structure of the

LaborDetail

element:

LaborDetail

has the following attribute:

supplierReferenceCode

The supplier’s quote or proposal ID, for cross reference.

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

TermReference

is a generic base element that identifies the definition of the

UnitRate

in question.

TermReference

has these attributes:

termName term

The name of the ID attribute containing the term.

The value of that attribute, that is, the term itself.

Here is a sample

UnitRate

with a

TermReference

:

<UnitRate>

<Money currency="USD">75</Money>

<UnitOfMeasure>HUR</UnitOfMeasure>

<TermReference termName="payCode" term="Overtime"/>

</UnitRate>

This

TermReference

identifies this

UnitRate

as being the rate for the Overtime payCode.

cXML User’s Guide 155

OrderRequest Documents Chapter 5 Purchase Orders

Period

Period

specifies the period of time over which the service occurs.

Contractor

Contractor

identifies the 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.”

ContractorIdentifier

ContractorIdentifier

uniquely identifies the contractor for both the buyer and supplier.

ContractorIdentifier

has the following attribute:

domain

Required. The domain in which the contractors identity is represented. This attribute allows the buyer and supplier systems to determine who assigned the identification. buyerReferenceID

implies that the identification was generated in the buyer system.

supplierReferenceID implies that the identification was generated in the supplier system.

Contact

Contact

contains contact element for the contractor.

JobDescription

JobDescription

is a text description of the job or work to be performed.

Supervisor

Supervisor

specifies contact information for the person who will supervise the contractor.

WorkLocation

WorkLocation

is the address of the place where the work is to be performed.

156 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders OrderRequest Documents

Extrinsic

This optional element in

LaborDetail

contains any additional data that the buying organization wants to pass to the supplier. The cXML specification does not define the content of

Extrinsic

elements—it is something that each buying organization and supplier must agree on and implement.

The following example passes the region in which the work is to be performed.

<Extrinsic name=”region"">sfbay</Extrinsic>

Extrinsic

Extrinsic

is supported in

SpendDetail,

enabling buyer-supplier pairs to convey detailed information on spend that does not fit within

TravelDetail

,

FeeDetail

, or

LaborDetail

.

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.

It is recommend that all

Extrinsic

elements in a single

SpendDetail

element be included under a single

Extrinsic

with the name

attribute used to specify the name of the category. This example shows two

Extrinsic

elements nested under one heading, within a

SpendDetail

element:

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

cXML User’s Guide 157

OrderRequest Documents Chapter 5 Purchase Orders

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

The

Accounting

element groups

AccountingSegments

to identify who is charged.

Accounting

has the following attribute:

name

The name for this accounting combination. The account from which this charge will be paid.

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>

AccountingSegment

has the following attribute:

id

The unique identifier within this

AccountingSegment

type.

This value might be the actual account code if the type were

“Cost Center”.

Name

An identifying name for this

AccountingSegment

with respect to the others in the

Accounting element.

Description

A description of the accounting entity.

158 cXML User’s Guide 1.2.021 November 2009

Chapter 5 Purchase Orders Response to an OrderRequest

Charge

This element specifies the amount to be charged to the entity represented by the

Accounting

element.

Money

Contains the amount of the

Charge

at the line item level.

currency

The unique ISO standard three-letter currency code. For example, “USD” = United States Dollar.

Response to an OrderRequest

This document is the response part of the synchronous Request-Response transaction.

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>

As shown above, this

Response

is straightforward. In this case, there is no actual element named “OrderResponse”, because the only data that needs to be sent back to the requestor is the

Status

part of the

Response

.

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 User’s Guide 159

Accepting Order Attachments Chapter 5 Purchase Orders

Accepting Order Attachments

Buyers often need to clarify purchase orders with supporting memos, drawings, or faxes. They can attach files of any type to cXML purchase orders by using MIME

(Multipurpose Internet Mail Extensions).

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.

160 cXML User’s Guide 1.2.021 November 2009

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

This chapter describes:

•

Overview of Path Routing

•

Nodes

•

Adding Nodes to PunchOutOrderMessage

•

Creating OrderRequests

•

Other Routable Documents

•

CopyRequest

Overview of Path Routing

Path routing is especially useful in direct and indirect marketplaces. In direct marketplaces, suppliers bill buyers directly. In indirect marketplaces, suppliers bill and receive payment from the marketplace host, which in turn bills and receives payment from member buyers.

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 buyers. This information also allows a marketplace to support edit/inspect PunchOut from procurement applications because it can distinguish which items in the shopping cart come from an external marketplace by inspecting the

Path

element.

cXML User’s Guide 161

Nodes Chapter 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.

To enable path routing in PunchOut:

1.

Each system adds itself as a node to the

Path

element of

PunchOutOrderMessage

documents sent by suppliers to procurement applications.

2.

Procurement applications generate

OrderRequest

documents by splitting the order based on the

Path

and

SupplierID

of each of the

ItemIn

elements of

PunchOutOrderMessage

documents. Procurement applications put a

Path element at the cXML header level of each

OrderRequest

document.

3.

Subsequent documents, such as

OrderRequest

,

PunchOutSetupRequest

,

ConfirmationRequest

, and

ShipNoticeRequest

documents are routed and copied by using the

Path

element at the header level.

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.

162 cXML User’s Guide 1.2.021 November 2009

Chapter 6 Path Routing Nodes

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">

<Credential domain="NetworkId">

<Identity>AN01000000233</Identity>

</Credential>

</Node>

</Path>

Router Nodes

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

The new document must reference the document it is modifying by adding an

OriginalDocument

element, if it is not already present, at the header level that specifies 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 new version of the updated OrderRequest to reference the correct payloadId as illustrated in the following diagram:

cXML User’s Guide 163

Adding Nodes to PunchOutOrderMessage Chapter 6 Path Routing

Buyer

Create OrderRequest

PayloadID1

OriginalDocument: PayloadID1

(Router Node)

Create OrderRequest

PayloadID2

OriginalDocument: PayloadID1

Supplier

ConfirmationRequest

PayloadID4

OriginalDocument: PayloadID3

DocumentReference: PayloadID1

ConfirmationRequest

PayloadID3

OriginalDocument: PayloadID3

DocumentReference: PayloadID2

Buyer

Update OrderRequest

PayloadID5

OriginalDocument: PayloadID5

DocumentReference: PayloadID1

Marketplace

(Router Node)

Update OrderRequest

PayloadID6

OriginalDocument: PayloadID2

DocumentReference: PayloadID2

Supplier

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>

Adding Nodes to PunchOutOrderMessage

PunchOutOrderMessage

documents generated by PunchOut sessions can go through intermediary sites on their way back to the buyer. Each intermediary site must add itself as a node to the

Path

element of the relevant

ItemIn

elements of the

PunchOutOrderMessage

.

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.

164 cXML User’s Guide 1.2.021 November 2009

Chapter 6 Path Routing Adding Nodes to PunchOutOrderMessage

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

</ItemID>

<Path>

<Node type="copy">

<Credential domain="NetworkId">

<Identity>AN01000000111</Identity>

</Credential>

</Node>

<Node type="route">

<Credential domain="NetworkId">

<Identity>AN01000000233</Identity>

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

cXML User’s Guide 165

Creating OrderRequests Chapter 6 Path Routing

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

.

In

OrderRequest

documents containing PunchOut items, procurement applications must include nodes for both the originating buyer and the supplier of record.

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.

The following example is the header of an

OrderRequest

sent from a procurement application. Because the

From

credential has no type=“marketplace”

, the node sending this

OrderRequest

must be the procurement application. The first node in the path is a marketplace Router node.

<Header>

<From>

<Credential domain="AribaNetworkUserId">

<Identity>[email protected]</Identity>

</Credential>

</From>

<To>

<Credential domain="NetworkId" type="marketplace">

<Identity>AN01000000233</Identity>

</Credential>

<Credential domain="DUNS">

<Identity>942888711</Identity>

</Credential>

</To>

<Sender>

166 cXML User’s Guide 1.2.021 November 2009

Chapter 6 Path Routing Creating OrderRequests

<Credential domain="NetworkId">

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

The following example is an

OrderRequest

from a marketplace Router node:

<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">

<Identity>AN01000000001</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

cXML User’s Guide 167

Other Routable Documents

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

Chapter 6 Path Routing

Other Routable Documents

Follow-up documents such as

PunchOutSetupRequest

,

ConfirmationRequest

, and

ShipNoticeRequest

documents also use the

Path

element to route and copy documents.

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.

ConfirmationRequest and ShipNoticeRequest

Route

ConfirmationRequest

and

ShipNoticeRequest

documents by using the

Path

element from the cXML header of the

OrderRequest

. The Path must be reversed to route the

ConfirmationRequest

or

ShipNoticeRequest

to the originating application.

168 cXML User’s Guide 1.2.021 November 2009

Chapter 6 Path Routing CopyRequest

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.

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

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.

The following example shows a

CopyRequest element forwarding a cXML document that does not itself contain attachments:

Content-Type: Multipart/Related; boundary=mime-boundary

[Other headers]

--mime-boundary

Content-Type: text/xml; charset=UTF-8

Content-ID: <[email protected]>

[Other headers]

<?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="2003-11-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>

cXML User’s Guide 169

CopyRequest Chapter 6 Path Routing

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

For an example showing a

CopyRequest

forwarding a cXML document with

attachments, see “Attachment Examples” on page 35.

170 cXML User’s Guide 1.2.021 November 2009

Chapter 7

Payment

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.

This chapter describes:

•

Overview of Payment

•

PaymentProposalRequest

•

PaymentRemittanceRequest

•

PaymentRemittanceStatusUpdateRequest

•

Example Payment Documents

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.

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.

cXML User’s Guide 171

PaymentProposalRequest Chapter 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

Payment Document Sequence

Procurement applications send

PaymentProposalRequest

and

PaymentRemittanceRequest documents and suppliers respond with generic

Response

documents. When payment transaction status levels are updated, procurement applications send

PaymentRemittanceStatusUpdateRequest

documents. These documents can all pass through a network commerce hub for authentication and routing.

PaymentProposalRequest

cXML

PaymentProposalRequest

documents represent scheduled payments. They list payment amounts and dates and can be for information only or for triggering payment.

After a buying organization sends scheduled payment to a network commerce hub, it can travel immediately to a supplier, or the network commerce hub can store it until the payment date.

172 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentProposalRequest

PaymentProposalRequest

has the following attributes:

paymentProposalID operation isNetworkPayment paymentDate

A buyer-generated identifier for the scheduled payment.

Defines the operation to be performed: new —Creates a new scheduled payment.

update —Updates an existing scheduled payment identified by paymentProposalID

.

delete

—Cancels an existing scheduled payment identified by paymentProposalID . All optional attributes and sub-elements of

PaymentProposalRequest will be ignored.

hold

—Puts on hold an existing scheduled payment identified by paymentProposalID

. All optional attributes and subelements of PaymentProposalRequest are ignored.

True if this scheduled payment is to be paid through a network commerce hub. By default it is false.

The date that payment will be made.

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>

<PayableInvoiceInfo>

<InvoiceIDReference or InvoiceIDInfo>

.....

</InvoiceIDReference or InvoiceIDInfo>

</PayableInvoiceInfo>

</PayableInfo>

The following example shows the structure of a

PayableInfo

element that includes an optional

PayableOrderInfo

:

<PayableInfo>

<PayableInvoiceInfo>

<InvoiceIDReference or InvoiceIDInfo>

<PayableOrderInfo>

<OrderIDInfo>

.....

</OrderIDInfo>

</PayableOrderInfo>

</InvoiceIDReference or InvoiceIDInfo>

</PayableInvoiceInfo>

</PayableInfo>

cXML User’s Guide 173

PaymentProposalRequest

The following diagram shows the structure of

PayableInfo

:

Chapter 7 Payment

174

PayableInfo has no attributes.

PayableInvoiceInfo

A reference to the invoice being paid.

PayableInvoiceInfo

must contain either

InvoiceReference

or

InvoiceIDInfo

, and might contain either

PayableOrderInfo

or

PayableMasterAgreementInfo

.

InvoiceReference

Provides a clear reference to a prior

InvoiceDetailRequest

document. The

InvoiceReference is copied from the

InvoiceDetailRequest

message.

InvoiceIDInfo

Defines the ID of an invoice known to the supplier system.

InvoiceIDInfo

is a container for two attributes:

invoiceID invoiceDate

The ID of an invoice known to the supplier system

The invoice date

PayableOrderInfo

Provides supplementary information related to the order. For example, a payment against a consolidated invoice might include associated order information. Defines payable information related to an order that was paid.

PayableOrderInfo

has no attributes.

cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentProposalRequest

OrderReference

The reference to the order being paid.

OrderIDInfo

The order ID from the procurement application.

PayableMasterAgreementInfo

Provides supplementary information related to the master agreement (contract). For example, a payment against a consolidated invoice might include associated master agreement information. Defines payable information related to the master agreement being paid.

PaymentMethod

The method of payment. Must be provided if isNetworkPayment is true.

Buying organizations use this element to identify the method for a payment.

PaymentMethod

has one attribute:

type

The type of the payment method: ach —Automated Clearing House cash

—Cash payment check

—Check payment creditCard —Credit card or PCard payment debitCard —Debit card payment draft

—A written payment order, directing a second party to pay a third party 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.

cXML User’s Guide 175

PaymentProposalRequest Chapter 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 information of the payment partner.

Contact

has one attribute:

role

The role of the payment partner: payer

—The payer of this transaction payee —The recipient of the payment originatingBank —The bank from which the payment will be drawn.

Required for bank transfers.

receivingBank

—The bank to which the payment will be deposited.

Required for bank transfers.

originatingCorrespondentBank —(optional) The bank that will hold the payment and transfer it to the receiving bank or the receiving correspondent bank receivingCorrespondentBank —(optional) The bank that will receive the payment and transfer it to the receiving bank intermediaryBank

—(optional) The intermediary bank remitTo

—(optional) The supplier’s remittance address. For this role value, the IdReference and PCard elements can be omitted.

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.

The remitTo element must be provided if isNetworkPayment is true.

176 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentProposalRequest

IdReference

Contains a unique identification reference for the payment partner, including information such as bank account identification, bank identification, and optional bank branch identification.

IdReference

is mandatory for all transactions that involve electronic payments. It is optional only for non-electronic payment methods, such as check or cash.

IdReference

has the following attributes:

identifier domain

The unique identifier of the IdReference within the domain

The domain of the IdReference: bankRoutingID

—The routing ID of this payment partner’s bank accountReceivableID

—The ID of the payee’s accounts receivable account or department bankAccountID —The ID of this payment partner’s bank account ibanID

—The International Bank Account Number for this payment partner, as specified in ISO 13616 abaRoutingNumber —The American Banking Association 9-digit routing transit number of this payment partner’s bank bankNationalID

—A national clearing code that is specific to a country.

This should uniquely identify the bank within the country specified in 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

The value supplierTaxID

is deprecated and will be treated as federalTaxID

.

cXML User’s Guide 177

PaymentProposalRequest Chapter 7 Payment

The bank account identification is specified as follows:

identifier domain

The unique identifier of the

IdReference

within the domain

The domain of the account ID abaRoutingNumber —ABA (American Banking Association) routing number swiftID

—SWIFT ID (Society for Worldwide Interbank Financial

Telecommunications) identification number chipsID —CHIPS ID (Clearing House Interbank Payment System) identification number 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).

bankNationalID —If none of the above bank identification methods is applicable, then use the bankNationalID to indicate national clearing codes that are specific to a country. This should uniquely identify the bank within the country specified in the

Contact

.

The bank branch identification, if necessary, is specified as follows:

Value

bankBranchID

Description

The bank branch ID

The following table illustrates some valid role

- domain

value combinations for

Contact and

IdReference

:

Contact@role

payer payee originatingBank

IdReference@domain

bankAccountID ibanID bankAccountID ibanID abaRoutingNumber bankNationalID isoBicID swiftID bankBranchID (optional)

178 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentProposalRequest

receivingBank originatingCorrespo ndentBank receivingCorrespon dentBank intermediaryBank abaRoutingNumber bankNationalID isoBicID swiftID bankBranchID (optional) abaRoutingNumber isoBicID swiftID abaRoutingNumber isoBicID swiftID 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 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.

GrossAmount

The gross payment amount.

DiscountAmount

The discount amount.

cXML User’s Guide 179

PaymentRemittanceRequest Chapter 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 - AdjustAmount

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

180 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentRemittanceRequest

The following diagram shows the structure of the

PaymentRemittanceRequest

element:

The following example shows the structure of the

PaymentRemittanceRequest

element:

<PaymentRemittanceRequest>

<PaymentRemittanceRequestHeader>

header information

</PaymentRemittanceRequestHeader>

<PaymentRemittanceSummary>

summary-level remittance information

</PaymentRemittanceSummary>

<RemittanceDetail>

detail-level remittance information

</RemittanceDetail>

</PaymentRemittanceRequest>

PaymentRemittanceRequest has no attributes.

For an example of a

PaymentRemittanceRequest

for an invoice, see

“PaymentRemittanceRequest Example” on page 191.

cXML User’s Guide 181

PaymentRemittanceRequest Chapter 7 Payment

PaymentRemittanceRequestHeader

The

PaymentRemittanceRequestHeader

element defines header information that applies to the entire payment or remittance.

The following diagram shows the structure of the

PaymentRemittanceRequestHeader element:

ShortName

Description

PaymentMethod

PaymentRemittanceRequestHeader

PaymentPartner

PaymentReferenceInfo

Contact

IdReference

PCard

PaymentReference

DocumentReference

Comments

Extrinsic

PaymentRemittanceRequestHeader

has the following attributes:

paymentRemittan ceID paymentDate isPayment paymentReferenc eNumber

A unique identifier for this PaymentRemittance , generated by the buying organization’s system.

The date and time this Payment or Remittance transaction was created. paymentDate

should be earlier than the timestamp of the actual PaymentRemittanceRequest .

Indicates whether this request is intended for making payment or is for remittance advice only.

If the request is for payment purposes, set the attribute to “yes.”

Remittance advice information can be included in a

PaymentRemittanceRequest with isPayment = yes.

If isPayment

is not specified, the document is assumed to be for remittance advice only.

Indicates a payment transaction reference or payment identification number. For example, for check payments, the paymentReferenceNumber is the check number, and for electronic payments, it is an electronic reference or confirmation number.

PaymentMethod

Identifies the method for a payment. For more information, see

“PaymentMethod” on page 175.

182 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentRemittanceRequest

PaymentPartner

Identifies a party involved in the payment. For more information, see

“PaymentPartner” on page 176.

PaymentReferenceInfo

Defines the ID of an earlier payment made by a buying organization. This ID should uniquely identify the payment made in the buyer system.

PaymentReferenceInfo

has no attributes.

PaymentReference

Reference to an earlier

PaymentRemittanceRequest

. If the earlier payment was made through cXML, this element is required.

PaymentReference

has the following attributes:

paymentRemittan ceID paymentDate

The paymentRemittanceID

of the request.

Note: Do not use the transaction identification number, such as check number.

The payment date.

DocumentReference

The

DocumentReference element of a

PaymentReference is a container for the payloadID

attribute, which refers to a prior

PaymentRemittanceRequest

.

payloadID

A unique identifier for the prior PaymentRemittanceRequest .

The payloadID is copied directly from the cXML element of the

PaymentRemittanceRequest

.

PaymentIDInfo

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.

cXML User’s Guide 183

PaymentRemittanceRequest Chapter 7 Payment

PaymentIDInfo

has the following attributes:

paymentRemittan ceID paymentDate

The paymentRemittanceID

of the request.

Note: Do not use the transaction identification number, such as check number.

The payment date.

Comments

Header-level textual comments about the payment remittance, for the

PaymentRemittanceRequestHeader

.

Extrinsic

Additional information related to this payment. Information in the

Extrinsic

element of

PaymentRemittanceRequestHeader should not duplicate information in the

PaymentRemittanceRequest

.

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.

PaymentRemittanceSummary

has no attributes.

NetAmount

The

NetAmount element defines the total net payment amount.

NetAmount should satisfy the following equation:

NetAmount = GrossAmount - DiscountAmount - AdjustmentAmount

GrossAmount

The total gross amount.

DiscountAmount

The total discount amount.

184 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentRemittanceRequest

AdjustmentAmount

The total adjustment amount.

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.

RemittanceDetail

has one attribute:

lineNumber

The line number of the associated payable

PayableInfo

A reference to the payable document, such as an invoice, order, or master agreement.

For more information, see

“PayableInfo” on page 173.

PayableInvoiceInfo

A reference to the invoice being paid.

PayableInvoiceInfo

must contain either

InvoiceReference

or

InvoiceIDInfo

, and might contain either

PayableOrderInfo

or

PayableMasterAgreementInfo

.

InvoiceReference

Provides a clear reference to a prior

InvoiceDetailRequest

document. The

InvoiceReference

is copied from the

InvoiceDetailRequest

message.

cXML User’s Guide 185

PaymentRemittanceRequest Chapter 7 Payment

InvoiceIDInfo

Defines the ID of an invoice known to the supplier system.

InvoiceIDInfo

is a container for two attributes:

invoiceID invoiceDate

The ID of an invoice known to the supplier system

The invoice date

PayableOrderInfo

Provides supplementary information related to the order. For example, a payment against a consolidated invoice might include associated order information. Defines payable information related to an order that was paid.

PayableOrderInfo

has no attributes.

OrderReference

The reference to the order being paid.

OrderIDInfo

The order ID from the procurement application.

PayableMasterAgreementInfo

Provides supplementary information related to the master agreement (contract). For example, a payment against a consolidated invoice might include associated master agreement information. Defines payable information related to the master agreement being paid.

NetAmount

The detail-level net amount for this payable:

NetAmount

=

GrossAmount

-

DiscountAmount

-

AdjustmentAmount

GrossAmount

The detail-level gross payment amount for this payable.

DiscountAmount

Defines the detail-level discount information for this payable.

186 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment PaymentRemittanceStatusUpdateRequest

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

PaymentRemittanceStatus

element supports Extrinsic elements.

The following example shows the structure of the

PaymentRemittanceStatusUpdateRequest

element:

<Request>

<PaymentRemittanceStatusUpdateRequest>

<DocumentReference>

.....

</DocumentReference>

<PaymentRemittanceStatus>

....

<Extrinsic name="OriginalSupplierAccountNumber">4232334545</Extrinsic>

<Extrinsic name="CorrectedSupplierAccountNumber">004232334545</Extrinsic>

<Extrinsic name="OriginalSupplierBankAbaNumber">121000358</Extrinsic>

<Extrinsic name="CorrectedSupplierBankAbaNumber">221000358</Extrinsic>

</PaymentRemittanceStatusUpdateRequest>

....

</PaymentRemittanceStatus>

</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:

<DocumentReference payloadID="0c300508b7863dcclb_14999"/>

cXML User’s Guide 187

PaymentRemittanceStatusUpdateRequest Chapter 7 Payment

DocumentReference

contains no elements, but has the following attribute:

payloadID

A unique identifier for the document. Copied directly from the cXML element of the previous

PaymentRemittanceRequest

.

PaymentRemittanceStatus

Defines the status for a payment transaction specified by an existing

PaymentRemittanceRequest

.

PaymentRemittanceStatus

has the following attributes:

type paymentReferenc eNumber

The status type of the payment transaction.

Indicates a unique number for a payment. For a check payment, for example, the paymentReferenceNumber would be the check number.

Possible values of the type

attribute in

PaymentRemittanceStatus

are:

Value

paid failed canceled

Description

The payment transaction was completed successfully.

The payment transaction failed. Under certain conditions, a

PaymentRemittance

of type “ failed

” can be resubmitted by the buying organization.

The payment transaction was canceled.

For a discussion of the common

Status

element, see

“Status” on page 48.

PaymentRemittanceStatusDetail

Defines status details of the payment transaction specified by an existing

PaymentremittanceStatusDetail

.

PaymentRemittanceStatusDetail

contains a PCDATA string.

Typically, this element describes the specifics of a problem.

PaymentRemittanceStatusDetail

has the following attributes:

code description xml:lang

Payment transaction status code provided by the payment provider.

Textual description of the status code (not specific issue).

The language in which the text attribute and element content are written.

188 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment Example Payment Documents

Extrinsic

The Extrinsic element list can be used to insert additional data. 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.

Extrinsic has the following attribute:

name

The value used to indicate the type or nature of the data.

Example Payment Documents

The following examples illustrate payment documents:

•

PaymentProposalRequest Example

•

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>

cXML User’s Guide 189

Example Payment Documents

<UserAgent>Procurement Application 1.0</UserAgent>

</Sender>

</Header>

<Request>

<PaymentProposalRequest paymentProposalID="proposal123" operation="new" paymentDate="2005-07-20T23:59:20-07:00">

<PayableInfo>

<PayableInvoiceInfo>

<InvoiceReference invoiceID="ABC">

<DocumentReference payloadID="25510.10.81.231"/>

</InvoiceReference>

<PayableOrderInfo>

<OrderReference orderID="DEF">

<DocumentReference payloadID="25510.10.81.002"/>

</OrderReference>

</PayableOrderInfo>

</PayableInvoiceInfo>

</PayableInfo>

<PaymentMethod type="ach"/>

<Contact role="remitTo" addressID="Billing">

<Name xml:lang="en">Lisa Dollar</Name>

<PostalAddress name="billing department">

<DeliverTo>Lisa Dollar</DeliverTo>

<Street>100 Castro Street</Street>

<City>Mountain View</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>

<AreaOrCityCode>650</AreaOrCityCode>

<Number>9990000</Number>

</TelephoneNumber>

</Phone>

</Contact>

<GrossAmount>

<Money currency="USD">3000.00</Money>

</GrossAmount>

<DiscountAmount>

<Money currency="USD">160.00</Money>

</DiscountAmount>

<AdjustmentAmount>

<Money currency="USD">30.00</Money>

</AdjustmentAmount>

<NetAmount>

Chapter 7 Payment

190 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment Example Payment Documents

<Money currency="USD">2810.00</Money>

</NetAmount>

</PaymentProposalRequest>

</Request>

</cXML>

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>

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

cXML User’s Guide 191

Example Payment Documents Chapter 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>

</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>

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

</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>

192 cXML User’s Guide 1.2.021 November 2009

Chapter 7 Payment Example Payment Documents

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

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

</Credential>

cXML User’s Guide 193

Example Payment Documents Chapter 7 Payment

</To>

<Sender>

<Credential domain=”NetworkId”>

<Identity>Procurement Application 1.0</Identity>

</Credential>

</Sender>

</Header>

<Request deploymentMode="production">

<PaymentRemittanceStatusUpdateRequest>

<DocumentReference payloadID="[email protected]">

</DocumentReference>

<PaymentRemittanceStatus type="canceled" paymentReferenceNumber="PaymentRefNumber">1234</

</PaymentRemittanceStatus>

</PaymentRemittanceStatusUpdateRequest>

</Request>

</cXML>

194 cXML User’s Guide 1.2.021 November 2009

Chapter 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

.

The contractor—that is, the temporary laborer in question—enters timecard information in either the buyer or supplier system, depending upon the situation.

Therefore, either buyers or suppliers can send timecard documents, and timecard documents can flow in either direction. In this way, timecards differ from invoices, which are typically sent only by suppliers.

cXML User’s Guide 195

TimeCard Element Chapter 8 TimeCard Transaction

Supplier to Buyer Request

TimeCardRequest

describes a timecard document that is sent from a supplier, such as a staffing agency, to a buyer. The from

and sender

credentials are the supplier’s, and the to

credential is the buyer’s. When the timecard is approved, the buyer sends a

StatusUpdateRequest

with the

DocumentApprovalStatus

element indicating whether the timecard was approved or rejected.

Buyer to Supplier Request

TimeCardInfoRequest

describes a timecard document that is sent from a buyer to a supplier. The from

credential is the buyer’s, and to

credential is the supplier’s.

TimeCard Element

The

TimeCard

element is used to capture the hours worked by a contractor or other temporary laborer, and has the following structure:

196

The

TimeCard

element has the following attributes:.

type status timeCardID

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 default value is submitted

.

Represents the unique identifier for this timecard in the buyer and supplier systems. Required.

cXML User’s Guide 1.2.021 November 2009

Chapter 8 TimeCard Transaction TimeCard Element

OrderInfo

The

OrderInfo

element is used to reference the order. One timecard can reference only one order.

Contractor

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:

domain

The domain in which the ContractorIdentifier is represented. Possible values are supplierReferenceID or buyerReferenceID, indicating the system in which the

ContractorIdentifier originated.

Contact

The generic

Contact

element describes the contractor.

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.

cXML User’s Guide 197

TimeCard Element Chapter 8 TimeCard Transaction

TimeCardTimeInterval

The

TimeCardTimeInterval

element represents the time interval being reported on a timecard. It contains the following attributes:

duration payCode isNonBillable

The duration of time being claimed for the line item, represented in the ISO 8601 format

PnYn MnDTnH nMnS , where nY represents the number of years, nM the number of months, nD the number of days, T the date/time separator, nH

the number of hours, nM

the number of minutes and nS

the number of seconds. For example, to indicate a duration of 1 year, 2 months, 3 days, 10 hours, and 30 minutes, one would write:

P1Y2M3DT10H30M

.

In the event that duration

and

TimeRange

do not agree, duration takes precedence. For example, if duration is 2 hours, and TimeRange is from 4:00 p.m. to 8:00 p.m., then the 2 hour duration

takes precedence. However, if duration

is not present, then it is computed from the

TimeRange.

The pay code to be used. Recommended pay codes include:

Regular

Overtime

Doubletime

Mealbreak

Tripletime

WeeklyRestDay

HolidayWorked

RegularNightShift

OvertimeNightShift

DoubletimeNightShift

TripletNightShift

WeeklyRestDayNightShift

RegularMixedShift

OvertimeMixedShift

DoubletimeMixedShift

TripletimeMixedShift

WeeklyRestDayMixedShift

Implied attribute that designates whether or not the time is billable. The default behavior is billable.

198 cXML User’s Guide 1.2.021 November 2009

Chapter 8 TimeCard Transaction TimeCard Element

Expense

The

Expensel

element represents any expense a contractor reported on a timecard. It contains the following attributes

expenseDate expenseType isNonBillable

The date of the expense.

The type of expense. Recommended expense types include: mileage airfare fuel taxi perDiem hotel

Implied attribute that designates whether or not the expense is billable. The default behavior is billable.

ExpenseAmount

The

ExpenseAmount

element represents the monetary value and currency of an expense a contractor reported on a timecard.

The

ExpenseAmount

element contains the following attributes:

alternateCurrency alternateAmount

The currency of the expense.

The total monetary value of the expense.

TimeRange

The

TimeRange

element defines a time range in which the start and end dates can be unbounded.

The

TimeRange

element contains the following attributes:

startDate endDate

The first date in the billable period. Required.

The last date in the billable period. Optional, because the difference in time between the endDate

and startDate attributes need not agree with the duration

attribute in the TimeCardTimeInterval element.

cXML User’s Guide 199

TimeCard Element Chapter 8 TimeCard Transaction

SubmitterInfo

The

SubmitterInfo

element contains information about the person submitting the timecard.

The

SubmitterInfo

element contains the following attributes:

Contact

If the

Contact

element is absent, then it is assumed that the contractor is also the submitter.

submittedDate

The time when the timecard was submitted. Required.

ApprovalInfo

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.

The

ApprovalInfo

element has the following attributes:

approvedDate

The time when the timecard was approved. Required.

DocumentReference

DocumentReference

is used on an update operation to refer to a previous

TimeCardRequest

or

TimeCardInfoRequest.

200 cXML User’s Guide 1.2.021 November 2009

Chapter 8 TimeCard Transaction TimeCard Examples

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>

cXML User’s Guide 201

TimeCard Examples Chapter 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>

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

</Request>

</cXML>

This example show an update sent upon approval 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>

202 cXML User’s Guide 1.2.021 November 2009

Chapter 8 TimeCard Transaction TimeCard Examples

<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">

cXML User’s Guide 203

TimeCard Examples Chapter 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>

<DocumentReference payloadID="[email protected]"/>

</TimeCard>

</TimeCardInfoRequest>

</Request>

</cXML>

204 cXML User’s Guide 1.2.021 November 2009

Chapter 9

Master Agreements

cXML supports the transmission of Master Agreement documents, which are contracts between trading partners.

This chapter describes:

•

Overview of Master Agreements

•

MasterAgreementRequest

Overview of Master Agreements

Master Agreements enable buyers to establish a commitment for goods and services 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.

The Master Agreement transaction enables procurement application to facilitate the negotiation and creation of Master Agreements with suppliers and creation of Release

Orders from those Master Agreements. These Agreement documents can be routed from the procurement application to the supplier by a network hub. The execution of 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 maximum and minimum values of the agreement. It also lists maximum and minimum values and quantities for individual items.

cXML User’s Guide 205

MasterAgreementRequest Chapter 9 Master Agreements

The following example shows a MasterAgreementRequest document:

<MasterAgreementRequest>

<MasterAgreementRequestHeader agreementID="MA123" agreementDate="2001-12-01" type="value" effectiveDate="2002-01-01" expirationDate="2002-12-31" operation="new">

<MaxAmount>

<Money currency="USD">10000</Money>

</MaxAmount>

<MaxReleaseAmount>

<Money currency="USD">10000</Money>

</MaxReleaseAmount>

<Contact role="BuyerLocation">

<Name xml:lang="en">Buyer Company</Name>

<PostalAddress name="default">

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

</Contact>

<Comments xml:lang="en-US">well formed XML can go here.</Comments>

</MasterAgreementRequestHeader>

<AgreementItemOut maxQuantity="100">

<MaxAmount>

<Money currency="USD">1000</Money>

</MaxAmount>

<MaxReleaseAmount>

<Money currency="USD">100</Money>

</MaxReleaseAmount>

<ItemOut quantity="1">

<ItemID>

<SupplierPartID>1233244</SupplierPartID>

</ItemID>

<ItemDetail>

<UnitPrice>

<Money currency="USD">1.34</Money>

</UnitPrice>

<Description xml:lang="en">Blue Ballpoint Pen</Description>

<UnitOfMeasure>EA</UnitOfMeasure>

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

<ManufacturerPartID>234</ManufacturerPartID>

<ManufacturerName>foobar</ManufacturerName>

206 cXML User’s Guide 1.2.021 November 2009

Chapter 9 Master Agreements MasterAgreementRequest

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

</ItemOut>

</AgreementItemOut>

</MasterAgreementRequest>

MasterAgreementRequestHeader Element

The

MasterAgreementRequestHeader

contains information about the Master Agreement common to all contained items.

MasterAgreementHeader

has the following attributes:

agreementDate type effectiveDate expirationDate operation parentAgreementPa yloadID agreementID

The date and time the agreement request was created. This is different from the effective and expiration date of the agreement.

Specifies whether the agreement refers to a value or quantity.

Specifies the date the agreement is available for ordering or releases.

Specifies the date the agreement is no longer available

Specifies the type of the agreement request. Can be “new”,

“update” or “delete”. Defaults to "new". The "delete" operation is used to cancel an existing agreement. The delete request should be an exact replica of the original request.

PayloadID for the corresponding parent document from which this agreement is derived. Optional.

The procurement system agreementID for this request.

MasterAgreementHeader

can contain the following optional child elements:

MaxAmount

MinAmount

MaxReleaseAmount

(Optional) Contains the maximum amount for all line items in the

Master Agreement.

(Optional) Contains the committed amount for all line items on the Master Agreement.

(Optional) The contractual maximum amount per Release of this

Master Agreement.

cXML User’s Guide 207

MasterAgreementRequest Chapter 9 Master Agreements

MinReleaseAmount

Contact

Comments

Extrinsic

(Optional) The contractual minimum amount per Release of this

Master Agreement.

(Optional) Use "Contact" element to supply any additional

Address or Location information.

(Optional) Can contain additional information about the status of the overall Master Agreement.

(Optional) Can be used to insert additional data about the

MasterAgreement for application consumption.

AgreementItemOut Element

The

AgreementItemOut

element specifies the requirements of a particular line item that is part of the Master Agreement contract.

AgreementItemOut

has the following attributes:

maxQuantity minQuantity maxReleaseQuantity minReleaseQuantity

(Optional) Specifies the maximum quantity for this particular line Item.

(Optional) Specifies the minimum quantity for this particular line Item.

(Optional) Specifies the maximum quantity per release for this particular line Item.

(Optional) Specifies the minimum quantity per release for this particular line Item.

AgreementItemOut

can contain the following child elements:

MaxAmount

MinAmount

MaxReleaseAmount

MinReleaseAmount

ItemOut

(Optional) Contains the maximum amount for this particular line Item.

(Optional) Contains the minimum amount for this particular line Item.

(Optional) Indicates the item level maximum amount per release.

(Optional) Indicates the item level minimum amount per release.

A line item that is part of the master agreement. Required.

The lineNumber attribute in the ItemOut specifies the corresponding lineNumber on the Master Agreement in the

Procurement Application.

The quantity attribute in the ItemOut should be set to “one” and ignored at the Master Agreement implementation processing stage.

208 cXML User’s Guide 1.2.021 November 2009

Chapter 10

Later Status Changes

cXML allows entities to set the status of purchase orders and line items within them.

This chapter describes:

•

Overview of Status

•

StatusUpdateRequest

•

ConfirmationRequest

•

ShipNoticeRequest

Overview of Status

After the

OrderRequest

transaction has completed, suppliers and intermediate servers 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.

Like the response to an

OrderRequest

(see

“Response to an OrderRequest” on page

159), none of these transactions includes a specific

Response

element. Instead, the returned document contains a nearly empty

Response

(only a

Status

). Each returned 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>

The returned code is “200” only if the operation completed successfully.

cXML User’s Guide 209

StatusUpdateRequest Chapter 10 Later Status Changes

StatusUpdateRequest

This transaction informs an earlier node about changes in the processing status of an order or invoice.

One change is of particular significance: when an intermediate hub successfully transmits a document onward, it can inform the original sender or a previous hub about that success. Transitions through various queues and processing steps at a supplier or hub might also be significant to the buying organization.

Order-processing partners (such as fax or EDI service providers) send

StatusUpdateRequest

transaction messages to network commerce hubs to set purchase order status. It affects the order status indicator on the hub, which is visible to both buyers and suppliers. Additionally, suppliers can send this transaction to allow buying organizations to see the status of document processing within the supplier’s organization.

Buying organizations use

StatusUpdateRequest

to update the status of invoices on network commerce hubs, which can in turn forward them to suppliers.

The

StatusUpdateRequest

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>

210 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes StatusUpdateRequest

<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 a

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 forwarded the document. The recipient should expect no further

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

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 payloadID="0c300508b7863dcclb_14999"/>

DocumentReference

contains no elements, but has the following attribute:

payloadID

A unique number with respect to space and time that is used for logging purposes to identify documents. This value should not change in the case of retry attempts.

The recommended implementation is: datetime.process id.random number@hostname

Taken directly from the cXML

element of the

OrderRequest

or

InvoiceDetailRequest document.

cXML User’s Guide 211

StatusUpdateRequest Chapter 10 Later Status Changes

DocumentReference

is optional.

StatusUpdateRequest

documents for invoices can use

InvoiceIDInfo

elemenets within

InvoiceStatus

elements to identify the invoices.

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.

A

StatusUpdateRequest

document is sent to a supplier in response to a

ConfirmationRequest

with type=”RequestToPay”

to a network hub. This

ConfirmationRequest invokes a payment service where the network hub requests a payment service provider to perform a point of sale transaction against the PCard listed in the purchase order and return the status of the transaction. The network hub then sends the transaction status back to the supplier in a

StatusUpdateRequest

document. For example:

<StatusUpdateRequest>

<DocumentReference payloadID="0c300508b7863dcclb_14999"/>

<Status code="0" text="Approved">Approved</Status>

<PaymentStatus orderID="PC100" transactionTimestamp="2000-01-08T10:00:06-

08:00" type="Sale" transactionID="V20000212000" authorizationID="PN123">

<PCard number="1234567890123456" expiration="2003-03-31"/>

<Total>

<Money currency="USD">500.00</Money>

</Total>

<Shipping>

<Money currency="USD">20.00</Money>

<Description xml:lang="en">shipping charge</Description>

</Shipping>

<Tax>

<Money currency="USD">40.00</Money>

<Description xml:lang="en">CA Sales Tax</Description>

</Tax>

</PaymentStatus>

</StatusUpdateRequest>

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.

212 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes StatusUpdateRequest

PaymentStatus

has the following attributes

orderID transactionTimeStamp type

(required)

transactionID authorizationID

Identifies the referenced order. It is copied from the

ConfirmationRequest or the OrderRequest.

Specifies the time when the payment transaction was submitted.

Specifies the type of PCard transaction. The value must be one of the following:

Authorization

—Authorizes the PCard. No charge is made.

There is one authorization per order.

Settlement— Transfers the funds secured by a previous authorization transaction.

Sale—

Initiates a charge to the PCard.

Credit—

Initiates a credit against the original charge.

Compensates for an order that did not meet buyer expectations, to make adjustments to an account that was overcharged, or to credit an account for items returned by a buyer.

Assigned to the transaction by the payment processing gateway.

The authorization code for the transaction provided by the bank.

SourcingStatus Element

The

SourcingStatus

element provides update information for a RFQ sourcing transaction,

PunchOutSetupRequest

document with operation=”source”

.

<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”,

“cancel”, or “deny”. The body of the

SourcingStatus

element can contain humanreadable information about the new state of the RFQ.

cXML User’s Guide 213

StatusUpdateRequest Chapter 10 Later Status Changes

InvoiceStatus Element

When using

StatusUpdateRequest

for invoices, include the

InvoiceStatus

element.

<StatusUpdateRequest>

<Status code="201" text="OK">Approved</Status>

<InvoiceStatus type="reconciled">

<InvoiceIDInfo invoiceID="INV123" invoiceDate="2005-04-20T23:59:20-07:00"/>

</InvoiceStatus">

</StatusUpdateRequest>

InvoiceStatus

has the following attribute:

type

(required)

Refers to the action taken by the buying organization on the invoice. It can have the following values: processing— The invoice was received by the buying organization and is being processed.

reconciled

—The invoice successfully reconciled. The amounts in the invoice have not yet been paid.

rejected —The invoice failed reconciliation. The buying organization is rejecting the invoice. The Comments element should contain free text explaining why the invoice was rejected, and the actions the supplier should take. The supplier can then resubmit a corrected invoice (a new invoice document with a new invoice number).

paying

—The invoice has been approved for payment and is in the payment process. paid —The invoice amounts have been paid by the buying organization.

InvoiceIDInfo Element

Use the

InvoiceIDInfo

element if the

DocumentReference

element is omitted. It identifies a specific invoice document by invoice ID and date, not by payloadID

as required by

DocumentReference

.

InvoiceIDInfo

has the following attributes:

invoiceID

(required)

invoiceDate

A supplier-generated identifier for the Invoice. This value is the invoiceID attribute that was in the InvoiceDetailRequestHeader of the invoice.

Date and time the invoice was created.

214 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ConfirmationRequest

PartialAmount Element

The

PartialAmount

element allows buying organizations to specify different amounts paid than the amounts specified in invoices. If invoices are paid in full, do not include

PartialAmount

. The existence of

PartialAmount

alerts the supplier to read the Comments elements which should contain more explanations on the differences.

Extrinsic Element

The Extrinsic element allows inclusion of additional information about the status of a document being updated.

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

A

ConfirmationRequest

with type=”requestToPay”

invokes a payment service where the network hub requests a payment service provider to perform a point of sale transaction against the PCard listed in the purchase order and return the status of the transaction. The network hub then sends the transaction status back to the supplier in a

StatusUpdateRequest

document.

cXML User’s Guide 215

ConfirmationRequest Chapter 10 Later Status Changes

The following example shows a

ConfirmationRequest

element that is of type “ accept

”.

<ConfirmationRequest>

<!-- Without the confirmID, it remains possible to update this confirmation. An update would refer (in the OrderReference element) to the same

OrderRequest document, would describe the status of the same items, and would point to this document through its DocumentReference element. However, the 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>

<Money currency="USD">0.19</Money>

<Description xml:lang="en-CA">CA Sales Tax</Description>

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

216 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ConfirmationRequest

To perform a substitution, include a

ConfirmationItem

element to specify the item to be replaced, then provide an

ItemIn

element for the replacement. Only use

ItemIn

elements for substitutions. You should then wait for a corresponding change order from the buyer before shipping.

The

ConfirmationRequest

element is a request to add confirmation information to the data known about an order at the receiving server. It can contain three elements:

ConfirmationHeader

,

OrderReference

, and an optional

ConfirmationItem

. If the Confirmation

Request type specified in the

ConfirmationHeader

is either “ detail

” or “ except

”, you can include

ConfirmationItem

elements to update specific line items from a purchase order.

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.

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 231) and two attributes:

orderID

and orderDate

.

orderID Attribute

Specifies the buyer system orderID

for the confirmation, that is, the PO number. When used, it must be copied directly from the referenced

OrderRequest OrderRequestHeader 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.

cXML User’s Guide 217

ConfirmationRequest Chapter 10 Later Status Changes

ConfirmationHeader Element

The

ConfirmationHeader

element contains information that is common to all items contained in the

ConfirmationRequest

. It has the following attributes:

• type

• noticeDate

• invoiceID

• operation

• ConfirmID

• incoTerms

The

ConfirmationHeader

element can contain the following elements:

• DocumentReference

• Tax

• Shipping

• Total

• Contact

•

Hazard

• Comments

•

Extrinsic

If the

ConfirmationHeader

(see page page 220) is either,

“allDetail”

, “ detail

” or “ except

”, you can include

ConfirmationItem

elements to update specific line items from a purchase order.

The following example shows a

ConfirmationRequest

of type “ except

”:

<ConfirmationRequest>

<!-- Without the confirmID, it remains possible to update the original confirmation.

This update refers (in the OrderReference element) to the same OrderRequest document, describes the status of the same items and refers to the original confirmation document in the DocumentReference element. However, the confirmID makes the update much more explicit.

Note: The noticeDate changes to match the time of the update and not the original confirmation time.-->

<ConfirmationHeader type="except" noticeDate="2000-10-13T18:39:09-08:00" confirmID="C999-234" operation="update" invoiceID="I1102-10-13">

<DocumentReference payloadID="[email protected]" />

<Total>

<Money currency="USD">190.60</Money>

</Total>

<Shipping>

218 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ConfirmationRequest

<Money currency="USD">2.5</Money>

<Description xml:lang="en-CA">FedEx 2-day</Description>

</Shipping>

<Tax>

<Money currency="USD">0.19</Money>

<Description xml:lang="en-CA">CA Sales Tax</Description>

</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, 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.

</Comments>

</ConfirmationStatus>

</ConfirmationItem>

</ConfirmationRequest>

cXML User’s Guide 219

ConfirmationRequest Chapter 10 Later Status Changes

type Attribute

This required attribute specifies the type of confirmation. accept allDetail detail backordered except reject

Accepts the entire order as described in the referenced purchase order.

A document of this type can contain

ConfirmationItem

elements. They must contain only

ConfirmationStatus

elements of type="accept"

.

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 tools, which commonly send buyers a snapshot of an order in 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.

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

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.

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

Rejects the entire purchase order. Specify a reason for the rejection in the Comments element. This document must not contain

ConfirmationItem elements.

220 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ConfirmationRequest

requestToPay replace

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.

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

The invoiceID

attribute is an optional supplier-generated identifier for an invoice associated with the items described in this confirmation. It is identical to the Invoice

Number that appears at the top of a physical invoice.

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"

.

When the confirmID

does not appear in an operation="new"

ConfirmationRequest, it must not appear in a corresponding operation="update"

document. The

DocumentReference element contained in the update's

ConfirmationHeader

and the payloadID

attribute of the original or previous update link the two documents.

cXML User’s Guide 221

ConfirmationRequest Chapter 10 Later Status Changes

operation Attribute

This optional attribute specifies whether the confirmation is new, or an update to a previous confirmation.

new update

Default value. No previous confirmation request has been sent.

Updates a previous confirmation request. The confirmID must match a previous request's confirmID

.

An

"update"

confirmation allows a supplier to correct an error in a confirmation or to add additional information learned later. In either case, an

"update"

document must be complete: all data from the original confirmation or a previous update should be discarded by the recipient.

The requirement that the confirmation be complete enables ConfirmationRequest information to expand. There are no restrictions on new items not yet referenced in an

“update”

ConfirmationRequest. New items must not have already been mentioned in another ConfirmationRequest unless all of the items from the other confirmation are now described in the consolidated document. This protocol does not support splitting confirmations (sending an

"update"

ConfirmationRequest document describing a 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).

An

"update"

ConfirmationRequest must contain the same confirmID,

if any, as the previous version of the confirmation. This attribute is an unambiguous and a direct connection between all versions of the confirmation.

An

"update"

ConfirmationRequest must also include a

DocumentReference

element in the

ConfirmationHeader

. See “DocumentReference Element” on page 223

for more information on this element. This element sequences multiple versions of a

confirmation and is the only link between those versions. See “confirmID Attribute” on page 221 for more of the implications of leaving out the attribute. Other

confirmations discarded through consolidations as previously described are not explicitly referenced by the new, larger ConfirmationRequest document.

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.

222 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ConfirmationRequest

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: deq des exw fas fca fob cfr cif cip cpt daf ddp ddu

Cost and freight

Cost, insurance, and freight

Carriage and insurance paid to

Carriage paid to

Delivered at frontier

Delivered duty paid

Delivered duty unpaid

Delivered ex quay (duty paid)

Delivered ex ship

Ex works

Free alongside ship

Free carrier

Free on board vessel

DocumentReference Element

The

DocumentReference

element should appear only when operation

is

“update”

(see

page 222). 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 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 222).

Tax and Shipping Elements

Tax

and

Shipping

amounts can be updated and included in the confirmation with new values without any corresponding line item information.

cXML User’s Guide 223

ConfirmationRequest Chapter 10 Later Status Changes

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.

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.

Contact role values include: technicalSupport customerService sales shipFrom shipTo payTo billTo supplierCorporate

Technical support

Customer service

Sales

Starting point for shipments related to this order

Copies the

ShipTo

element from the OrderRequest document

Where payment for this order should be sent

Copies the BillTo element from the OrderRequest document

Supplier at corporate

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 should apply to the entire order or all items mentioned in the confirmation. A

ConfirmationRequest that updates the status of a single line item should not include

Hazard

elements in the

ConfirmationItem

element. See

“Hazard Element” on page 240 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.

224 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ConfirmationRequest

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.

ConfirmationItem

has the following attributes:

quantity lineNumber

Specifies how many items were ordered. Expressed in units given in the UnitOfMeasure element. Matches the quantity value for the line item's

ItemOut

element in the corresponding

OrderReference

element.

Required.

Position, counting from 1, of the item in an order. Matches the corresponding line item,

ItemOut

, in the document referenced by the

OrderReference element. Required.

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.

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.

cXML User’s Guide 225

ConfirmationRequest Chapter 10 Later Status Changes

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

element.

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

UnitOfMeasure

in the

ItemDetail

contained within the

ItemIn

element.

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.

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

element, a price change if there is a

UnitPrice

element, or a delayed shipment if there is a deliveryDate

attribute. The

"allDetail"

type requires reconciliation software to determine what has changed since the original order.

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.

226 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ConfirmationRequest

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.

type Attribute

Specifies the status of this portion of the order. accept allDetail detail reject requestToPay

Accept this portion as described in the referenced ItemOut element.

Accept this portion of the line item as detailed in the contents of this

ConfirmationStatus element. These contents completely describe what will be shipped. Unlike the "detail" type, this confirmation type includes all information known by the supplier, whether or not it differs from the data provided in the original OrderRequest document.

This type is provided for compatibility with current EDI and order entry tools, which commonly send the buyer a snapshot of an order in the supplier's systems. Due to the reconciliation issues caused by confirmations of this type, it is recommended that you use this type as a "bridge" strategy suitable only for the short term.

Allowed only in documents whose ConfirmationHeader type is

"allDetail".

Accept this portion with the changes detailed in the

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 this portion of the line item.

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.

This type is allowed in documents with overall request

(ConfirmationHeader) type "requestToPay".

cXML User’s Guide 227

ShipNoticeRequest Chapter 10 Later Status Changes

unknown backordered

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

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 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"

.

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

.

ShipNoticeRequest

can contain the following elements:

•

ShipNoticeHeader

•

ShipControl

•

ShipNoticePortion

228 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ShipNoticeRequest

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.

ConfirmationRequest

and

ShipNoticeRequest

documents with operation

=" update

" must include all relevant information from the original

OrderRequest

document.

The following example shows a

ShipNoticeRequest

element:

<ShipNoticeRequest>

<ShipNoticeHeader shipmentID="S2-123" noticeDate="2000-10-14T18:39:09-08:00" shipmentDate="2000-10-14T08:30:19-08:00" deliveryDate="2000-10-18T09:00:00-08:00">

<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">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>

<ShipNoticePortion>

<!-- The orderID and orderDate attributes are not required in the OrderReference element. -->

<OrderReference orderID="DO1234">

<DocumentReference payloadID="[email protected]" />

</OrderReference>

</ShipNoticePortion>

</ShipNoticeRequest>

cXML User’s Guide 229

ShipNoticeRequest Chapter 10 Later Status Changes

The

ShipNoticeRequest

element contains information about a ship notice common to all contained items. It is not necessary to copy this information from the

OrderRequest document. The

Contact

element should be used primarily to add new information about an order.

The

ShipNoticeRequest

element contains three elements:

ShipNoticeHeader

,

ShipControl

, and

ShipNoticePortion

. All are required, and both

ShipNoticePortion

and

ShipControl

can occur more than once.

Shipments with multiple responsible carriers are described in one of two ways:

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.

2.

Each segment requires a separate tracking number. Suppliers send such information with one

ShipControl

element per segment.

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.

ShipNoticePortion

elements can appear in any order. A particular order, with

ShipNoticePortion

,

OrderReference

, or

DocumentReference payloadID

attribute value, must not appear more than once in a

ShipNoticeRequest

element.

Note:

Many elements and attributes in the

ShipNoticeRequest

and

ShipNoticeHeader

elements are optional only for the operation="delete"

case. For other operations, one or more

ShipControl

and

ShipNoticePortion

elements must appear in a

ShipNoticeHeader

element.

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.

230 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ShipNoticeRequest

ServiceLevel Element

One or more

ServiceLevel

elements must appear in all

ShipNoticeRequest

documents, except when operation="delete"

is specified. Each

ServiceLevel

must contain a single string corresponding to the level of service, such as

"overnight"

, provided by the carrier for this shipment. When multiple

ServiceLevel

elements appear, all must describe the same level of service in different languages or locales. No two

ServiceLevel

elements can have the same xml:lang

attribute. Elements in such a list can appear in any order.

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.

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

ShipNoticeHeader

element, should apply to the entire shipment, or to all items contained 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 and routes. All such data must be intended for human use.

cXML User’s Guide 231

ShipNoticeRequest Chapter 10 Later Status 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 attribute value, must not appear more than once within a

ShipNoticeHeader

element. A 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

A supplier-specified optional identifier for the document. The attribute is user-visible and secondary to the document's

PayloadID

. It is required.

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

This optional attribute specifies whether the

ShipNoticeRequest

document is new or an update to a previous ship notice.

new update delete

Default value. No previous ship notice has been sent.

Updates a previous ship notice request. Allows a supplier to correct an error in a ship notice or to add additional information learned later. In either case, an "update" document must be complete: all data from the original should be discarded by the recipient. The shipmentID

must match a previous request's shipmentID

.

Removes the changes described in the previous new or updated

ShipNoticeRequest from the state of the shipment. Only use when the supplier discards a planned shipment or incorrectly sends a

ShipNoticeRequest about an order that will not take place. The shipmentID

must match a previous request's shipmentID.

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 231 for more information on this element.

This effectively sequences multiple versions of a ship notice.

232 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ShipNoticeRequest

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"

.

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 92).

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.

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.

cXML User’s Guide 233

ShipNoticeRequest Chapter 10 Later Status Changes

Route Element

If present,

Route

elements must be in the order the shipment will travel.

Contact Element

The most common

Contact

roles in this element are

: carrierCorporate shipFrom

Details the contact information the supplier has about the carrier organization.

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 estimated time.

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.

234 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ShipNoticeRequest

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"

.

Each carrier within a segment controlled by a third-party logistics provider provides tracking information to that provider externally. The ShipNoticeRequest includes tracking information at the

ShipControl

level only.

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

Identifies the transportation type code.

air motor rail ship

Transportation by flight

Transportation by land motor craft, common carrier

Transportation by rail

Transportation by boat; ocean

Because shipments can travel through multiple segments with different methods, this attribute has no default.

cXML User’s Guide 235

ShipNoticeRequest Chapter 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

Specifies the date and time this shipment ended this part of the trip. Must come after startDate

. If any

Route

elements follow, the startDate

of that element must not precede this value.

CarrierIdentifier Element

Identifies the carrier that will transport this shipment. There is one attribute, called domain

.

domain Attribute

Specifies the domain in which

CarrierIdentifier

value has meaning. For example,

“SCAC” for Standard Carrier Alpha Code, or the legal company name.

Recognized domains include the following:

company name

SCAC

IATA

AAR

UIC

EAN

DUNS

The legal name for this company. In some cases, this can also be 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.

Standard Carrier Alpha Code.

www.nmfta.org

International Air Transport Association.

www.iata.org

Association of American Railroads.

www.aar.org

International Union of Railways.

www.uic.asso.fr

European Article Numbering.

www.ean-ucc.org

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.

236 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ShipNoticeRequest

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

.

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

A particular

OrderRequest

specified in the

OrderReference

element must be mentioned in at most one

ShipNoticePortion

element. While multiple shipments can be sent for one order, a ship notice must mention each order only once.

If a

ShipNoticePortion

element contains no

ShipNoticeItem

elements, the entire referenced order is included in the shipment. This simplifying option prevents inclusion of hazard and packaging information.

cXML User’s Guide 237

ShipNoticeRequest Chapter 10 Later Status Changes

Contact Element

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

.

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 common to all contained items or make it clear which

ShipNoticeItem

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 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 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 four elements:

UnitOfMeasure

(for more information, see “UnitOfMeasure” on page

58),

Packaging

,

Hazard

, and

AssetInfo

.

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.

238 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ShipNoticeRequest

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 239). 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.

Dimension Element

Specifies a single dimension for the packaging of the item.

•

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: length width height weight volume

The length of the packaging.

The width of the packaging.

The height of the packaging.

The weight of the packaging.

The volume of the packaging

cXML User’s Guide 239

ShipNoticeRequest Chapter 10 Later Status Changes

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 are two elements:

Description

, and

Classification

.

Classification

is optional and can occur more than once.

The

Description

element list, if provided, should include detailed handling requirements. Elements in this list can appear in any order. A description locale specified by the xml:lang

attribute must not appear more than once. When more than one

Description

element is present, each must contain translations of a common description.

Classification

elements can appear in any order. A

Classification domain

attribute must not 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.

The following

Classification domain

values are expected in this context:

UNDG

IMDG

NAHG

United Nations Dangerous Goods

International Marine Organization Dangerous Goods

North American Hazardous Goods

240 cXML User’s Guide 1.2.021 November 2009

Chapter 10 Later Status Changes ShipNoticeRequest

AssetInfo Element

The

AssetInfo

element provides asset tag numbers or serial numbers for individual items in a shipment of goods. The buyer might want to know this information before receiving the shipment. This element can include the following attributes:

•

tagNumber

attribute

Specifies a buyer-specific asset tag number identfier for the item. In order for the supplier to assign asset tag numbers on behalf of the buyer, the buyer and supplier must agree in advance which asset tag numbers the supplier should use and how they should be assigned.

•

serialNumber

attribute

Specifies the serial number of the item.

•

location attribute

Specifies the location of the item.

Even though all attributes for

AssetInfo

are optional, the element should not be used unless at least one attribute is specified. If more than one attribute is specified, they should all refer to the properties of the same item.

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 yyyymm-dd per international ISO standard 8601.

cXML User’s Guide 241

ShipNoticeRequest Chapter 10 Later Status Changes

242 cXML User’s Guide 1.2.021 November 2009

Chapter 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, line-item credit memos, debit memos, and receipts.

This chapter describes:

•

Overview of Invoices

•

InvoiceDetailRequest

•

Response

•

Invoice Status Update

•

Example 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, line-item credit memos, debit memos, and receipts.

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.

cXML User’s Guide 243

Overview of Invoices Chapter 11 Invoices

The cXML

InvoiceDetailRequest

document represents an invoice. After a receiving system accepts an invoice document, it responds with a generic cXML

Response

.

After buying organizations begin processing invoices, they send

StatusUpdateRequest documents to notify the commerce network hub about their reconciliation progress.

The commerce network hub can forward these documents to suppliers.

Early InvoiceRequest Document

Previously, cXML support for invoicing was provided by the

InvoiceRequest

document, which contained less detail than

InvoiceDetailRequest

and did not support line item or summary invoices.

InvoiceRequest

is deprecated in cXML 1.2.011. All cXML invoice projects should implement

InvoiceDetailRequest

.

Debit and Credit Amounts

In invoices, positive amounts are debits the buying organization owes the supplier; negative amounts are credits issued by the supplier to the buying organization. For example, the supplier can specify a

SubtotalAmount

of -50 USD to issue a credit of fifty

US dollars to the buying organization. Debit can be used in both standard invoices and debit memos. Credit can be used in standard invoices, credit memos, and lineitem credit memos.

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 215.)

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.

The shipping information in invoices is not meant to be a substitute for sending

ShipNoticeRequest

documents.

244 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Overview of Invoices

Types of Invoices

InvoiceDetailRequest

has the features and flexibility to support most business scenarios.

Individual and Summary Invoices

cXML supports both individual and summary invoices:

Invoice Category

Individual Invoice

Summary Invoice

Description

Applies against a single purchase order.

Applies against multiple purchase orders.

Invoice Level

cXML supports both header and detailed invoices:

Invoice Level

Header Invoice

Detailed Invoice

Description

Applies against the entirety of one or more purchase orders, without describing their line items.

Specify isHeaderInvoice="yes" and use

InvoiceDetailHeaderOrder elements, which do not contain lineitem information.

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

cXML User’s Guide 245

Overview of Invoices Chapter 11 Invoices

Invoice Purpose

Use the

InvoiceDetailRequestHeader

attributes to specify the purpose of the invoice.

Invoice Purpose

Standard Invoice

Credit Memo

Line-Item Credit

Memo

Debit Memo

Information Only

Cancel Invoice

Description

Request for payment after providing products or services.

Specify purpose="standard" and operation="new".

Specifies credit to a buying organization.

Specify purpose="creditMemo" and operation="new". Must be a header invoice. Amounts must be negative.

Specifies credit to a buying organization.

Specify purpose="lineLevelCreditMemo" and operation="new".

Must not be a header invoice. Amounts must be negative.

Specifies debit to a buying organization.

Specify purpose="debitMemo" and operation="new". Must be a header invoice. Amounts must be positive.

Provides a record of charges, similar to a receipt. No action is expected.

Specify isInformationOnly="yes" and operation="new".

Cancels a previously sent invoice.

Specify operation="delete".

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

246 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

InvoiceDetailRequest

InvoiceDetailRequest

documents represent invoices.

The structure of the

InvoiceDetailRequest

document is:

<Request>

<InvoiceDetailRequest>

<

InvoiceDetailRequestHeader >

header information

</InvoiceDetailRequestHeader>

<

InvoiceDetailHeaderOrder

>

order-level invoice information

</InvoiceDetailHeaderOrder>

. . .

or

<

InvoiceDetailOrder

>

detailed line-item information

</InvoiceDetailOrder>

. . .

<

InvoiceDetailSummary >

invoice summary

</InvoiceDetailSummary>

</InvoiceDetailRequest>

</Request>

InvoiceDetailOrder

elements are for detailed (line-item level) invoices and

InvoiceDetailHeaderOrder

elements are for header invoices. Invoices must not contain both types of elements. Both types of elements contain invoice lines.

All invoice line level amounts must add up to the total specified in

InvoiceDetailSummary

.

cXML User’s Guide 247

InvoiceDetailRequest Chapter 11 Invoices

InvoiceDetailRequestHeader

Defines header information that applies to the entire invoice.

InvoiceDetailHeader

has the following attributes:

invoiceID isInformationOnly purpose operation invoiceDate invoiceOrigin

A supplier-generated identifier for the Invoice. Identical to the

Invoice Number that appears at the top of a physical Invoice.

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

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.

creditMemo — A credit memo for issuing credit to the buying organization. isHeaderInvoice must be yes. Also, the element

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.

lineLevelCreditMemo — A line-item credit memo for issuing credit to the buying organization. isHeaderInvoice must be no.

Also, the element InvoiceDetailSummary/DueAmount must be a negative amount.

How this document is acting on the invoice: new — (default) Creates a new invoice.

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 cXML timestamp).

Indicates the originator of the invoice for categorization: supplier — Invoice originated by supplier.

buyer — Invoice originated by buying organization.

Not specified — Invoice origin is unknown.

248 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

InvoiceDetailHeaderIndicator

Defines indicators that describe overall attributes of the invoice. By default, all indicators are false.

InvoiceDetailHeaderIndicator

has the following attributes:

isHeaderInvoice isVatRecoverable

Category of the invoice: yes — Header invoice. Invoice uses

InvoiceDetailHeaderOrder, which contains header level invoice information without item details

Not specified — Detail invoice. Invoice uses

InvoiceDetailOrder, which contains item details.

yes — The entire invoice is VAT (Value Added Tax)recoverable.

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.

InvoiceDetailLineIndicator

has the following attributes:

isTaxInLine isSpecialHandlingInLine isShippingInLine isDiscountInLine isAccountingInLine

yes — Tax (Tax) is provided at invoice line level. If header tax is specified, it will be ignored.

yes — Special handling

(InvoiceDetailLineSpecialHandling) is provided at invoice line level.

yes — Shipping (InvoiceDetailLineShipping) is provided at invoice line level.

yes — Discount (InvoiceDetailDiscount) is provided at invoice line level.

yes — Accounting distribution (Distribution) is provided at invoice line level. If isHeaderInvoice is true, this indicator must nor be specified, because Distribution is available only at item level.

cXML User’s Guide 249

InvoiceDetailRequest Chapter 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.

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 from

, issuerOfInvoice

, soldTo

, billTo

, remitTo

.

Note that from

and issuerOfInvoice

must be synonymous.

IdReference

Defines an ID reference. The identifier/domain pair should be unique within each trading partner relationship (a buying organization and a supplier).

IdReference

has the following attributes:

identifier domain

The unique identifier of the IdReference within the domain.

The domain of the IdReference. One of the following values: accountID federalTaxID provincialTaxID taxExemptionIS bankRoutingID stateTaxID vatID accountPayableID accountReceivableID gstID

Values can be application-specific, such as 1099ID or courtRegisterID.

supplierTaxID has been deprecated and is treated as federalTaxID.

Creator

The creator of the

IdReference

(for example, the name of the bank, shipper, or other organization).

Description

Textual description of the

IdReference f or human readability.

250 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

DocumentReference

Identifies an earlier

InvoiceDetailRequest

document. If operation="delete"

,

DocumentReference

is required and it must reference the original

InvoiceDetailRequest document (with operation="new"

). In all other situations,

DocumentReference

is optional.

DocumentReference

has the following attribute:

payloadID

The payloadID attribute of another cXML document.

InvoiceDetailShipping

The shipping details of the invoice.

InvoiceDetailShipping

has the following attribute:

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.

Contact has the following attributes:

role addressID

The role name of the contact. Allowed roles are shipFrom

, shipTo

, and carrierCorporate

.

Unique identifier for the contact’s address.

Name

Name of the contact

PostalAddress

Postal address of the contact

cXML User’s Guide 251

InvoiceDetailRequest Chapter 11 Invoices

Email

Email address of the contact

Email

has the following attributes:

preferredLang

The language in which the recipient prefers to receive emails.

This attribute is optional. See “xmlLangCode” on page 58 for

more information.

Phone

Telephone number of the contact

Fax

Fax number of the contact

URL

Web address of the contact

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.

CarrierIdenifier

has the following attribute:

domain

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/

StandardCarrierAlphaCode/tabid/59/Default.aspx

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 - D&B’s Data Universal Numbering System. www.dnb.com

252 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

ShipmentIdentifier

The tracking number of this shipment.

DocumentReference

Identifies an earlier

ShipNoticeRequest

.

For more information, see

“DocumentReference” on page 251.

InvoiceDetailPaymentTerm (deprecated)

InvoicedetailPaymentTerm

is deprecated in cXML 1.2.011, in favor of

PaymentTerm

.

PaymentTerm

Defines a payment term in an invoice or order.

PaymentTerm

defines either the net term

(without discount) or the discount term (with discount).

PaymentTerm

has the following attributs:

payInNumberOfDays

The number of days after invoice date to pay in full.

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

Do not use the

Discount

element if the

PaymentTerm

is a net term.

Period

The period over which the services were rendered.

Period

has the following attributes:

startDate endDate

The starting date of the service.

The ending date of the service.

cXML User’s Guide 253

InvoiceDetailRequest Chapter 11 Invoices

InvoiceDetailOrder

Defines the invoice information of an order with item details, used only when isHeaderInvoice

is false (not specified).

An invoice line is an

InvoiceDetailItem

or an

InvoiceDetailServiceItem

and its invoice line number is specified by the invoiceLineNumber

attribute.

InvoiceDetailOrderInfo

Defines information related to the corresponding purchase order, including order reference and related master agreement reference, if any. Applications use this information to match the invoice with the corresponding purchase order or master agreement. The more definitive the reference, the more likely applications can successfully perform document matching.

InvoiceDetailOrderInfo

can contain several possible elements for refering to documents.

OrderReference

is strongly recommended, but if that information is not available, use

MasterAgreementReference

,

MasterAgreementIDInfo

,

OrderIDInfo

, or

SupplierOrderInfo

, in that order.

OrderReference

The reference to the purchase order being invoiced.

MasterAgreementReference

Defines a reference to an earlier

MasterAgreementRequest

document. This element identifies the master agreement of the release order to be invoiced.

MasterAgreementReference

has the following attributes:

agreementID agreementDate

The ID number of a master agreement known to the buying organization’s system.

The date and time the master agreement request was created.

254 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

MasterAgreementIDInfo

Defines the buying organization’s ID number of the corresponding master agreement if the order being invoiced is a release. This element identifies the master agreement of the contract or release order to be invoiced.

MasterAgreementIDInfo

has the following attributes:

agreementID agreementDate

The ID number of a master agreement known to the buying organization’s system.

The date and time the master agreement request was created.

OrderIDInfo

Identifies a purchase order known to the buying organization.

OrderIDInfo

has the following attributes:

orderID orderDate

The ID of a purchase order (purchase order number) known to the buying organization.

The date and time the purchase order was created.

SupplierOrderInfo

Defines supplier sales order information related to a purchase order.

SupplierOrderInfo

has the following attribute:

orderID

Supplier sales order ID of the purchase order.

cXML User’s Guide 255

InvoiceDetailRequest Chapter 11 Invoices

InvoiceDetailItem

Defines an invoice line item.

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.

InvoiceDetailItem

has the following attributes:

invoiceLineNumber quantity referenceDate inspectionDate

Supplier defined ID for the current invoice line. Should be unique across all invoice lines within an invoice.

The quantity being invoiced for the line item.

The reference date for the blanket order or contract item. The usage of this attribute is optional in most cases, and must be defined by the trading partners involved in the transaction.

Procurement software might use this date in reconciling an invoice against a blanket order or contract.

The date when the transfer of goods or the delivery of services occurs according to legal tax definitions. The usage of this attribute is optional in most cases, and must be defined by the trading partners involved in the transaction.

UnitOfMeasure

The line item’s unit of measure. For more information, see

“UnitOfMeasure” on page

58.

UnitPrice

The unit price.

InvoiceDetailItemReference

Defines all references related to an invoice line item.

InvoiceDetailItemReference

has the following attributes:

lineNumber serialNumber

(deprecated)

The purchase order line number of current line item, copied from the OrderRequest.

The product serial number for the current line item.

This attribute was deprecated in cXML 1.2.009. Use

SerialNumber

elements, instead.

256 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

ItemID

The supplier part number of current line item, from the

OrderRequest

.

Description

The line item description, from the

OrderRequest

.

SerialNumber

A serial number that uniquely identifies an accountable item that is being invoiced.

You can include multiple

SerialNumber

elements; the number of

SerialNumber elements should match the invoice item quantity.

Use

SerialNumber

elements instead of the

InvoiceDetailItemReference serialNumber attribute, which was deprecated in cXML 1.2.009.

ManufacturerPartID

The manufacturer part number.

ManufacturerName

The name of the manufacturer.

Country

The country of origin of the product listed in the line item.

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

The amount owed for tax.

cXML User’s Guide 257

InvoiceDetailRequest Chapter 11 Invoices

Description

Textual description of the tax.

TaxDetail

Detailed information about the tax.

TaxDetail

has the following attributes:

purpose category percentageRate isVatRecoverable taxPointDate paymentDate isTriangularTransactio n exemptDetail

The purpose of the tax. For example, "tax" or

"custom duty".

The category of the tax. For example, "sales",

"usage", "vat", or "gst".

The tax rate percentage. Do not include a percent symbol (%).

Set to "true" if the tax amount is recoverable.

The date on which VAT becomes due

The date on which payment must be made

(used only for transactions in France).

Set to “true” to indicate that the transaction occurred between three parties in three different countries, but the movement of goods did not follow the invoicing route. Add a

Contract element with role=”subsequentBuyer” to identify the subsequent buying organization in triangular transactions.

When the tax rate is zero percentage, regulations may require that suppliers specify if the tax is required, or if the goods or services are exempt from taxations.

This attribute can have the following values:

- zeroRated: This indicates the goods and services are taxable, but the tax rate is zero percent.

- exempt: This indicates the goods and services are tax exempt.

TaxableAmount

The amount that is taxable.

TaxAmount

The amount of tax.

258 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

TaxLocation

The locale in which the tax applies.

Description

Textual description of the tax.

TriangularTransactionLawReference

Reference to the relevant EU law covering the VAT for triangular transactions. For example, “

VAT - EC Article 28 Simplification Invoice

”.

Extrinsic

Additional information related to TaxDetail. This information should not duplicate any information in TaxDetail.

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

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

The

GrossAmount

minus discounts for the line item.

Distribution

Accounting information generated by the buying organization, such as cost center or general ledger category. This information should be copied from the

OrderRequest

.

Ignored if isAccountingInLine

is false (not specified).

cXML User’s Guide 259

InvoiceDetailRequest Chapter 11 Invoices

Comments

Textual comments for the line item.

Extrinsic

Additional information related to the line item. Should not duplicate anything in

InvoiceDetailItem

or

InvoiceDetailOrder

.

260 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

InvoiceDetailServiceItem

Specifies a service being invoiced.

InvoiceDetailServiceItem

has the following attributes:

invoiceLineNumber quantity referenceDate inspectionDate

Supplier defined ID for the current invoice line. Should be unique across all invoice lines within an invoice.

The quantity being invoiced for the line item. For service items, quantity represents the number of units of service rendered.

For example, 2 hours of service, where UnitOfMeasure is

"HUR"

The reference date for the service item. This can indicate the date at which the service line item is being invoiced.

The date when the transfer of goods or the delivery of services occurs according to legal tax definitions. The usage of this attribute is optional in most cases, and must be defined by the trading partners involved in the transaction.

InvoiceDetailServiceItemReference

InvoiceDetailServiceItemReference

has the following attribute:

lineNumber

The line number of current line item on the master agreement.

This value is required if the item being invoiced is part of a detailed master agreement that specifies detailed pricing terms at the line item or commodity level. It is optional if the item being invoiced is part of a master supplier agreement or blanket purchase order which do not contain detailed line item pricing information.

Classification

Commodity classification of the service.

ItemID

The Supplier’s part number for the service

Description

Description of the service.

SubtotalAmount

The subtotal amount of the service item. If unit price and invoiced quantity are specified, then subtotal should be the product of them.

cXML User’s Guide 261

InvoiceDetailRequest Chapter 11 Invoices

Period

The period during which the service was rendered.

For more information, see

“Period” on page 253.

UnitRate

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

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

For more information, see

“Tax” on page 257

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

The

GrossAmount

minus discounts for the line item.

262 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

Distribution

Accounting information generated by the buying organization, such as cost center or general ledger category. This information should be copied from the

OrderRequest

.

Ignored if isAccountingInLine

is false (not specified).

Comments

Textual comments for the line item.

InvoiceLaborDetail

Contains information about an item related to temporary labor. l

Contractor

The contractor whose work is being invoiced.

JobDescription

A text description of the job being performed.

Supervisor

Specifies contact information for the person who supervises the contractor.

WorkLocation

The address of the place where the work is performed.

InvoiceTimeCardDetail

Invoice details about a temporary labor service. The pay code for this invoice line item is in the

UnitRate

of the containing

InvoiceDetailServiceItem

.

TimeCardReference

Provides a clear reference to a prior

TimeCard

cXML document.

TimeCardReference has the following attribute:

timeCardID

Unique ID for the timecard as sent on the TimeCard document during TimeCardInfoRequest or

TimeCardRequest

. For more information, see Chapter 8,

“TimeCard Transaction.”

cXML User’s Guide 263

InvoiceDetailRequest Chapter 11 Invoices

TimeCardIDInfo

Defines the unique ID of the timecard known to the buyer and supplier systems.

TimeCardIDInfo

has the following attribute:

timeCardID

Unique ID for the timecard as sent on the

TimeCard document during

TimeCardInfoRequest

or

TimeCardRequest

. For more information, see Chapter 8,

“TimeCard Transaction.”

Extrinsic

Additional information related to this line item. Do not duplicate information in

InvoiceDetailItem

or

InvoiceDetailOrder

.

Use

Extrinsic

elements to specify line item related attributes such as service location, overtime/regular, and union/non- union.

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:

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

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

264 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

InvoiceDetailOrderInfo

Defines information related to the corresponding purchase order.

For more information, see

“InvoiceDetailOrderInfo” on page 254

InvoiceDetailOrderSummary

Defines header level summary info of an order in an invoice line.

InvoiceDetailOrderSummary

has the following attribute:

invoiceLineNumber inspectionDate

Supplier defined ID for the current invoice line. It should be unique across all invoice lines of the same

InvoiceDetailRequest.

The date when the transfer of goods or the delivery of services occurs according to legal tax definitions. The usage of this attribute is optional in most cases, and must be defined by the trading partners involved in the transaction.

SubtotalAmount

The invoice subtotal of the this order.

Period

The period over which the services were rendered.

For more information, see

“Period” on page 253.

Tax

The tax for this order. Ignored if isTaxInLine

is false (not specified).

For more information, see

“Tax” on page 257.

InvoiceDetailLineSpecialHandling

The special handling information for this order. Ignored if isSpecialHandlingInLine

is false (not specified).

InvoiceDetailLineShipping

The shipping information for this invoice line. Ignored if isShippingInLine

is false (not specified).

cXML User’s Guide 265

InvoiceDetailRequest Chapter 11 Invoices

InvoiceDetailShipping

The shipping details. For more information, see

“InvoiceDetailShipping” on page 251.

Money

The shipping amount.

GrossAmount

The

SubtotalAmount

plus taxes, shipping, and special handling charges.

InvoiceDetailDiscount

The discount or penalty for this invoice line. Ignored if isDiscountInLine

is false (not specified).

InvoiceDetailDiscount

has the following attribute:

percentageRate

Discount or penalty rate percentage. Positive rates denote discounts and negative rates denote penalties. Do not include a percentage sign (%) or divide by 100; for example “2” means

2%.

NetAmount

The

GrossAmount

minus discount amount.

Comments

Textual comments for the line item.

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

Sum of line item quantities multiplied by unit price.

266 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices InvoiceDetailRequest

Tax

Total tax information.

For more information, see

“Tax” on page 257.

SpecialHandlingAmount

Total special handling charge. You can optionally add a

Description

element to explain the charge.

ShippingAmount

Total shipping charge.

GrossAmount

Sum of subtotal, taxes, special handling charges, and shipping charges, before discounts.

InvoiceDetailDiscount

The total discount or penalty applied in the invoice.

For more information, see

“InvoiceDetailDiscount” on page 266.

NetAmount

Total

GrossAmount

minus discounts.

DepositAmount

Total deposit or prepayment amount.

DueAmount

Total amount due and payable:

NetAmount

minus

DepositAmount

. If purpose="creditMemo"

, this amount must be negative. If purpose="debitMemo"

, this amount must be positive.

cXML User’s Guide 267

Response Chapter 11 Invoices

Response

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]">

<Response>

<Status code="201" text="Accepted">Acknowledged</Status>

</Response>

</cXML>

For a list of possible status codes, see “Status” on page 48.

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.

Buying organizations update the status of invoices by sending

StatusUpdateRequest documents to commerce network hubs, which can forward them to suppliers.

StatusUpdateRequest

documents for invoices contain

InvoiceStatus

elements. Invoice status can be processing, reconciled

, rejected

, paying

, or paid

, which refers to the action taken by the buying organization on the invoice: processing reconciled rejected paying

The invoice was received by the buying organization and is being processed.

The invoice reconciled. The amounts in the invoice have not yet been paid.

The invoice failed to reconcile. The buying organization is rejecting the invoice. The

Comments

element should contain free text explaining why the invoice was rejected, and the actions the supplier should take. The supplier can resubmit a corrected invoice

(a new invoice document with a new invoice number).

The invoice is in the payment process or has been partially paid.

268 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Invoice Status Update

paid

The invoice amounts have been paid by the buying organization.

The

PartialAmount

element enables buying organizations to specify different amounts paid than the amounts specified in invoices.

PartialAmount

should not appear for invoices that are paid in full. The existence of

PartialAmount

alerts the supplier to read the

Comments

elements, which should explain the differences.

The

DocumentReference

within the

StatusUpdateRequest

must refer to the

InvoiceDetailRequest

document. The

Status

element should have status code 200.

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

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

<cXML timestamp="2001-09-05T16:34:28-07:00" payloadID="999732868377--

[email protected]">

<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>Procurement Application V1.0</UserAgent>

</Sender>

</Header>

<Request>

<StatusUpdateRequest>

<DocumentReference payloadID="Inv123"></DocumentReference>

<Status code="200" text=""></Status>

<InvoiceStatus type="paid">

<PartialAmount>

<Money currency="USD">10.99</Money>

</PartialAmount>

<Comments>This charge is paid, minus $2.00 due to missing items.</Comments>

</InvoiceStatus>

</StatusUpdateRequest>

</Request>

</cXML>

For more information about the StatusUpdate transaction, see “StatusUpdateRequest” on page 210.

cXML User’s Guide 269

Example Invoices Chapter 11 Invoices

Example Invoices

The following examples illustrate several types of invoices.

•

Standard Header Invoice

•

Standard Detail Invoice

•

Service Invoice

•

Marketplace Invoice

Standard Header Invoice

This example shows a header invoice against a single purchase order.

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE cXML SYSTEM "http:// xml.cXML.org/schemas/cXML/1.2.020/InvoiceDetail.dtd">

<cXML timestamp="2009-03-10T16:23:01-07:00" payloadID="Mar102009_0447pm">

<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>Supplier’s Super Invoice Generator</UserAgent>

</Sender>

</Header>

<Request>

<InvoiceDetailRequest>

<InvoiceDetailRequestHeader invoiceDate="2009-03-09T00:00:00-07:00" invoiceID="Mar102009_0447pm" purpose="standard" operation="new" invoiceOrigin="supplier">

<InvoiceDetailHeaderIndicator isHeaderInvoice="yes" />

<InvoiceDetailLineIndicator isTaxInLine="yes" isShippingInLine="yes" isSpecialHandlingInLine="yes" isDiscountInLine="yes" />

<InvoicePartner>

<Contact role="billTo">

<Name xml:lang="en-US">Buyer Headquarters</Name>

270 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Example Invoices

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

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

<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">

<Street>15 Oak Road</Street>

<City>Bigtown</City>

<State>CA</State>

cXML User’s Guide 271

Example Invoices

272

Chapter 11 Invoices

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

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

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

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

cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Example Invoices

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

</Request>

</cXML>

Standard Detail Invoice

This example shows a detail invoice for two line items in a single purchase order. It contains payment terms that define discounts for early payment and penalties for late 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>

</Header>

From, To, and Sender credentials

<Request>

<InvoiceDetailRequest>

<InvoiceDetailRequestHeader invoiceID="Oct102001_1204pm" purpose="standard" operation="new"

cXML User’s Guide 273

Example Invoices

274

Chapter 11 Invoices

invoiceDate="2001-04-20T23:59:20-07:00">

<InvoiceDetailHeaderIndicator/>

<InvoiceDetailLineIndicator isTaxInLine="yes” isShippingInLine="yes" isAccountingInLine="yes"/>

<InvoicePartner>

Sell To contact information

</InvoicePartner>

<InvoicePartner>

Remit To contact information

</InvoicePartner>

<PaymentTerm payInNumberOfDays="10">

<Discount>10</Discount>

</PaymentTerm>

<PaymentTerm payInNumberOfDays="20">

<Discount>5</Discount>

</PaymentTerm>

<PaymentTerm payInNumberOfDays="30">

<Discount>0</Discount>

</PaymentTerm>

<PaymentTerm payInNumberOfDays="40">

<Discount>-5</Discount>

</PaymentTerm>

<PaymentTerm payInNumberOfDays="50">

<Discount>-9</Discount>

</PaymentTerm>

</InvoiceDetailRequestHeader>

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

cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Example Invoices

</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>

</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">

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

<Accounting name="Buyer assigned accounting code 16">

<AccountingSegment id="ABC000000001">

<Name xml:lang="en">Trade</Name>

cXML User’s Guide 275

Example Invoices

276

Chapter 11 Invoices

<Description xml:lang="en">Misc (Expensed)</Description>

</AccountingSegment>

</Accounting>

<Charge>

<Money currency="USD">18.94</Money>

</Charge>

</Distribution>

</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">

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">

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

cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Example Invoices

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

<TaxAmount>

<Money currency="USD">0.41</Money>

</TaxAmount>

<TaxLocation xml:lang="en">US</TaxLocation>

</TaxDetail>

</Tax>

<ShippingAmount>

<Money currency="USD">3.00</Money>

</ShippingAmount>

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

</InvoiceDetailRequest>

</Request>

</cXML>

cXML User’s Guide 277

Example Invoices Chapter 11 Invoices

Service Invoice

The following invoice is for both regular items and service items.

<?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>

</Header>

From, To, and Sender credentials

<Request deploymentMode="test">

<InvoiceDetailRequest>

<InvoiceDetailRequestHeader invoiceID="123456" purpose="standard" operation="new" invoiceDate="2001-04-20T23:59:20-07:00">

<InvoiceDetailHeaderIndicator/>

<InvoiceDetailLineIndicator isTaxInLine="yes" isShippingInLine="yes" isAccountingInLine="yes"/>

<InvoicePartner>

<Contact role="soldTo" addressID="B2.4.319">

<Name xml:lang="en">Mike Smith</Name>

Postal address, email address, phone, and fax information

</Contact>

</InvoicePartner>

<InvoicePartner>

<Contact role="remitTo" addressID="Billing">

<Name xml:lang="en">Lisa King</Name>

Postal address, email address, phone, and fax information

</Contact>

<IdReference identifier="00000-11111" domain="accountReceivableID">

<Creator xml:lang="en">Supplier ERP</Creator>

</IdReference>

<IdReference identifier="123456789" domain="bankRoutingID">

<Creator xml:lang="en">Supplier Bank</Creator>

</IdReference>

</InvoicePartner>

<lPaymentTerm payInNumberOfDays="10">

<Discount>10</Discount>

</PaymentTerm>

<PaymentTerm payInNumberOfDays="20">

<Discount>5</Discount>

</PaymentTerm>

<PaymentTerm payInNumberOfDays="30">

<Discount>0</Discount>

</PaymentTerm>

278 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Example Invoices

<PaymentTerm payInNumberOfDays="40">

<Discount>-5</Discount>

</PaymentTerm>

</InvoiceDetailRequestHeader>

<InvoiceDetailOrder>

<InvoiceDetailOrderInfo>

<MasterAgreementIDInfo agreementID="MA-1234"/>

</InvoiceDetailOrderInfo>

<InvoiceDetailItem invoiceLineNumber="1" quantity="100">

<UnitOfMeasure>EA</UnitOfMeasure>

<UnitPrice>

<Money currency="USD">57.13</Money>

</UnitPrice>

<InvoiceDetailItemReference lineNumber="2">

<ItemID>

<SupplierPartID>TOW08134</SupplierPartID>

</ItemID>

<Description xml:lang="en">Roll Towel Series 2000</Description>

</InvoiceDetailItemReference>

<SubtotalAmount>

<Money currency="USD">5713</Money>

</SubtotalAmount>

<Tax>

<Money currency="USD">287</Money>

<Description xml:lang="en">total item tax</Description>

<TaxDetail purpose="tax" 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>

</TaxDetail>

</Tax>

<GrossAmount>

<Money currency="USD">6000</Money>

</GrossAmount>

<NetAmount>

<Money currency="USD">6000</Money>

</NetAmount>

</InvoiceDetailItem>

<InvoiceDetailServiceItem invoiceLineNumber="2" quantity="100">

<InvoiceDetailServiceItemReference lineNumber="1">

<Classification domain="UNSPC">76111501</Classification>

<Description xml:lang="en">

Window cleaning services at $30/hour

cXML User’s Guide 279

Example Invoices

280

Chapter 11 Invoices

</Description>

</InvoiceDetailServiceItemReference>

<SubtotalAmount>

<Money currency="USD">3000.00</Money>

</SubtotalAmount>

<Period startDate="2001-02-01T12:00:00-00:00" 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>

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

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

cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Example Invoices

<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”>

</InvoiceTimeCardDetail>

</InvoiceLaborDetail>

</InvoiceDetailServiceItem>

</InvoiceDetailOrder>

<InvoiceDetailOrder>

<InvoiceDetailOrderInfo>

<MasterAgreementIDInfo agreementID="MA-1235"/>

</InvoiceDetailOrderInfo>

<!--- milestone invoicing -->

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

</InvoiceDetailServiceItem>

</InvoiceDetailOrder>

cXML User’s Guide 281

Example Invoices

<InvoiceDetailSummary>

<SubtotalAmount>

<Money currency="USD">13713</Money>

</SubtotalAmount>

<Tax>

<Money currency="USD">287</Money>

<Description xml:lang="en">total tax</Description>

<TaxDetail purpose="tax" 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>

</TaxDetail>

<TaxDetail purpose="tax" category="Federal sales tax" percentageRate="2">

<TaxableAmount>

<Money currency="USD">5713</Money>

</TaxableAmount>

<TaxAmount>

<Money currency="USD">87</Money>

</TaxAmount>

</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>

Chapter 11 Invoices

282 cXML User’s Guide 1.2.021 November 2009

Chapter 11 Invoices Example Invoices

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>

</Header>

<Request>

<InvoiceDetailRequest>

cXML User’s Guide 283

Example Invoices Chapter 11 Invoices

284 cXML User’s Guide 1.2.021 November 2009

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

This chapter describes:

•

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 description, part numbers, and classification codes.

The catalog

Contract

element was deprecated in cXML 1.2.008.

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.

cXML User’s Guide 285

Catalog Definitions Chapter 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

domain value

+

*

SupplierLocation

OrderTarget

Phone|Email|Fax|URL

?

OrderProtocol

OrderMethods

+ ?

OrderMethod Contact

code

Address

Supplier

has the following attributes:

URL for supplier's website.

corporateURL

(optional)

storeFrontURL

(optional)

URL for website for shopping or browsing.

286 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Catalog Definitions

The following example shows an outline of the

Supplier

element:

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

…

</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>

<Phone name="Office">

…

</Phone>

</Contact>

</OrderMethods>

</SupplierLocation>

</Supplier>

SupplierLocation

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

.

cXML User’s Guide 287

Catalog Definitions Chapter 12 Catalogs

OrderMethods and OrderMethod

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.

OrderMethod

encapsulates ordering information in the form of an order target (such as phone, fax, or URL) and an optional protocol to further clarify the ordering expectations at the given target; for example, “cxml” for a URL target.

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>

...

288 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Catalog Definitions

</ItemID>

</IndexItemDelete>

</IndexItem>

<IndexItem>

<IndexItemPunchout>

<ItemID>

...

</ItemID>

<PunchOutDetail>

<SearchGroupData>

...

</SearchGroupData>

...

</PunchOutDetail>

</IndexItemPunchout>

</IndexItem>

</Index>

Index

has the following attribute:

loadmode

(optional)

The mode in which the target application should load the Index:

"Full"

Completely replaces a previously loaded index.

"Incremental" Imports the index on top of the existing index, replacing or deleting existing items and adding new items. The recommended application default is incremental.

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:

•

IndexItemAdd

—Inserts a new item or updates an existing item in the index. It contains an

ItemID

element, an

ItemDetail

element, and an

IndexItemDetail

element.

•

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.

cXML User’s Guide 289

Catalog Definitions Chapter 12 Catalogs

ItemID

The

ItemID

element uniquely identifies a supplier’s items. It contains a

SupplierPartID element and an optional

SupplierPartAuxiliaryID

element.

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

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

112.

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.

In the context of an

IndexItemAdd

,

Extrinsic

elements extend information about a particular item. These extensions should not be transmitted to a supplier within an

OrderRequest

, because the supplier can retrieve the same data using the unique

ItemID

.

IndexItemDetail

The

IndexItemDetail

element contains index-specific elements that define additional aspects of an item, such as

LeadTime

,

ExpirationDate

,

EffectiveDate

,

SearchGroupData

, or

TerritoryAvailable

.

290 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Type Definitions

PunchoutDetail

PunchoutDetail

is similar to

ItemDetail

, except it requires only one or more

Description elements and a

Classification

. It can also contain

UnitPrice

,

UnitOfMeasure

,

URL

,

ManufacturerName

,

ManufacturerPartID

,

ExpirationDate

,

EffectiveDate

,

SearchGroupData

,

TerritoryAvailable

,

LeadTime

, and

Extrinsic

elements. Price values are approximate; users can punch out to the supplier’s website to obtain the current pricing information.

PunchoutDetail

has the following attribute:

punchoutLevel

(optional)

Specifies how the procurement application should present the

PunchOut item to users. This attribute can have the value store , aisle , shelf

, or product

.

Procurement applications might display these items differently, depending on how they are tagged by suppliers. For example, they might display store-level items differently than product-level items.

Use punchoutLevel="aisle"

for top level product categories; for example, Computer

Accessories or Electrical Component Supplies. Use punchoutLevel="shelf"

for similar products from which a user would choose while shopping; for example, if multiple manufacturers make the same product or a single product is available in multiple configurations. Use punchoutLevel="product"

for specific items that appear by themselves on PunchOut site pages.

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

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.

cXML User’s Guide 291

Type Definitions Chapter 12 Catalogs

TypeProvider

TypeProvider

specifies the provider of the types being defined, identified by a name and one or more IDs (for example, NetworkId or DUNS).

TypeProvider

has the following attribute:

name

(required)

The canonical name used to reference the type provider when fully qualifying the name of a type (for example, in a

SearchGroupData

element reference).

Name

The

Name

element is for localized display purposes, allowing different names to be provided per locale.

OrganizationID

Unique identifier for the type provider organization.

Type

A

TypeDefinition

document contains a

TypeProvider

element and either

Type

or

PrimitiveType

elements.

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 objectoriented inheritance models: child

TypeAttributes

cannot override parent

TypeAttributes

.

It is illegal to define a

TypeAttribute

of the same name as a parent

TypeAttribute

.

Type has the following attributes:

name

(required)

extends

(optional)

Canonical name of the type.

Name of the type that is being extended.

292 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Type Definitions

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.

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.

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.

name

(required)

type

(required)

shortTag mappedFrom isRequired

Specifies the canonical name of this attribute.

Specifies the data type of this attribute. Can be one of:

"integer"

"string"

A whole number, with no fraction.

A group of characters with words that can be individually indexed for free text searching.

"literal"

"double"

A group of characters with words that cannot be individually indexed for free text searching.

A floating point number.

"date"

"boolean"

A date of the form yyyy-mm-dd; for example,

2002-01-25

A Boolean value; yes, no, 1, 0, true, false, t, or f.

Alias for this attribute.

Specifies the name of another object in the system that implicitly defines this attribute.

Indicates whether this attribute requires a (non-empty) value.

cXML User’s Guide 293

Type Definitions Chapter 12 Catalogs isRequiredForOrdering isRefinable isSearchable isCollection isCaseSensitive isInKey isInFreeTextSearch isHidden isSortable isReadOnly unit

Indicates that the value for an attribute must be provided

(usually by the requisitioner) before the item can be included in an order for the supplier. Typically used for ad-hoc or partially specified catalog items.

Indicates whether this attribute is refinable in search queries.

Indicates whether this attribute is searchable in search queries.

Indicates whether this attribute allows repeating values.

Indicates whether this attribute preserves letter case. This property applies only to attributes of type string or literal. It has no effect on numeric, boolean, or date attributes, nor does it apply to attributes of complex type.

Indicates whether this attribute is part of the unique key for the type.

Indicates whether this attribute should be indexed to be a candidate in a free-text (All) query.

Indicates whether this attribute is displayed to users.

Indicates whether this attribute can be sorted.

Indicates whether values assigned to this attribute are frozen and cannot be changed by the receiving application.

Specifies the unit of this attribute, if applicable. For example, if the TypeAttribute is of a PrimitiveType with a scalar type of

"integer"

, this unit might be

"IN"

to indicate inches.

Name

Localized name of the

TypeAttribute

.

Description

Localized description of the

TypeAttribute

.

EnumerationValue

EnumerationValue

allows you to optionally specify a set of one or more valid data values for the

TypeAttribute

.

294 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Type Definitions

Range

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

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" isRefinable="yes">

<Name xml:lang="en">Weight</Name>

<Range>

<RangeBegin>12</RangeBegin>

<RangeEnd inclusive="no">100</RangeEnd>

</Range>

</TypeAttribute>

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.

PrimitiveType

has the following optional attributes:

min max

The minimum length for a

The maximum length for a

TypeAttribute

TypeAttribute

of scalarType

of scalarType

"string"

"string"

or

or

"literal"

"literal"

maxPrecision

The maximum precision for a

TypeAttribute

of scalarType

“double”

.

.

.

maxScale

The maximum scale for a TypeAttribute of scalarType "double" .

cXML User’s Guide 295

Subscription Management Definitions Chapter 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.

This section discusses:

•

Supplier Data

•

Supplier Profile Information

•

Catalog Subscriptions

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">

296 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Subscription Management Definitions

<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

SupplierDataRequest

requests data about a supplier.

<Request>

<SupplierDataRequest>

<SupplierID domain="DUNS">123456789</SupplierID>

</SupplierDataRequest>

</Request>

SupplierDataResponse

SupplierDataResponse

contains data about a supplier.

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

<Email>[email protected]</Email>

<Phone name="Office">

<TelephoneNumber>

cXML User’s Guide 297

Subscription Management Definitions Chapter 12 Catalogs

<CountryCode isoCountryCode="US">1</CountryCode>

<AreaOrCityCode>800</AreaOrCityCode>

<Number>5551212</Number>

</TelephoneNumber>

</Phone>

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

</Address>

<OrderMethods>

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

SupplierChangeMessage

This element is for notification of changes to supplier data.

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>

298 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Subscription Management Definitions

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

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

</Address>

<OrderMethods>

<OrderMethod>

<OrderTarget>

<URL>http://www.workchairs.com/cxmlorder</URL>

</OrderTarget>

<OrderProtocol>cXML</OrderProtocol>

</OrderMethod>

</OrderMethods>

</SupplierLocation>

</Supplier>

</SupplierChangeMessage>

</Message>

cXML User’s Guide 299

Subscription Management Definitions Chapter 12 Catalogs

Supplier Profile Information

Supplier profile management uses three types of transactions:

•

OrganizationDataRequest – Requests profile information for suppliers with which the buyer has relationships.

•

OrganizationDataResponse – Returns supplier profile information.

•

OrganizationChangeMessage – Returns profile information for suppliers whose profile has changed.

OrganizationDataRequest

OrganizationDataRequest

requests profile information for suppliers with whom the buyer has established trading relationships.

<Request>

<OrganizationDataRequest>

<OrganizationID>

<Credential domain="NetworkID">

<Identity>AN01022222222222</Identity>

</Credential>

<Credential domain="DUNS">

<Identity>123456789</Identity>

</Credential>

</OrganizationID>

</OrganizationDataRequest>

</Request>

</cXML>

OrganizationDataResponse

OrganizationDataResponse

returns profile information for suppliers with whom the buyer has established trading relationships.

<Response>

<Status code="200" text="OK"/>

<OrganizationDataResponse>

<Organization>

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

<Credential domain="NetworkID">

<Identity>AN01022222222222</Identity>

</Credential>

<Credential domain="DUNS">

<Identity>123456789</Identity>

</Credential>

<OrganizationRole name="supplier"/>

300 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Subscription Management Definitions

<Address>

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

<PostalAddress>

<Street>123 Front Street</Street>

<City>Toosunny</City>

<State>CA</State>

<PostalCode>95000</PostalCode>

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

</PostalAddress>

<Email>[email protected]</Email>

<Phone>

<TelephoneNumber>

<CountryCode isoCountryCode="US">1</CountryCode>

<AreaOrCityCode>800</AreaOrCityCode>

<Number>555-1212</Number>

</TelephoneNumber>

</Phone>

<Fax>

<TelephoneNumber>

<CountryCode isoCountryCode="US">1</CountryCode>

<AreaOrCityCode>408</AreaOrCityCode>

<Number>555-1234</Number>

</TelephoneNumber>

</Fax>

<URL>http://www.workchairs.com/Support.htm</URL>

</Address>

<Person>

<Contact>

<Name xml:lang = "en-US">Joe Hannyman</Name>

<PostalAddress>

<Street>321 The Main Street</Street>

<City>Sunnyvale</City>

<State>CA</State>

<PostalCode>90488</PostalCode>

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

</PostalAddress>

<Email>[email protected]</Email>

</Contact>

<PersonRole name="buyerAccount"/>

<PersonRole name="supplierMasterAccount"/>

</Person>

</Organization>

<Extrinsic name="OrderRoutingMethod">email</Extrinsic>

</OrganizationDataResponse>

</Response>

cXML User’s Guide 301

Subscription Management Definitions Chapter 12 Catalogs

OrganizationChangeMessage

OrganizationChangeMessage

returns updated profile information for suppliers with whom the buyer has established trading relationships.

<Message>

<OrganizationChangeMessage type="update">

<Organization>

<Name xml:lang="en-US">BOISE CASCADE OFFICE PRODUCTS

CORPORATION</Name>

<Credential domain="NetworkID">

<Identity>AN01000000125</Identity>

</Credential>

<Credential domain="DUNS">

<Identity>178923231</Identity>

</Credential>

<OrganizationRole name="supplier"/>

<Address>

<Name xml:lang="en-US">BOISE CASCADE OFFICE PRODUCTS

CORPORATION</Name>

<PostalAddress>

<Street>800 W BRYN MAWR AVEEDI profile</Street>

<City>ITASCA</City>

<State>IL</State>

<PostalCode>60143</PostalCode>

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

</PostalAddress>

<Email>[email protected]</Email>

<Phone name="">

<TelephoneNumber>

<CountryCode isoCountryCode="US">1</CountryCode>

<AreaOrCityCode></AreaOrCityCode>

<Number>555-555-5555</Number>

</TelephoneNumber>

</Phone>

<Fax name="">

<TelephoneNumber>

<CountryCode isoCountryCode="US">1</CountryCode>

<AreaOrCityCode></AreaOrCityCode>

<Number>666-666-6666</Number>

</TelephoneNumber>

</Fax>

<URL name="website1">http://main.url.com</URL>

</Address>

</Organization>

</OrganizationChangeMessage>

302 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Subscription Management Definitions

Catalog Subscriptions

Catalog subscription management uses four types of transactions:

•

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.

•

SubscriptionStatusUpdateRequest – Returns the catalog subscription status from the buyer.

Subscription

All catalog subscription transactions use the

Subscription

element to describe 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>

<Format version="2.1">CIF</Format>

<Description xml:lang="en-US">The best prices for software</Description>

</Subscription>

The elements within

Subscription

include:

InternalID

A unique ID internal to the intermediary. Contains an optional domain

attribute.

Name

The name of the subscription.

ChangeTime

The date and time when any aspect of the subscription last changed.

SupplierID

Format

Description

The ID of the supplier.

The format of the catalog.

A description of the catalog.

cXML User’s Guide 303

Subscription Management Definitions Chapter 12 Catalogs

SubscriptionListRequest

This element requests the buyer’s current list of catalog subscriptions.

<Request>

<SubscriptionListRequest/>

</Request>

SubscriptionListResponse

This element lists the buyer’s current list of catalog subscriptions.

<Response>

<Status code="200" text="OK"/>

<SubscriptionListResponse>

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

<Description xml:lang="en-US">The best prices for software</Description>

</Subscription>

<Subscription>

<InternalID>1235</InternalID>

<Name xml:lang="en-US">Q2 Hardware Prices</Name>

<Changetime>1999-03-12T18:15:00-08:00</Changetime>

<SupplierID domain="DUNS">555555555</SupplierID>

<Format version="2.1">CIF</Format>

<Description xml:lang="en-US">The best prices for hardware

</Description>

</Subscription>

</SubscriptionListResponse>

</Response>

SubscriptionContentRequest

This element requests the contents of a subscribed catalog. The request includes the

InternalID

and

SupplierID

for the catalog.

<Request>

<SubscriptionContentRequest>

<InternalID>1234</InternalID>

<SupplierID domain="DUNS">123456789</SupplierID>

</SubscriptionContentRequest>

</Request>

304 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Subscription Management Definitions

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>

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

ABCDBBDBDBDBDB

. . .

</CIFContent>

</SubscriptionContent>

</SubscriptionContentResponse>

</Response>

SubscriptionChangeMessage

This element signals to the buyer'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>

cXML User’s Guide 305

Subscription Management Definitions Chapter 12 Catalogs

</Message>

The type

attribute describes the type of change: new

, delete

, or update

.

SubscriptionStatusUpdateRequest

This element requests the subscription status of a catalog. It enables buying organizations to send the catalog subscription status to suppliers through Ariba SN.

On a buying organization’s system, a catalog can have various status updates from the time it is downloaded until it is activated. Each catalog status on the buying organization's system can be sent to the supplier using this element. Ariba SN receives and updates the subscription status of the catalog using the

InternalID

.

A

SubscriptionStatusUpdateRequest

includes the

InternalID

of the catalog, and the

SubscriptionVersion

and

SubscriptionStatus

elements.

<Request >

<SubscriptionStatusUpdateRequest>

<InternalID>1234</InternalID>

<SubscriptionVersion versionNumber="2"//>>

<SubscriptionStatus status="activated" />

</SubscriptionStatusUpdateRequest>

</Request>

SubscriptionVersion

This element stores the version number of the catalog.

When a supplier edits a catalog, Ariba SN creates a new version of the catalog and assigns a version number. This version number is used with the

InternalID

in all messages sent from the buyer to Ariba SN. This is an optional attribute. When it is not defined, Ariba SN uses the last published version of the catalog as the

InternalID

.

SubscriptionStatus

This element stores the status of the catalog. Catalog status values are: approved, rejected, validation error, deleted, received, validated, activated, deactivated, and changed.

306 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Catalog Upload Transaction

Catalog Upload Transaction

The cXML Catalog Upload transaction enables suppliers to programmatically upload and publish catalogs on network commerce hubs.

The Catalog Upload transaction gives you an alternative to logging on to network hubs to interactively upload and publish catalogs. You can use it to automatically distribute updated catalogs whenever you change pricing or availability of your products or services.

The Catalog Upload transaction supports both CIF and cXML catalogs.

The Catalog Upload transaction consists of two cXML documents:

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.

Response

Sent by the network commerce hub to acknowledge the receipt of a

CatalogUploadRequest

.

CatalogUploadRequest

MIME header

The following example shows a

CatalogUploadRequest

:

ID of network hub

--kdflkajfdksadjfklasdjfkljdfdsfdkf

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">

<Identity>AN01000000001</Identity>

</Credential>

</To>

<Sender>

<Credential domain="DUNS">

<Identity>123456789</Identity>

cXML User’s Guide 307

Catalog Upload Transaction Chapter 12 Catalogs

ID of MIME attachment

MIME attachment header

MIME trailer

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

<Attachment>

<URL>cid:[email protected]</URL>

</Attachment>

<Commodities>

<CommodityCode>52</CommodityCode>

</Commodities>

<AutoPublish enabled="true"/>

<Notification>

<Email>[email protected]</Email>

<URLPost enabled="true"/>

</Notification>

</CatalogUploadRequest>

</Request>

</cXML>

--kdflkajfdksadjfklasdjfkljdfdsfdkf

Content-type: text/plain; charset=US-ASCII

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

--kdflkajfdksadjfklasdjfkljdfdsfdkf--

308 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Catalog Upload Transaction

CatalogUploadRequest Element

CatalogUploadRequest

has the following attribute:

operation

Specifies the type of upload to perform:

“new”

“update”

Uploads a new catalog. A catalog with the same name must not exist.

Overwrites an exiting catalog. A catalog with the same name must exist.

CatalogUploadRequest

contains the following elements.

CatalogName

CatalogName

specifies the name of the uploaded catalog. This value is the user-visible name, not the file name of the catalog.

CatalogName

has the following attribute:

xml:lang

Specifies the language used for the catalog name.

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.

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.

Description

has the following attribute:

xml:lang

Specifies a language used for the catalog name.

For more information, see the description of xml:lang

for

CatalogName

, above.

cXML User’s Guide 309

Catalog Upload Transaction Chapter 12 Catalogs

Attachment

Attachment

specifies the URL of the attached catalog.

The

Attachment

element contains one

URL

element with the scheme “cid:”.

For more information about attachments, see

“Attaching Your Catalog” on page 311.

Commodities

Commodities

specifies the top-level commodity codes for the items in your catalog.

Buying organizations use these codes to search for new catalogs.

The

Commodities

element contains one or more

CommodityCode

elements.

Use two-digit UNSPSC (United Nations Standard Products and Services Code) segment codes.

For a list of UNSPSC segment codes, go to the UNSPSC website at www.unspsc.org

.

AutoPublish

AutoPublish

automatically publishes the catalog to buyers after upload.

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.

AutoPublish has the following attribute:

Enabled

Specifies whether to automatically publish the catalog:

“true”

“false”

Publishes the catalog. It must be an update to a previously published catalog.

Does not publish the catalog. You can log on to your account and manually publish the catalog.

310 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Catalog Upload Transaction

Notification

Notification

sends catalog-status notifications through e-mail or cXML POST. For examples of these messages, see

“Receiving Later Catalog Status” on page 313.

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.

The URL destination of the

StatusUpdateRequest

is determined by your website’s

response to the ProfileRequest transaction. For more information see Chapter 3,

“Profile Transaction.”

URLPost

has the following attribute

Enabled

Specifies whether the network sends catalog-status notifications through StatusUpdateRequest :

“true”

Enables this feature.

“false”

Disables this feature.

Attaching Your Catalog

Send your catalog attached to the

CatalogUploadRequest

document. Large catalogs must be zipped to compress them before uploading.

Using a MIME envelope

Include the catalog file in the

CatalogUpdateRequest

as a MIME (Multipurpose Internet

Mail Extensions) attachment. cXML contains only references to external MIME parts sent within one multipart MIME envelope.

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.

Note:

The cXML specification allows attachments to reside outside of the

MIME envelope, but the Catalog Upload transaction does not support that attachment method.

cXML User’s Guide 311

Catalog Upload Transaction Chapter 12 Catalogs

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

Catalog files can be zipped to compress them.

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">

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

The following table lists possible status codes:

Status

200

201

461

462

463

464

465

466

467

468

469

470

Text

Success

Accepted

Bad Commodity Code

Catalog Has Errors

Meaning

The catalog-upload request succeeded.

The catalog-upload request is processing.

The commodity code you assigned to the catalog is invalid.

Notification Error

Bad Catalog Format

No Catalog to Update

Publish Not Allowed

Catalog Too Large

No notification method (e-mail or URL) provided.

The zip file is invalid.

Bad Catalog No catalog is attached, or more than one is attached.

Duplicate Catalog Name The name of the catalog exists.

The catalog to be updated does not exist.

You attempted to publish a catalog that was not previously published.

The size of the uploaded file exceeds the 4 MB limit.

Zip the catalog to compress it before uploading it.

Bad Catalog Extension The file name of the catalog must have .cif, .xml, or

.zip extensions.

The message is the status of the catalog.

(HasErrors)

312 cXML User’s Guide 1.2.021 November 2009

Chapter 12 Catalogs Catalog Upload Transaction

Status Text

499

561

Document Size Error

Too Many Catalogs

562 Publish Disabled

563 Catalog Validating

Meaning

The cXML document is too large.

You cannot upload more than a specific number of catalogs per hour.

Catalog publishing is temporarily unavailable due to scheduled maintenance. It will be back online by the specified date and time.

You attempted to update a catalog before validation finished on a previous version of the catalog.

For other possible status codes, see “Status” on page 48.

Receiving Later Catalog Status

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:

Validated

BadZipFormat

HasErrors

Published

The catalog contains no syntax errors.

The zip format is incorrect.

The catalog contains syntax errors, and it cannot be published.

The catalog has been published (private or public).

URLPost

The following example shows a

StatusUpdateRequest

notification sent by a network commerce hub:

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

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

<cXML timestamp="2001-01-23T18:39:44-08:00" payloadID="980303984882--

[email protected]">

<Header>

<From>

<Credential domain="NetworkID">

<Identity>AN01000000001</Identity>

</Credential>

</From>

<To>

<Credential domain="DUNS">

<Identity>123456789</Identity>

</Credential>

</To>

<Sender>

<Credential domain="NetworkID">

<Identity>AN01000000001</Identity>

cXML User’s Guide 313

Catalog Upload Transaction Chapter 12 Catalogs

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>ANValidator</UserAgent>

</Sender>

</Header>

<Request>

<StatusUpdateRequest>

<DocumentReference payloadID="123456669131--

[email protected]"></DocumentReference>

<Status text="Success" code="200">

Validated

</Status>

</StatusUpdateRequest>

</Request>

</cXML>

The possible status codes are:

Status Code

200 Success

463 Bad Catalog Format

470 Catalog Has Errors

Meaning

The catalog-upload request succeeded.

The zip file is invalid.

The message is the status of the catalog. (HasErrors)

314 cXML User’s Guide 1.2.021 November 2009

Chapter 13

Get Pending/Data Download

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 transactions enables these organizations to poll for waiting documents and download them.

This chapter describes:

•

Introduction to Get Pending/Data Download Transaction

•

GetPendingRequest

•

GetPendingResponse

•

DataRequest

•

DataResponse

Introduction to Get Pending/Data Download Transaction

Client systems use the get pending and data download transactions to pull documents at their convenience. The get pending transaction indicates whether there are waiting documents. If there are waiting documents, they either appear in the response, or the client retrieves them with the data download transaction.

Examples of documents that depend on this polling for transmission are:

•

SupplierChangeMessage —

Notifies buying organizations about changes to supplier data.

•

SubscriptionChangeMessage —

Notifies buying organizations about changes to supplier catalogs.

•

DataAvailableMessage —

Notifies any organization about waiting documents that can be retrieved using the data download transaction.

cXML User’s Guide 315

GetPendingRequest Chapter 13 Get Pending/Data Download Transaction

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.

lastReceivedTimestamp

(optional) maxMessages

(optional)

The timestamp of the most recent document received.

Maximum number of documents in a single response that the requester can handle.

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="SystemID">

<Identity>ERP01</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" maxMessages="5">

<MessageType>SubscriptionChangedMessage</MessageType>

</GetPendingRequest>

</Request>

</cXML>

316 cXML User’s Guide 1.2.021 November 2009

Chapter 13 Get Pending/Data Download Transaction GetPendingResponse

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

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>

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

The following example contains a waiting

SubscriptionChangeMessage

document:

<?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>

<Status code="200" text="OK"/>

<GetPendingResponse>

<cXML xml:lang="en-US" payloadID="[email protected]" timestamp=""2005-01-12T16:00:25-08:00">

<Header>

<From>

cXML User’s Guide 317

GetPendingResponse Chapter 13 Get Pending/Data Download Transaction

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

For information about the

SupplierChangeMessage

element, see

“SupplierChangeMessage” on page 298. For information about the

SubscriptionChangeMessage

element, see “SubscriptionChangeMessage” on page 305.

318 cXML User’s Guide 1.2.021 November 2009

Chapter 13 Get Pending/Data Download Transaction GetPendingResponse

Documents Referenced through DataAvailableMessage

GetPendingReponse

documents can refer to waiting documents with a

DataAvailableMessage

element, instead of including them in-line. This element contains an internal identifier, which the client uses to retrieve the documents. The client uses the data download transaction, which transports documents as Multipurpose Internet

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.

•

MIME attachments are simpler to process than nested documents with multiple parent and child elements.

•

MIME is better for large documents, which transport as separate files, rather than one very large document.

The following example contains a

DataAvailableMessage

element, which indicates that there documents waiting for retrieval through the data download transaction.

<?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: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>

<Credential domain="NetworkId">

<Identity>AN01000000001</Identity>

<UserAgent>ANCXMLDispatcher</UserAgent>

</Credential>

cXML User’s Guide 319

DataRequest Chapter 13 Get Pending/Data Download Transaction

</Sender>

</Header>

<Message>

<DataAvailableMessage>

<InternalID domain="PendingMessages">3738</InternalID>

</DataAvailableMessage>

</Message>

</cXML>

</GetPendingResponse>

</Response>

</cXML>

The

DataAvailableMessage

element contains an internal ID, which corresponds to one or more documents waiting for download. Use the data download transaction to retrieve them.

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>

320 cXML User’s Guide 1.2.021 November 2009

Chapter 13 Get Pending/Data Download Transaction

<InternalID domain="PendingMessages">3738</InternalID>

</DataRequest>

</Request>

</cXML>

DataResponse

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.

The following

DataResponse

document has one

StatusUpdateRequest

document attached.

Content-Type: multipart/mixed; boundary="----=_Part_0_10550230.1105574425445"

------=_Part_0_10550230.1105574425445

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="2005-01-12T16:00:25-08:00"

payloadID="[email protected]">

<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]>

<?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-12T15:51:59-08:00">

<Header>

<From>

<Credential domain="NetworkId">

<Identity>AN12000000259</Identity>

</Credential>

cXML User’s Guide 321

DataResponse Chapter 13 Get Pending/Data Download Transaction

</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--

For more information on MIME attachments, see

“Attachments” on page 33.

You do not need to authenticate documents downloaded through the data download transaction if they come from a trusted source.

322 cXML User’s Guide 1.2.021 November 2009

Chapter 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 communicate during this transaction. These cXML documents are

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.

This chapter describes:

•

Message Flow

•

ProviderSetupRequest Document

•

ProviderSetupResponse Document

•

ProviderDoneMessage Document

cXML User’s Guide 323

Message Flow Chapter 14 Provider PunchOut Transaction

Message Flow

The order of cXML message flow in the Provider PunchOut transaction is shown in the following diagram.

1. Provider Setup Request

Network

O

RIGINATING

A

PPLICATION

2. Provider Setup Response

3. Provider Done Message

P

ROVIDER

To initiate a Provider PunchOut, the originating application sends a

ProviderSetupRequest

document to the provider. This document includes credential information for the user and the user’s organization, the return URL, and the service requested from the provider. To acknowledge the request, the provider sends a

ProviderSetupResponse

document to the originating application and includes a URL for the start page indicating where the user should be redirected. When the user has finished, the provider sends a

ProviderDoneMessage

document back to the originating application, indicating that the user has completed their session at the provider’s site.

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.

324 cXML User’s Guide 1.2.021 November 2009

Chapter 14 Provider PunchOut Transaction ProviderSetupRequest Document

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

<Credential domain="NetworkId" type="marketplace">

<Identity>AN01000001709</Identity>

</Credential>

<Credential domain="triton.com">

<Identity>9999</Identity>

</Credential>

</From>

<To>

<!-- Marketplace -->

<Credential domain="NetworkId">

<Identity>AN01000000003</Identity>

</Credential>

</To>

<Sender>

<!-- Triton Bank -->

<Credential domain="NetworkId">

<Identity>AN01000001709</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>www.triton.com</UserAgent>

</Sender>

</Header>

Because the

Header

element is similar for each message type, see “Header” on page 43

for specifics on how to construct this portion of the message.

Request

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

cXML User’s Guide 325

ProviderSetupRequest Document Chapter 14 Provider PunchOut Transaction

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

Element

ProviderSetupRequest

OriginatorCookie

BrowserFormPost

URL

SelectedService

Extrinsic

Instances Parent Elements

1

1

0 or 1

0 or 1

Request

Child Elements

OriginatorCookie,

BrowserFormPost,

SelectedService,

Extrinsic

None ProviderSetupRequest,

ProviderDoneMessage

ProviderSetupRequest URL

None

1

BrowserFormPost,

Followup

ProviderSetupRequest None

Any ProviderSetupRequest Varies

Attributes

None

None

None

None

None name

The elements in the header section are:

Request

Contains a request to initiate a Provider PunchOut transaction, and in this case contains a

ProviderSetupRequest

element.

ProviderSetupRequest

A request from an originating application to a provider to initiate a transaction.

326 cXML User’s Guide 1.2.021 November 2009

Chapter 14 Provider PunchOut Transaction ProviderSetupRequest Document

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.

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 the requestor’s site to return the user when they have finished at the provider site.

SelectedService

Identifies the service requested by the originating application and offered by the provider.

Extrinsic

The extrinsics for the Provider PunchOut depend upon what service the provider 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

To demonstrate a typical

ProviderSetupRequest

document, the following is a request 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>

</Credential>

<Credential domain="triton.com">

<Identity>9999</Identity>

</Credential>

</From>

<To>

<Credential domain="NetworkId">

cXML User’s Guide 327

ProviderSetupResponse Document Chapter 14 Provider PunchOut Transaction

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

328 cXML User’s Guide 1.2.021 November 2009

Chapter 14 Provider PunchOut Transaction ProviderSetupResponse Document

The following table provides guidelines for the structure of the

ProviderSetupResponse document of the Provider PunchOut transaction.

Element

Response

Status

ProviderSetupReponse

StartPage

URL

1

1

1

1

Instances

1

Parent Elements

cXML

Response

Response

Child Elements

Status,

ProviderSetupResponse

None

StartPage

ProviderSetupReponse URL

StartPage None

Attributes

None code

, text

None

None

None

Response

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:

code text

The status code of the request. This follows the HTTP status code model.

For example, 200 represents a successful request.

The text of the status message. This text aids user readability in logs, and 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 interoperability testing.

The provider should not include the

ProviderSetupResponse

element unless the status code is in the 200 range. See

“Status” on page 48 for a list of all possible status code

values.

ProviderSetupResponse

If the request was successful, the

ProviderSetupResponse

element is included in the response document and contains the

StartPage

and

URL

elements which indicate where the user should be redirected.

cXML User’s Guide 329

ProviderDoneMessage Document Chapter 14 Provider PunchOut Transaction

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.

330 cXML User’s Guide 1.2.021 November 2009

Chapter 14 Provider PunchOut Transaction ProviderDoneMessage Document

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

<UserAgent>Purchase</UserAgent>

</Sender>

</Header>

Because the

Header

element is similar for each message type, see “Header” on page 43

for the specifics on how to construct this portion of the message.

Message

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"/>

<ProviderDoneMessage>

<OriginatorCookie>c546794949</OriginatorCookie>

<ReturnData name="method">

<ReturnValue>Triton.transact</ReturnValue>

<Name xml:lang="en-US">Triton OM transact</Name>

</ReturnData>

</ProviderDoneMessage>

</Message>

cXML User’s Guide 331

ProviderDoneMessage Document Chapter 14 Provider PunchOut Transaction

The following table details guidelines for the structure of the message section of the

ProviderDoneMessage

document.

Element

Message

Status

ProviderDoneMessage

OriginatorCookie

ReturnData

ReturnValue

Name

1

1

Instances

1

1

1

1

Any

Parent Elements

None

Message

Message

Child Elements

Status,

ProviderDoneMessage

None

OriginatorCookie,

ReturnData,

ReturnValue,

Name

ProviderDoneMessage None

ProviderDoneMessage ReturnValue,

Name

ProviderSetupRequest

BrowserFormPost,

Followup

None

None

Attributes

None text, code

None

None name

None xml:lang

The elements in the message section are:

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.

332 cXML User’s Guide 1.2.021 November 2009

Chapter 14 Provider PunchOut Transaction ProviderDoneMessage Document

When displaying values, keep in mind that

Name

and

ReturnValue

have similar semantics, but different uses in the originating application.

cXML User’s Guide 333

ProviderDoneMessage Document Chapter 14 Provider PunchOut Transaction

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">

<Identity>AN01000001709</Identity>

</Credential>

</To>

<Sender>

<!-- marketplace -->

<Credential domain="NetworkId">

<Identity>AN01000000003</Identity>

</Credential>

<UserAgent>Purchase</UserAgent>

</Sender>

</Header>

<Message>

<Status code="200" text="OK"/>

<ProviderDoneMessage>

<OriginatorCookie>c546794949</OriginatorCookie>

<ReturnData name="method">

<ReturnValue>Triton.transact</ReturnValue>

<Name xml:lang="en-US">Triton OM transact</Name>

</ReturnData>

</ProviderDoneMessage>

</Message>

</cXML>

334 cXML User’s Guide 1.2.021 November 2009

Chapter 15

Alternative Authentication

Methods

cXML supports alternatives to the shared secret authentication method for verifying the sender of cXML documents.

This chapter describes:

•

Message Authentication Code (MAC)

•

Auth Transaction

Message Authentication Code (MAC)

Message Authentication Code (MAC) authentication allows the authentication of 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 45.

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

cXML User’s Guide 335

Message Authentication Code (MAC) Chapter 15 Alternative Authentication 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.

For more information about IETF RFC 2104, see

www.ietf.org/rfc/rfc2104.txt

.

Creation and Expiration Dates

Creation and expiration dates add additional security to MACs.

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.

336 cXML User’s Guide 1.2.021 November 2009

Chapter 15 Alternative Authentication Methods Message Authentication Code (MAC)

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.

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):

From/Credential@domain

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.

Normalizing the Inputs

Normalize the values listed above to remove differences in case and formatting before computation:

Value

domain

Identity creationDate expirationDate

Normalize by...

Use the lowercase version of the string, unless it is known to be case sensitive, for example, “AribaNetworkUserId”. Note that

“NetworkId” and “DUNS” are not casesensitive.

Discard leading or trailing whitespace and use the lowercase version of the string.

No normalization needed, because they are in ISO8601 format described in

“Date,

Time, and other Data Types” on page 40.

Normalized Example

networkid an9900000100

2003-01-15T11:42:46-

08:00

Do not normalize the shared secret.

cXML User’s Guide 337

Message Authentication Code (MAC) Chapter 15 Alternative Authentication Methods

338

MAC Algorithm

The only supported MAC algorithm value is

"HMAC-SHA1-96"

, which corresponds to the HMAC-SHA1 algorithm, which produces a 160 bit (20 byte) output, and retaining only the left-most 96 bits (12 bytes). The 12 bytes are then base-64 encoded, yielding a 16-byte character string consisting only of characters in the set [A-Z a-z 0-9 +/].

W

To computer the MAC:

1.

Concatenate the UTF-8-encoded byte representation of the following strings, each followed by a null byte (0x00). (The strings have been normalized as described above):

“networkid”, “an9900000100”, “networkid”, “an9900000100”,

“2003-01-15T08:42:46-08:00”, “2003-01-15T11:42:46-08:00”

The concatenation yields the following byte sequence:

6e 65 74 77 6f 72 6b 69 64 00 61 6e 39 39 30 30

30 30 30 31 30 30 00 6e 65 74 77 6f 72 6b 69 64

00 61 6e 39 39 30 30 30 30 30 31 30 30 00 32 30

30 33 2d 30 31 2d 31 35 54 30 38 3a 34 32 3a 34

36 2d 30 38 3a 30 30 00 32 30 30 33 2d 30 31 2d

31 35 54 31 31 3a 34 32 3a 34 36 2d 30 38 3a 30

30 00

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

Do not terminate or normalize the shared secret.

3.

Truncate the above result to 96 bits (12 bytes):

71 1e 89 a7 3e 7c 9e b8 97 11 10 cd

Truncation helps increase the security of the hash.

4.

Base-64 encode the above result to yield the final result: cR6Jpz58nriXERDN

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

cXML User’s Guide 1.2.021 November 2009

Chapter 15 Alternative Authentication Methods Message Authentication Code (MAC)

ProfileResponse

The following cXML example shows a

ProfileResponse

sent from a trusted third party

(such as a commerce network hub) to a client (such as a procurement application) so 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>

<Option name="CredentialMac.algorithm">HMAC-SHA1-96</Option>

<Option name="CredentialMac.creationDate">2003-01-15T08:42:46-0800</Option>

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

<Option name="Direct.AuthenticationMethod.CredentialMac">Yes</Option>

<Option name="Direct.AuthenticationMethod.Certificate">Yes</Option>

</Transaction>

</ProfileResponse>

</Response>

</cXML>

For more information about the Profile transaction, see Chapter 3, “Profile

Transaction.”

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>

<Credential domain=”DUNS”>

<Identity>049329048</Identity>

</Credential>

</To>

<From>

<Credential domain=”NetworkId”>

<Identity>AN9900000100</Identity>

</Credential>

cXML User’s Guide 339

Auth Transaction Chapter 15 Alternative Authentication Methods

</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 45.

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

340 cXML User’s Guide 1.2.021 November 2009

Chapter 15 Alternative Authentication Methods Auth Transaction

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 credential and certificate, the receiver need not send another

AuthRequest

.

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.

<!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="NetworkId">

<Identity>AN99000000092</Identity>

</Credential>

</From>

<To>

<Credential domain="NetworkId">

<Identity>AN99000000092</Identity>

</Credential>

</To>

<Sender>

<Credential domain="NetworkId">

<Identity>AN99000000092</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>cXML application 2.0</UserAgent>

</Sender>

</Header>

<Request>

<AuthRequest>

<Credential domain="DUNS">

<Identity>12345</Identity>

</Credential>

<X509Data>

<X509IssuerSerial>

<X509IssuerName>Verisign</X509IssuerName>

<X509SerialNumber>12345</X509SerialNumber>

</X509IssuerSerial>

</X509Data>

</AuthRequest>

</Request>

</cXML>

cXML User’s Guide 341

Auth Transaction Chapter 15 Alternative Authentication Methods

Credential

A cXML credential.

For more information, see

“Credential” on page 45.

X509Data

Describes the X.509 client certificate being used for authentication.

X509IssuerSerial

A container for the serial number and issuer name of the X.509 certificate.

X509IssuerName

The distinguished name of the issuer of the X.509 certificate. The distinguished name should be a string representation of an LDAP

Distinguished Name, as described in RFC 2253. For example,

C=US, O=”John Doe Data Security, Inc.”, OU=Secure Server Certification Authority

X509SerialNumber

The serial number of the X.509 certificate.

X509SKI

The Subject Key Identifier of the X.509 certificate.

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

Contains the Base-64-encoded X.509v3 certificate.

X509CRL

Contains a Base-64-encoded X.509v3 Certificate Revocation List.

342 cXML User’s Guide 1.2.021 November 2009

Chapter 15 Alternative Authentication Methods Auth Transaction

AuthResponse

Returns a list of valid credentials of the person entity in the

AuthRequest

document.

Note that this response is for successful authentications only.

AuthResponse

has the following attribute:

expirationDate

(optional)

Specifies the time beyond which the information contained in the AuthResponse must be discarded. The inclusion of this attribute specifies that the receiver can cache the

AuthResponse information until the expirationDate

.

The absence of an expirationDate

should be interpreted to forbid caching.

<?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>

</Credential>

</AuthResponse>

</Response>

</cXML>

cXML User’s Guide 343

Auth Transaction Chapter 15 Alternative Authentication Methods

344 cXML User’s Guide 1.2.021 November 2009

Chapter 16 cXML Digital Signatures

Any cXML request, response, or message can be signed using World Wide Web

Consortium (W3C) XML Digital Signatures. Support for the XML Advanced

Electronic Signature (XAdES) standard is also included.

This chapter describes:

•

Digital Signature Overview

•

Signing cXML Documents

Readers of this chapter should be familiar with electronic signature terminology and concepts such as asymmetric key pairs, certificates, and smart cards.

Digital Signature Overview

Digital signatures confirm the identity of the sender of an electronic document, and ensure that the document was not modified after it was generated by the signer. They consist of a series of bytes that contain cryptographic information, including the sender’s public key and detailed information about the contents of the document being signed.

An XML digital signature—which is a specific arrangement of a digital signature—is an element that contains other information besides the cryptographic signature itself, including a list of what was signed, the signer’s public key, and other attributes. A cXML signature is an XML digital signature of a certain form, as described later in this chapter.

XML Advanced Electronic Signature (XAdES) provides basic authentication and integrity protection.

cXML User’s Guide 345

Signing cXML Documents Chapter 16 cXML Digital Signatures

W3C XML signatures and XAdES have many options designed to allow for flexibility. These options are described in the following resources:

•

For information about W3C XML digital signatures, see www.w3.org

.

•

For information about XAdES, see

uri.etsi.org/01903/v1.3.2

.

Options for Signing

You can use a service to sign documents on your behalf, or you can implement the necessary hardware or software systems to sign the documents yourself. If you implement your own signing system, you must obtain a certificate signed by a

Certificate Authority (CA) trusted by the receiver. Meeting receiver requirements might mean obtaining hardware that keeps the private key secret, such as a smart card or Hardware Security Module.

Note that signature and certificate requirements vary according to local laws and regulations. Prior to implementing a signing system, be sure you learn the requirements of the relevant locale.

Signing cXML Documents

A valid cXML digital signature is not just an XML signature, but an XML signature that uses particular options, has particular elements present, and signs (or does not sign) certain portions of the document.

cXML Digital Signatures

Note that namespace prefix conventions are used here when referring to elements that come from other specifications. All W3C XML Digital Signature elements use the ds prefix, and all XAdES elements use the xades

prefix.

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, one or more signatures, and the keys used to create the signature or signatures. 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.

346 cXML User’s Guide 1.2.021 November 2009

Chapter 16 cXML Digital Signatures Signing cXML Documents signatureVersion

If present, signatureVersion implies that the document is digitally signed, that is, that the document contains a valid ds:Signature

element immediately following the

Request

,

Response

, or

Message

element. If the document is signed, this attribute must be present. The only valid value for the attribute is 1.0

; other values are reserved for future use.

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, “cXML Basics.”.

Id

This attribute can be used to call out an element and all its children as a target for signing. For example, if a document contains

<Request Id="foo">

, then in the digital signature <Reference URI="#foo"> will refer to the

Request element and all its children. If the document is signed, this attribute must be present.

cXMLSignedInfo

The cXMLSignedInfo

element includes cXML-specific details about the signature, and has the following attributes:

signatureVersion payloadID

Required. signatureVersion

implies that the document is digitally signed, that is, that the document contains a valid ds:Signature element immediately following the

Request

,

Response

, or

Message

element. The only valid value for the attribute is

1.0

; other values are reserved for future use.

Required. The payloadID

attribute is used to establish links between documents. The payloadID in the cXMLSignedInfo element must be the same as the payloadID

in the document’s main cXML

element.

Signing Essentials

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>

<cXMLSignedInfo Id="cXMLSignedInfo"

signatureVersion="1.0"

payloadID="xxx"/>

</ds:Object>

cXML User’s Guide 347

Signing cXML Documents Chapter 16 cXML Digital Signatures

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 in the ds:SignedInfo,

as follows:

<ds:Reference URI="#cXMLSignedInfo">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<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 required for digital signatures. In the signature, xades:QualifyingProperties should be the second ds:Object . 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 . When using XAdES, 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

If the document in question includes attachments, digital signatures can be used to sign just the document, or both the document and its attachments. Signatures are structured in such a way that if the attachments are discarded, the signature on the document itself can still be validated.

The attachments should be signed using ds:Reference

elements in a ds:Manifest

element included under a ds:Object

contained in the signature. The

Id

attribute of the ds:Manifest element must be

"AttachmentManifest"

. The ds:Object

should occur immediately after the ds:Object

containing the xades:QualifyingProperties

element, if it is present. Otherwise, it should occur immediately after the ds:Object containing the cXMLSignedInfo element

.

348 cXML User’s Guide 1.2.021 November 2009

Chapter 16 cXML Digital Signatures Signing cXML Documents

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">

<ds:Reference URI="cid:[email protected]">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>P6ua59kKBLLtMBFE+IwPUgp2xqc=</ds:DigestValue>

</ds:Reference>

<ds:Reference URI="cid:[email protected]">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>P6ua59kKBLLtMBFE+IwPUgp2xqc=</ds:DigestValue>

</ds:Reference>

</ds:Manifest>

</ds:Object>

Error Status Codes for Digital Signatures

The following table lists cXML digital signature status codes:

Status

475

476

477

Text

Signature

Required

Signature

Verification

Failed

Signature

Unacceptable

Meaning

The receiver is unwilling to accept the document because it does not have a digital signature.

The receiver is unable to validate the signature, possibly because the document was altered in transit, or the receiver does not support one or more algorithms used in the signature.

The signature is technically valid, but is not acceptable to the receiver for some other reason. The signature policies or certificate policies might be unacceptable, the type of certificate used might be unacceptable, or there might be some other problem.

cXML User’s Guide 349

Signing cXML Documents Chapter 16 cXML Digital Signatures

Digital Signature Example

The following example shows a signed invoice. Note that the digest values and signature value are not correct, because parts of the invoice document have been abbreviated for this example.

<?xml version="1.0" ?>

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

<cXML payloadID="[email protected]" signatureVersion="1.0" 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">

350 cXML User’s Guide 1.2.021 November 2009

Chapter 16 cXML Digital Signatures Signing cXML Documents

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

<ds:X509Data>

<ds:X509Certificate>

MIICgDCCAekCAw7cUTANBgkqhkiG9w0BAQQFADCBijELMAkGA1UEBhMCVV w7cUTANBgkqhkiG9w0BAQQFADCBijELMAkGA1UEBhMCVVMxEzARBgNV

MIICgDCCAekCAw7cUTANBgkqhkiG9w0BAQQFADCBijELMAkGA1UEBhMCVV w7cUTANBgkqhkiG9w0BAQQFADCBijELMAkGA1UEBhMCVVMxEzARBgNVBA

MIICgDCCAekCAw7cUTANBgkqhkiG9w0BAQQFADCBijELMAkGA1UEBhMCVV zuRel/9tb8M95FuN5yR9GUGl5PgkzwuCQYobJqIcAs=</ds:X509Certificate>

</ds:X509Data>

</ds:KeyInfo>

<ds:Object>

<cXMLSignedInfo Id="cXMLSignedInfo" payloadID="[email protected]" signatureVersion="1.0">

</cXMLSignedInfo>

</ds:Object>

<ds:Object>

<xades:QualifyingProperties xmlns:xades="http://uri.etsi.org/01903/v1.1.1#"

Target="#cXMLSignature">

<xades:SignedProperties Id="XAdESSignedProps">

<xades:SignedSignatureProperties>

<xades:SigningTime>2003-09-30T18:32:27Z</xades:SigningTime>

<xades:SigningCertificate>

<xades:Cert>

<xades:CertDigest>

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">

</ds:DigestMethod>

<ds:DigestValue>LETnT8c7gvZqp3oVt8/BLOJpeeA=</ds:DigestValue>

</xades:CertDigest>

<xades:IssuerSerial>

cXML User’s Guide 351

Signing cXML Documents Chapter 16 cXML Digital Signatures

<ds:X509IssuerName>[email protected],

CN=anrc.hub.com, O="Hub, Inc.", L=Mountain View, ST=California,

C=US</ds:X509IssuerName>

<ds:X509SerialNumber>973905</ds:X509SerialNumber>

</xades:IssuerSerial>

</xades:Cert>

</xades:SigningCertificate>

<xades:SignaturePolicyIdentifier>

<xades:SignaturePolicyImplied>

</xades:SignaturePolicyImplied>

</xades:SignaturePolicyIdentifier>

</xades:SignedSignatureProperties>

</xades:SignedProperties>

</xades:QualifyingProperties>

</ds:Object>

</ds:Signature>

</cXML>

352 cXML User’s Guide 1.2.021 November 2009

Appendix A

New Features in cXML 1.2.021

cXML 1.2.021 contains the following new features:

•

“exemptDetail Attribute” on page 353

•

“Extrinsic Element Support” on page 353

DTDs and documentation for this version are available at

www.cXML.org

.

exemptDetail Attribute

The following new attribute is included in the TaxDetail element: exemptDetail.

For more information, see

“TaxDetail” on page 258.

Extrinsic Element Support

The following elements now include an Extrinsic element:

•

Tax

•

TaxDetail

•

StatusUpdateRequest

cXML User’s Guide 353

Extrinsic Element Support Appendix A New Features in cXML 1.2.021

354 cXML User’s Guide 1.2.021 November 2009

Index

A

Accounting element 158

AccountingSegment element 158

Address element 124, 150 addressID attribute 124

agreementDate attribute 207 agreementID attribute 207

OrderRequestHeader element 122

agreementItemNumber attribute 130

AgreementItemOut element 208

agreementPayloadID attribute

OrderRequestHeader element 122

AirDetail element 141

AirLeg element 142

AirLeg element 142 about 142

AirLeg attributes 143

AirLegDestination element 144

AirLegOrigin element 144

Airport element 140 airportCode attribute 140

alternateAmount attribute 59 alternateCurrency attribute 59

&lt through &apos entities 41

ApprovalInfo element 200 approvedDate attribute 200

arrivalTime attribute 143, 149, 152

AssetInfo Element 241

Attachment element 128

attachments

signing 348

to purchase orders 160

AvailablePrice element 138

CarRentalDetail element 149

B

backordered status

header level 220

line-item level 228

bedType attribute 150

BillTo element 124

blanket purchase orders 122

BlanketItemDetail element, of an ItemOut

133

booking orders 81

BookingClassCode element 139, 141, 145

BrowserFormPost element 105, 326, 327

buyer and supplier cookies 90, 100

BuyerCookie element 105, 109

C

caching DTDs 25

CarRentalDetail element

about 146 attributes 146

AvailablePrice element 149

BookingClassCode element 147

CarRentalDropoff element 146

CarRentalFee element 147

CarRentalPickup element 146

LimitedMileage element 148

Vendor element 146, 150, 153

CarRentalFee element

attribute 148 values of type attribute 148

CarrierIdentifier element 236

carType attribute 152

Catalog.dtd 25

character encoding 32

cXML User’s Guide 355

character entities 41

Charge element 159

checkinTime attribute 149 checkoutTime attribute 149

Classification element 83

code attribute 48, 329

Comments element

about 128

ConfirmationHeader 224

ShipNoticePortion element 238

ConfirmationHeader element 218

ConfirmationItem element 217, 225

ConfirmationRequest element 215, 217

ConfirmationStatus element 226

confirmID attribute 221

Contact element 60, 156, 197, 200

about 126 attributes 126

ShipNoticePortion element 238

submittedDate attribute 200

Contractor element 156, 197

ContractorIdentifier element 156, 197

cookies

buyer and supplier 90, 100

copy node 164

corporateURL attribute 286

Credential element 45

CredentialMac

in ProfileRequest 64

in ProfileResponse 65

currency attribute 59

cXML digital signature overview 345

cXML Digital Signatures 346

cXML element 38

cXML license agreement ii

cXML.dtd 25 cxml.org Website 25

cXML-base64 hidden field 56, 98

cXMLSignedInfo element 347

cXML-urlencoded hidden field 55, 98

D

DataAvailableMessage 319

DataRequest 320

356 cXML User’s Guide

Index

DataResponse 321

date and time format 40, 135

debit and credit amounts

PCard orders 244

DeliverTo element 124

deliveryDate attribute 233

departureTime attribute 143, 149, 152

deploymentMode attribute 48, 53

Description element 83, 112

Dimension element 239

direct marketplace 161

direct PunchOut 114

CredentialMac 65

ProfileResponse 65

Direct.AuthenticationMethod attributes 65

Distribution element 158

Document Type Definitions (DTDs) 24

DocumentReference element 129, 163, 200,

211

domain attribute 156

CarrierIdentifier element 236

Credential element 45

dropoffTime attribute

CarRentalDetail element 146

ds:Signature element 346

DTDs (Document Type Definitions) 24

caching locally 25

E

earlyCheckinAllowed attribute 149

EDI (X.12 Electronic Data Interchange) 21

editors for XML 27

effectiveDate attribute 63, 207

OrderRequestHeader element 123

encoding

character 32

entities 41

equipment attribute 143

error codes for digital signatures 349

Expense element 199 isNonBillable attribute 199

ExpenseAmount element 199 expenseDate element attribute 199

1.2.021 November 2009

Index

F

G

H

expirationDate attribute 207

OrderRequestHeader element 123

Extrinsic element 88, 100, 105, 157, 326, 327

about 129

ConfirmationHeader element 225

of LaborDetail element 157 of SpendDetail element 157

ShipNoticePortion element 238

Fax element 127

FeeDetail element

about 154

flightNumber attribute 143

Followup element 62, 128

form encoding 55, 98

From element 85

From, To, and Sender elements 44

Fulfill.dtd 25

GetPendingRequest element 316

GetPendingResponse 317

Hazard element 240

ConfirmationHeader 224

Header element 43

PunchOutSetupRequest 102

highest attribute 138 highestCompliant attribute 138

HotelDetail element 149 attributes 149

attributes of RoomType element 150

AvailablePrice element 151

BookingClassCode 151

Meal element 151

Rate element 151

HTML form encoding 55, 98

I

Id attribute 347

id attribute 158

Index element 288

IndexItemAdd element 289

IndexItemDelete element 289

IndexItemDetail element 290

IndexItemPunchout element 289

indirect marketplace 161

inReplyTo attribute 53

InvoiceDetail.dtd 25

InvoiceDetailPaymentTerm element 253

InvoiceDetailRequest 243–269

InvoiceDetailRequestHeader

PaymentTerm element 253

InvoiceLaborDetail element 263

invoiceOrigin attribute 248

InvoiceRequest 244

InvoiceRequest element 244

invoices 246

about 243

cancel type 246 credit memo type 246

debit and credit amounts 244

debit memo type 246

detailed invoices 245

dtd location 246

header invoice 245 individual and summary invoices 245

information only type 246

invoice levels 245

shipping information 244

specifying the purpose of 246 standard type 246

types 245

isAccountingInLine 249

isAdHoc attribute 130, 132

isDiscountInLine 249

isInternalVersion attribute

OrderRequestHeader element 122

isNetworkPayment 173

IsoCountryCode element 58

IsoLanguageCode element 58

isRecurring attribute

FeeDetail element 154

cXML User’s Guide 357

Index

isShippingInLine 249 isSpecialHandlingInLine 249 isTaxInLine 249

isTriangularTransaction 258 isVatRecoverable 258

ItemDetail element 112, 290

of an ItemOut 133

ItemID

of an ItemOut 132

ItemID element 111

ItemIn element 110

ItemOut element 130

J

JobDescription element 156

L

LaborDetail element

about 155

language

in cXML header 92

lastReceivedTimestamp attribute 316

lastRefresh attribute 63

lateCheckoutAllowed attribute 149

Launch Page 91

level attribute 137

license agreement, cXML ii

LimitedMileage element

attribute 148

Line-Item Credit Memo 246

lineNumber attribute 111, 130

ShipNoticeItem element 239

loadmode attribute for catalogs 289

locale, in cXML header 92

location attribute 241

lowest attribute 138 lowestCompliant attribute 138

M

MAC options in ProfileRequest 64

marketplace credential 45

MasterAgreementRequest 205

358 cXML User’s Guide

MaxAmount element 207

maxMessages attribute 316

maxQuantity element 208

MaxReleaseAmount element 207

maxReleaseQuantity element 208

Meal element 140

Message element 53

method attribute 235

MIME attachments 33, 160, 321

MinAmount element 207

minQuantity element 208

MinReleaseAmount element 208 minReleaseQuantity element 208

Money element 59

multiple credentials 46

N

Name element 124

new elements

PaymentTerm 253

non-catalog (ad-hoc) items 130

noticeDate attribute 221, 233

numberOfBed attribute 150

O

operation attribute 85, 104, 207

ConfirmationHeader element 222

ShipNoticeHeader element 232

operationAllowed attribute 109

Order Receiver Page 99

orderDate attribute

OrderReference element 217, 241

OrderRequestHeader element 122

orderID attribute 217

OrderReference element 217, 241

OrderRequestHeader element 122

OrderInfo element 197

OrderMethods element 288

OrderReference element 217, 241

ShipNoticePortion element 237

OrderRequest documents 116

1.2.021 November 2009

Index

OrderRequest element

diagram 117

example 118

structure 117

OrderRequestHeader element 120

attributes 122

example 120

orderType attribute

OrderRequestHeader element 122

orderVersion attribute

OrderRequestHeader element 122

OrganizationChangeMessage element 302

OrganizationDataRequest element 300

OrganizationDataResponse element 300

OriginalDocument element 163

OriginatorCookie element 326, 327

P

PackageIdentification element 237

Packaging element 239

PackagingCode element 239

parentAgreementID attribute

OrderRequestHeader element 122

parentAgreementPayloadID attribute 207

OrderRequestHeader element 122

Path element 163

of an ItemOut 133

path routing 161–170

payInNumberOfDays attribute 125

payloadID attribute 39, 85, 163, 211, 347

Payment element

about 125

payment, RequestToPay 212

paymentDate 258

PaymentProposalRequest 172

PaymentRemittance.dtd 25

PaymentTerm element

about 125 attribute 125

InvoiceDetailRequestHeader 253

Period element 156, 197

pickupTime attribute

CarRentalDetail element 146

pnrLocator attribute

TravelDetail element 135

PolicyViolationJustification element 137

preferred attribute 136

preferredLang attribute 252

Profile transaction 26

ProfileRequest element 62

ProfileResponse element 63

Provider PunchOut 323

ProviderDoneMessage 330

ProviderSetupRequest 324

ProviderSetupRequest element 326

ProviderSetupResponse 328

PunchOut index catalog 82, 106

PunchoutDetail element 291

punchoutLevel attribute 83, 291

PunchOutOrderMessage document 89

PunchOutOrderMessage element 108

PunchOutOrderMessageHeader element 109

PunchOutSetupRequest document 84

PunchOutSetupRequest element 103

PunchOutSetupResponse document 88

PunchOutSetupResponse element 107

purchase orders 115–160

about 115

attachments 160

blanket 122

Q

quantity attribute 111

ConfirmationStatus element 227

Dimension element 239

ItemOut element 130

ShipNoticeItem element 239

quoteExpirationTime attribute

TravelDetail element 135

quoteStatus attribute 109

quoting orders 80

R

RailDetail element 151

values of type attribute of TripType 152

cXML User’s Guide 359

RailLeg element

Vendor element 153

RailLegOrigin, RailLegDestination 153

rangeBegin attribute

PackageIdentification element 237

rangeEnd attribute

PackageIdentification element 237

Rate element 138

ravelSegment attribute 143

releaseRequired attribute

OrderRequestHeader element 122

remittance advice, about 172

replace 221

ReportedTime element 197

Request element 47

requestedDeliveryDate attribute 130

requestName attribute 67

RequestToPay 212

requestToPay 215, 221

requisitionID attribute 123, 130

Response element 48

ReturnData element 332

ReturnValue element 332

role values

for ConfirmationRequest 224

for OrderRequest 126

for PaymentPartner 176

for ShipControl 234

RoomType element 150

Route element 235

router node 163

S

seatNumber attribute 143, 152 seatType attribute 143

SelectedItem element 87, 106

SelectedService element 326, 327

Sender element 85

Sender Page 95

Sender, To, and From elements 44

serialNumber attribute 241

shipComplete attribute 123

shipmentDate attribute 233

shipmentID attribute 232

360 cXML User’s Guide

Index

ShipmentIdentifier element 236

ShipNoticeHeader element 230

ShipNoticeItem element 238

ShipNoticePortion element 237

ShipNoticeRequest element 230

Shipping element

about 125

ShipTo element 124

ShortName element 112

signatureVersion attribute 39, 347

smoking attribute 150

SourcingStatus element 109

SpendDetail element

about 134

grouping Extrinsics elements in 157 undefined spend category in 157

Start Page 95

StartPage element 107, 329, 330

Status element 48, 329

StatusUpdateRequest element 210

stops attribute 143

storeFrontURL attribute 286

SubmitterInfo element 200

Subscription element 303

SubscriptionContentRequest element 304

SubscriptionContentResponse element 305

SubscriptionListRequest element 304

SubscriptionListResponse element 304

SubscriptionStatus 306

SubscriptionStatusUpdateRequest 306

SubscriptionVersion 306

subsequentBuyer role 258

Supervisor element 156

supplier and buyer cookies 90, 100

Supplier element 286

SupplierChangeMessage element 298

SupplierDataRequest element 297

SupplierDataResponse element 297

SupplierID element 82

SupplierListRequest element 296

SupplierListResponse element 296

SupplierLocation element 287

SupplierOrderInfo element 129

SupplierPartAuxiliaryID element (Supplier

Cookie) 90, 100, 290

1.2.021 November 2009

Index

SupplierSetup element 88, 107

T

tagNumber attribute 241

Tax element

about 125

taxPointDate 258

TelephoneNumber element 127

TermsAndConditions element 136

text attribute 329

time and date format 40, 135

TimeCard element 195, 196

TimeCardTimeInterval element 198 duration attribute 198 isNonBillable attribute 198 payCode attribute 198

TimeRange element 199 endDate attribute 199 startDate attribute 199

timestamp attribute 39, 85

To element 85

To, From, and Sender elements 44

tools for working with XML 27

trainNumber attribute 152

Transaction element 67

TravelDetail

Money element of AvailablePrice 138

TravelDetail element

about 134

attributes 135

CarRentalDetail element 146

common elements in 135

HotelDetail element 149

RailDetail element 151

type attribute of AvailablePrice element

138

travelSegment attribute 149, 152

CarRentalDetail element 146

TriangularTransactionLawReference 259

TripType element 142, 151

type attribute

ConfirmationHeader element 220

ConfirmationStatus element 227

Credential element 45

Dimenstion element 239

OrderRequestHeader element 122

type definitions 291–295

U

Unit of Measure 58, 91

United Nations Standard Products and

Services Code (UNSPSC) 91

UnitOfMeasure element 262

UnitPrice element 262

UnitRate element 155, 262

upgrade attribute 143

URL element 59, 326

UserAgent element 44

utilities for use with XML 27

V

validating cXML 24

Vendor element 136, 144, 150

CarRentalDetail element 146, 150, 153

version attribute 39

W

W3C XML Digital Signatures 345

WorkLocation element 156

X

XAdES 345

XAdES, using 348

xml:lang 92

xml:lang attribute 39

xmllanguageCode element 58

cXML User’s Guide 361

www.cxml.org