PunchOut setup request and response
This is article three in a series of five articles:
- PunchOut/cXML Process and Design Overview
- PunchOut/cXML Configuration and Data Requirements
- PunchOut Setup Request and Response - Current Article
- 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 B2B 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 Optimizely B2B Commerce 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, Optimizely 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 an B2B endpoint. The endpoint will be located as follows, with a separate endpoint available for each domain setup within the B2B platform:
- 4.4: https://<DOMAIN>/punchout/punchoutsetuprequest.isch
- 4.5: https://<DOMAIN>/api/v1/punchout/setuprequest
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:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.008/cXML.dtd">
<cXML payloadID="2013-09-09T10:57:28-05:[email protected]" timestamp="2013-09-09T10:57:28-05:00" xml:lang="en-US">
<Header>
<From>
<Credential domain="NetworkId">
<Identity>PunchOutCustomer_ISCUserName</Identity>
</Credential>
</From>
<To>
<Credential domain="DUNS">
<Identity>ClientName</Identity>
</Credential>
</To>
<Sender>
<Credential domain="UserSiteNetworkUserId">
<Identity>IntegrationPartner_ISCUserName</Identity>
<SharedSecret>IntegrationPartner_ISCPassword</SharedSecret>
</Credential>
<UserAgent>IntegrationPartner</UserAgent>
</Sender>
</Header>
<Request deploymentMode="test">
<PunchOutSetupRequest operation="create">
<BuyerCookie>{A4FC3513-F7B4-41AC-B904-5A3449022CAC}</BuyerCookie>
<Extrinsic name="User"></Extrinsic>
<BrowserFormPost>
<URL>https://www.integrationpartner.com/ClientName/receivepunchoutquote.asp</URL>
</BrowserFormPost>
<ShipTo>
<Address addressID="ShipToNumber"></Address>
</ShipTo>
<Contact role="endUser">
<Name xml:lang="en"></Name>
<Email></Email>
</Contact>
<SupplierSetup>
<URL>https://www.integrationpartner.com/ClientName/punchoutsetup.asp</URL>
</SupplierSetup>
<SelectedItem>
<ItemID>
<SupplierPartID>AAA</SupplierPartID>
<SupplierPartAuxiliaryID>ISCPunchOutSessionId</SupplierPartAuxiliaryID>
</ItemID>
</SelectedItem>
</PunchOutSetupRequest>
</Request>
</cXML>
PunchOut setup request data mapping
Below are the specific definitions around important cXML elements/attributes and their use by ISC:
Element/Attribute |
Use |
---|---|
<Header><From><Credential><Identity> |
Represents the Customer from which the Setup Request originated. From a business perspective, it will correlate with a client's Bill-To customer. This value will need to tie back to the Username field on a User record in the B2B platform. This Username will only be used for PunchOut access. |
<Header><To><Credential><Identity> |
Represents the Client to which the Setup Request is sent. This should be the client's name, and does NOT tie back to an B2B Username. |
<Header><Sender><Credential><Identity> |
Represents the system sending the Setup Request to ISC. From a process perspective, it will represent the system sending the message to B2B (such as Integration Partner). This value will need to tie back to the Username field on a User record in the B2B platform. |
<Header><Sender><Credential> <SharedSecret> |
The B2B password associated with the Username sent in the <Header><Sender><Credential><Identity> field. Technically used to validate that the Setup Request sent to B2B is from a valid source. |
<Header><Sender><UserAgent> |
The application sending the Setup Request. |
<Request><PunchoutSetupRequest> |
This node needs to exist to validate the cXML function is for a Setup Request |
<Request><PunchoutSetupRequest operation> |
This value will be "create", "edit" or "inspect", depending on the reason for the Setup Request. |
<...> <BuyerCookie> |
The data that allows the Customer's Procurement System to tie together multiple outstanding PunchOut requests. |
<...> <BrowserFormPost> |
The URL provided here will be the location where the PunchOut Order Message will be sent. |
<...><BillTo><Address addressID> | This optional field can help determine the Bill-To Customer that is assigned to the site session when there is more than one B2B Bill-To Customers assigned to the given Username. |
<...><ShipTo><Address addressID> |
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 B2B Customer record assigned to the site session. There is a section in the B2B Management Console where the client maintains a PunchOut addressID to client's Ship-To mapping. The mapping tool will use the B2B Username (set in <Header><From><Credential><Identity>) and this addressID value to match to a single client's Customer record in B2B (that is the specific Bill-To and Ship-To combination). If an addressID value is not provided in the Setup Request, then B2B will set the site session to the B2B Customer record attached to the User record in ISC. |
<...><SelectedItem><ItemID> <SupplierPartAuxiliaryID> |
This value will only be analyzed under an edit or inspect Setup Request. This value should be the B2B PunchOut Session ID that was attached to each line in PunchOut Order Messages sent from ISC. It helps the system tie back the PunchOut Setup Request (coming to B2B under the edit or inspect operation) to an existing cart that a User had already created in ISC. |
The <SupplierSetup> node is listed to show that additional elements and data can be included in the Setup Request cXML. However, B2B 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 B2B 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 B2B User provided in the '<Header><From><Credential><Identity>' element of the PunchOut Setup Request. B2B 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:
<?xml version="1.0" encoding="utf-16"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="[email protected]" timestamp="2013-09-09T14:57:35-05:00">
<Response>
<Status code="200" text="success" />
<PunchoutSetupResponse>
<StartPage>
<URL>https://www.ClientSite.com/Punchout/
punchoutsessionrequest.isch?ps=e82d0d33-9fee-45fe-9d87-a23400a4218d</URL>
</StartPage>
</PunchoutSetupResponse>
</Response>
</cXML>
The following are two samples of failed PunchOut Setup Response cXML messages:
<?xml version="1.0" encoding="utf-16"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="[email protected]" timestamp="2013-03-19T19:25:35-05:00">
<Response>
<Status code="500" text="The incoming cXml is not in a known format" />
</Response>
</cXML>
<?xml version="1.0" encoding="utf-16"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="[email protected]" timestamp="2013-09-06T16:14:29-05:00">
<Response>
<Status code="500" text="PunchOut Credentials are not valid " />
</Response>
</cXML>
PunchOut setup response data mapping
Below are the specific definitions around important cXML elements/attributes:
Element/Attribute |
Use |
---|---|
<Response><Status code> |
200 represents a successful status of the Setup Request 500 represents a failure status of the Setup Request |
<Response><Status text> |
Provides the success/error message produced by the processing the Setup Request |
<PunchoutSetupResponse> |
This node should only exist in a successful PunchOut Setup Response |
<PunchoutSetupResponse><StartPage> <URL> |
The URL that the Customer should go to on the site. The URL should be the B2B 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. |