PunchOut setup request and response

This is article three in a series of five articles:

1. PunchOut/cXML Process and Design Overview
2. PunchOut/cXML Configuration and Data Requirements
3. PunchOut Setup Request and Response - Current Article
4. PunchOut Order Message (that is Cart Information)
5. 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 ISC 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.

The Integration Partner will translate the Customer's PunchOut Setup Request message into Insite's standard cXML format and POST that cXML to an ISC endpoint. The endpoint will be located as follows, with a separate endpoint available for each domain setup within the ISC 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:

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

Field Mapping: PunchOut Setup Request cXML
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 ISC 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 ISC 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 ISC (such as Integration Partner). This value will need to tie back to the Username field on a User record in the ISC platform.
<Header><Sender><Credential> <SharedSecret>	The ISC password associated with the Username sent in the <Header><Sender><Credential><Identity> field. Technically used to validate that the Setup Request sent to ISC 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 ISC 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 ISC Customer record assigned to the site session. There is a section in the ISC Management Console where the client maintains a PunchOut addressID to client's Ship-To mapping. The mapping tool will use the ISC Username (set in <Header><From><Credential><Identity>) and this addressID value to match to a single client's Customer record in ISC (that is the specific Bill-To and Ship-To combination). If an addressID value is not provided in the Setup Request, then ISC will set the site session to the ISC 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 ISC 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 ISC 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, ISC 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 ISC 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 ISC User provided in the '<Header><From><Credential><Identity>' element of the PunchOut Setup Request. ISC 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:

Field Mapping: PunchOut Setup Response cXML
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 ISC 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.