3. PunchOut setup request and response

This is article three in a series of five articles:

1. PunchOut/cXML process and design
2. PunchOut/cXML configuration and data requirements
3. PunchOut setup request and response
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 Configured Commerce 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 Configured 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, 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 Configured Commerce endpoint. The endpoint will be located as follows, with a separate endpoint available for each domain setup within the Configured Commerce 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 Configured Commerce:

The <SupplierSetup> node is listed to show that additional elements and data can be included in the Setup Request cXML. However, Configured Commerce 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 Configured Commerce 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 Configured Commerce User provided in the '<Header><From><Credential><Identity>' element of the PunchOut Setup Request. Configured Commerce 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: