3. PunchOut setup request and response

8 min

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 {user["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 {user["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 {user["product-name"]} endpoint. The endpoint will be located as follows, with a separate endpoint available for each domain setup within the {user["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:

<?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 {user["product-name"]}:

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 `<>` 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 `<>` Username.
<Header><Sender><Credential><Identity>	Represents the system sending the Setup Request to `<>`. From a process perspective, it will represent the system sending the message to `<>` (such as Integration Partner). This value will need to tie back to the Username field on a User record in the `<>` platform.
<Header><Sender><Credential> <SharedSecret>	The `<>` password associated with the Username sent in the <Header><Sender><Credential><Identity> field. Technically used to validate that the Setup Request sent to `<>` 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 `<>` 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 `<>` Customer record assigned to the site session. There is a section in the `<>` Management Console where the client maintains a PunchOut addressID to client's Ship-To mapping. The mapping tool will use the `<>` Username (set in <Header><From><Credential><Identity>) and this addressID value to match to a single client's Customer record in `<>` (that is the specific Bill-To and Ship-To combination). If an addressID value is not provided in the Setup Request, then `<>` will set the site session to the Customer record attached to the User record in `<>`.
<...><SelectedItem><ItemID> <SupplierPartAuxiliaryID>	This value will only be analyzed under an edit or inspect Setup Request. This value should be the `<>` PunchOut Session ID that was attached to each line in PunchOut Order Messages sent from `<>`. It helps the system tie back the PunchOut Setup Request (coming to `<>` under the edit or inspect operation) to an existing cart that a User had already created in `<>`.

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

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