This is article three in a series of five articles:
[PunchOut/cXML process and design](🔗)
[PunchOut/cXML configuration and data requirements](🔗)
PunchOut setup request and response
[PunchOut order Message (that is Cart information)](🔗)
[Order request (that is Purchase Order)](🔗)
## PunchOut setup request
The PunchOut Setup Request is the signal to initiate the PunchOut session. This communication is first created from a Customer's Procurement system and ultimately sent to <<product-name>> in the form of a PunchOut Setup Request cXML. The Customer's Procurement system will technically connect to the Integration Partner's system, so that connection will be established between those two parties.
PunchOut order failures on the <<product-name>> side are captured in the PunchOut Order Request log and an email communication is available and configurable, within the Admin Console, to communicate an order has failed. If cXML is poorly formatted or there was an issue with receiving the file, Insite will automatically, as a part of the REST services, notify your integration partner of the issue. This will be captured in the log file.
The Integration Partner will translate the Customer's PunchOut Setup Request message into Insite's standard cXML format and POST that cXML to a <<product-name>> endpoint. The endpoint will be located as follows, with a separate endpoint available for each domain setup within the <<product-name>> platform:
`<https://<DOMAIN>/punchout/punchoutsetuprequest.isch`
The PunchOut Setup Request cXML should contain the following:
Customer that is making the request
PunchOut operation
Create – User would like to create a brand new requisition order
Edit – User would like to make a change to an existing cart/requisition order
Inspect – User would like to view an existing cart/requisition order, but they cannot make any changes
Specific Ship – To Address ID
Unique request ID used to tie together future communications (that is Buyer Cookie)
PunchOut Setup Response URL
### PunchOut setup request cXML
The following is a sample PunchOut Setup Request cXML:
## PunchOut setup request data mapping
Below are the specific definitions around important cXML elements/attributes and their use by <<product-name>>:
<table class="TableStyle-Borders" style="margin-left: 0; margin-right: auto; width: 100%;" data-cellspacing="0"> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <thead> <tr class="header TableStyle-Borders-Head-Header1"> <th colspan="2" class="TableStyle-Borders-HeadD-Regular-Header1"><p>Field Mapping: PunchOut Setup Request cXML</p></th> </tr> <tr class="odd TableStyle-Borders-Head-Header1"> <th class="TableStyle-Borders-HeadE-Regular-Header1"><p>Element/Attribute</p></th> <th class="TableStyle-Borders-HeadD-Regular-Header1"><p>Use</p></th> </tr> </thead> <tbody> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Header><From><Credential><Identity></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>Represents the Customer from which the Setup Request originated. From a business perspective, it will correlate with a client's Bill-To customer.</p> <p>This value will need to tie back to the Username field on a User record in the <<product-name>> platform. This Username will only be used for PunchOut access.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Header><To><Credential><Identity></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>Represents the Client to which the Setup Request is sent. This should be the client's name, and does NOT tie back to an <<product-name>> Username.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Header><Sender><Credential><Identity></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>Represents the system sending the Setup Request to <<product-name>>. From a process perspective, it will represent the system sending the message to <<product-name>> (such as Integration Partner).</p> <p>This value will need to tie back to the Username field on a User record in the <<product-name>> platform.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Header><Sender><Credential> <SharedSecret></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The <<product-name>> password associated with the Username sent in the <Header><Sender><Credential><Identity> field. Technically used to validate that the Setup Request sent to <<product-name>> is from a valid source.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Header><Sender><UserAgent></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The application sending the Setup Request.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Request><PunchoutSetupRequest></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This node needs to exist to validate the cXML function is for a Setup Request</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Request><PunchoutSetupRequest operation></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This value will be "create", "edit" or "inspect", depending on the reason for the Setup Request.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><...> <BuyerCookie></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The data that allows the Customer's Procurement System to tie together multiple outstanding PunchOut requests.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><...> <BrowserFormPost></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The URL provided here will be the location where the PunchOut Order Message will be sent.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><...><BillTo><Address addressID></td> <td class="TableStyle-Borders-BodyD-Regular-Row1">This optional field can help determine the Bill-To Customer that is assigned to the site session when there is more than one <<product-name>> Bill-To Customers assigned to the given Username.</td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><...><ShipTo><Address addressID></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This optional, but highly encouraged element represents the Customer's ID for the Ship-To that will be attached to the Setup Request. This may be necessary to determine exact pricing and/or other site-level logic driven by the <<product-name>> Customer record assigned to the site session.</p> <p>There is a section in the <<product-name>> Management Console where the client maintains a PunchOut addressID to client's Ship-To mapping. The mapping tool will use the <<product-name>> Username (set in <Header><From><Credential><Identity>) and this addressID value to match to a single client's Customer record in <<product-name>> (that is the specific Bill-To and Ship-To combination).</p> <p>If an addressID value is not provided in the Setup Request, then <<product-name>> will set the site session to the Customer record attached to the User record in <<product-name>>.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyB-Regular-Row1"><p><...><SelectedItem><ItemID> <SupplierPartAuxiliaryID></p></td> <td class="TableStyle-Borders-BodyA-Regular-Row1"><p>This value will only be analyzed under an edit or inspect Setup Request. This value should be the <<product-name>> PunchOut Session ID that was attached to each line in PunchOut Order Messages sent from <<product-name>>. It helps the system tie back the PunchOut Setup Request (coming to <<product-name>> under the edit or inspect operation) to an existing cart that a User had already created in <<product-name>>.</p></td> </tr> </tbody> </table>
The \<SupplierSetup> node is listed to show that additional elements and data can be included in the Setup Request cXML. However, <<product-name>> will not use any of this additional data for any site function.
## PunchOut setup response
The PunchOut Setup Response is the signal back to the Customer that confirms the PunchOut Setup Request. If a successful result is returned, it indicates that <<product-name>> has a stored session ready for the user to go to. The URL that is included in the Setup Response contains a session code/GUID that will automatically log the Customer User into the site under the same <<product-name>> User provided in the '\<Header>\<From>\<Credential>\<Identity>' element of the PunchOut Setup Request. <<product-name>> Customer Bill-To & Ship-To records will also be provided to the site session using the Address ID or default logic assigned during the Setup Request.
The PunchOut Setup Response cXML should contain the following:
PunchOut Setup Request success/failure indicator
Site URL with session variable
### PunchOut setup response cXML
The following is a sample of a successful PunchOut Setup Response cXML:
The following are two samples of failed PunchOut Setup Response cXML messages:
### PunchOut setup response data mapping
Below are the specific definitions around important cXML elements/attributes:
<table class="TableStyle-Borders" style="margin-left: 0; margin-right: auto; width: 100%;" data-cellspacing="0"> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <thead> <tr class="header TableStyle-Borders-Head-Header1"> <th colspan="2" class="TableStyle-Borders-HeadD-Regular-Header1"><p>Field Mapping: PunchOut Setup Response cXML</p></th> </tr> <tr class="odd TableStyle-Borders-Head-Header1"> <th class="TableStyle-Borders-HeadE-Regular-Header1"><p>Element/Attribute</p></th> <th class="TableStyle-Borders-HeadD-Regular-Header1"><p>Use</p></th> </tr> </thead> <tbody> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Response><Status code></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>200 represents a successful status of the Setup Request</p> <p>500 represents a failure status of the Setup Request</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><Response><Status text></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>Provides the success/error message produced by the processing the Setup Request</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p><PunchoutSetupResponse></p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This node should only exist in a successful PunchOut Setup Response</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyB-Regular-Row1"><p><PunchoutSetupResponse><StartPage> <URL></p></td> <td class="TableStyle-Borders-BodyA-Regular-Row1"><p>The URL that the Customer should go to on the site. The URL should be the <<product-name>> site with the additional unique session code (that is GUID) that will result in the Customer User auto-logging into the site with the appropriate Customer set into the session.</p></td> </tr> </tbody> </table>