Punchout
-
eMarketplace Punch-out (ERP to Unimarket)
Overview
Unimarket can be setup as an eMarketplace on top of an existing ERP system such as WorkDay, Peopesoft, Oracle or TechnologyOne. To do this the Unimarket Community is Configured as Punch-Out (Roundtrip) from the customers ERP system.
Why Setup Unimarket as an eMarketplace Punchout?
Traditionally when customers integrate suppliers into their ERP system they must go through the process of integrating each individual supplier separately to open the firewall and setup the Punchout, Purchase Order and Invoice integration. This results in a large amount of cost and effort each time a new supplier is added and the cost to change suppliers in the future is high and the number of holes in the customer firewall to third party integrations is a security risk.
Integrating to the Unimarket Marketplace provides customers with the ability to access all their suppliers through a single integration. The customer can then work with Unimarket to grow the supplier list and the cost to change between suppliers in the future is low as no further integration is required.
Please click below to download a process overview of the punch-out process.
Unimarket Marketplace Process.pdf
Punchout Setup Request Message
Below is an example of the Punch-out Setup Request message. Full details of all the messages (and examples) can be found below within the cXML User Guide. The messages adhere to the cXML standard and are compatible with any ERP that supports this standard.
Punchout Setup Request
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="payloadId" timestamp="2020-01-06T13:50:13+13:00" version="1.2" xml:lang="en">
<Header>
<From>
<Credential domain="DUNS">
<!-- 1. ENTER VALUE HERE used to get tenant for authentication based on Domain options for DUNS, Network ID or others -->
<Identity> 8 digit ID or other based on Domain </Identity>
</Credential>
</From>
<To>
<Credential domain="unimarket-code">
<Identity> 8 digit ID or other based on Domain </Identity>
</Credential>
</To>
<Sender>
<Credential domain="unimarket-user">
<!-- 2. ENTER VALUE HERE used to get username for authentication -->
<Identity>9520969d-e16b-46db-9d03-859874d883f6</Identity>
<!-- 3. ENTER VALUE HERE used to get password for authentication -->
<SharedSecret>password1</SharedSecret>
</Credential>
<UserAgent>Initiating System or ERP</UserAgent>
</Sender>
</Header>
<Request deploymentMode="production">
<PunchOutSetupRequest operation="create">
<BuyerCookie>Long UUID created for each session</BuyerCookie>
<!-- 4. ENTER VALUE HERE unimarket username (to determine whose cart should be used) -->
<Extrinsic name="User">john.doe@school.edu</Extrinsic>
<Extrinsic name="email">john.doe@school.edu</Extrinsic>
<Extrinsic name="FirstName">John</Extrinsic>
<Extrinsic name="LastName">Doe</Extrinsic>
<BrowserFormPost>
<URL>http://admin.unimarket-demo.com/roundtrip-tester-module/receive-cxml-cart.jsp</URL>
</BrowserFormPost>
</PunchOutSetupRequest>
</Request>
</cXML>
Punchout Cart Return (PunchOutOrderMessage)<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="payloadId" timestamp="2020-01-06T13:50:13+13:00" version="1.2" xml:lang="en">
<Header>
<From>
<Credential domain="DUNS">
<!-- 1. ENTER VALUE HERE used to get tenant for authentication based on Domain options for DUNS, Network ID or others -->
<Identity> 8 digit ID or other based on Domain </Identity>
</Credential>
</From>
<To>
<Credential domain="unimarket-code">
<Identity> 8 digit ID or other based on Domain </Identity>
</Credential>
</To>
<Sender>
<Credential domain="unimarket-user">
<!-- 2. ENTER VALUE HERE used to get username for authentication -->
<Identity>9520969d-e16b-46db-9d03-859874d883f6</Identity>
<!-- 3. ENTER VALUE HERE used to get password for authentication -->
<SharedSecret>password1</SharedSecret>
</Credential>
<UserAgent>Initiating System or ERP</UserAgent>
</Sender>
</Header>
<Message>
<PunchOutOrderMessage>
<BuyerCookie>a05918eb-556e-4269-a612-dffac9b8d30d</BuyerCookie>
<PunchOutOrderMessageHeader operationAllowed="create">
<Total>
<Money currency="USD">32.29</Money>
</Total>
<Shipping>
<Money currency="USD">0.00</Money>
<Description xml:lang="en">Standard Shipping</Description>
</Shipping>
</PunchOutOrderMessageHeader>
<ItemIn quantity="1">
<ItemID>
<SupplierPartID>LS1234</SupplierPartID>
<SupplierPartAuxiliaryID/>
<IdReference domain="unimarketProductId" identifier="Long UUID number"/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">32.29</Money>
</UnitPrice>
<Description xml:lang="en">Product Text Description</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">49161506</Classification>
</ItemDetail>
<SupplierID domain="SupplierNumber">BSHC</SupplierID>
</ItemIn>
</PunchOutOrderMessage>
</Message>
</cXML>
Technical Information
For more technical information on integrating with Unimarket please see:
This documentation should be read in conjunction with the following:
Testing the Punchout from an ERP to Unimarket
The credentials in the external application should be set to those displayed within your Unimarket Community under Edit Community / Integration.The punch-out to Unimarket can then be tested using the following tool:
https://akl-office.unimarket.co.nz:7443/roundtrip-tester/
-
ERP Punchout to Unimarket (Technical Information)
Overview
The Punchout process is made up of three parts:
Punchout Setup Request
Punchout Setup Response
Punchout Order Message
Here’s how the process will take place behind the scenes.
- The Punchout Setup Request is a cXML request that is sent from the ERP system requesting a punchout session with Unimarket. Included in this is information to identify which community this punchout request is for, authorization, details about the user and the Browser Form Post URL.
- Once Unimarket authenticates the request, it will create a session and send the Punchout Setup Response.
- The key piece of information in the response will be the Start Page which is the URL to direct the user to.
- The user will be able to shop as normal on the Unimarket site and at the return the shopping cart back to their ERP.
- This is done by Unimarket sending a Punchout Order Message to the Browser Form Post URL from the initial Punchout Setup Request.
Punchout Setup Request
The Punchout Setup Request will need to be sent as an HTTPS POST request specific to each Community.
The key pieces of information in this request will be:
The Community ID: cb897379-12df-4a5f-ab87-05709517f44b
The System User: 5cd5ed4c-09c3-4c51-871d-3cde84e09556
The System Password: SuperSecretPasswordHere
The Buyer Username: TestPunchoutUser
The BrowserFormPost: https://your.procurement.system.com
Example URL:
https://miketest.unimarket-demo.com/ws
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="payloadId" timestamp="2009-11-06T13:50:13+13:00" version="1.2" xml:lang="en">
<Header>
<From>
<Credential domain="unimarket-id">
<Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
</Credential>
</From>
<To>
<Credential domain="unimarket-id">
<Identity/>
</Credential>
</To>
<Sender>
<Credential domain="unimarket-user">
<Identity>5cd5ed4c-09c3-4c51-871d-3cde84e09556</Identity>
<SharedSecret>SuperSecretPasswordHere</SharedSecret>
</Credential>
<UserAgent>Unimarket Testing System.</UserAgent>
</Sender>
</Header>
<Request deploymentMode="production">
<PunchOutSetupRequest operation="create">
<BuyerCookie>NA</BuyerCookie>
<Extrinsic name="User">TestPunchoutUser</Extrinsic>
<BrowserFormPost>
<URL>https://your.procurement.system.com</URL>
</BrowserFormPost>
</PunchOutSetupRequest>
</Request>
</cXML>Punchout Setup Response
The Punchout Setup Response is the response to the HTTPS POST request sent from the Agency community.
The key piece of information in this response will be:
StartPage URL: https://miketest.unimarket-demo.com/app/home?cid=c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d
This URL is what should be opened for the user in their browser which will take them to an authenticated home page within Unimarket.
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d" timestamp="2020-05-01T13:42:04.601 12:00" version="1.2.038" xml:lang="en">
<Response>
<Status code="200" text="success"/>
<PunchOutSetupResponse>
<StartPage>
<URL>https://miketest.unimarket-demo.com/app/home?cid=c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d</URL>
</StartPage>
</PunchOutSetupResponse>
</Response>
</cXML>Punchout Order Message
Unimarket will redirect the buyer's browser back to the BrowserFormPost URL specified in the original PunchOutSetupRequest message.
The redirect will include a POST parameter named cxml-urlencoded, which will be a URL encoded version of the cXML PunchOutOrderMessage message, containing the details of the items in the buyer's cart. This will need to be URL decoded and the resulting XML parsed.
Example Punchout Order Message (URLencoded):
cxml-urlencoded: %3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%0D%0A%3C%21DOCTYPE+cXML%0D%0A++SYSTEM+%22http%3A%2F%2Fxml.cXML.org%2Fschemas%2FcXML%2F1.2.021%2FcXML.dtd%22%3E%0D%0A%3CcXML+payloadID%3D%22c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d%22+timestamp%3D%222020-05-01T13%3A42%3A52.536%2B12%3A00%22+version%3D%221.2.021%22+xml%3Alang%3D%22en%22%3E%3CHeader%3E%3CFrom%3E%3CCredential+domain%3D%22unimarket-id%22%3E%3CIdentity%3Ecb897379-12df-4a5f-ab87-05709517f44b%3C%2FIdentity%3E%3C%2FCredential%3E%3C%2FFrom%3E%3CTo%3E%3CCredential+domain%3D%22unimarket-id%22%3E%3CIdentity%2F%3E%3C%2FCredential%3E%3C%2FTo%3E%3CSender%3E%3CCredential+domain%3D%22unimarket-id%22%3E%3CIdentity%3Ecb897379-12df-4a5f-ab87-05709517f44b%3C%2FIdentity%3E%3CSharedSecret%3ESuperSecretPasswordHere%3C%2FSharedSecret%3E%3C%2FCredential%3E%3CUserAgent%3EUMKT%3C%2FUserAgent%3E%3C%2FSender%3E%3C%2FHeader%3E%3CMessage%3E%3CPunchOutOrderMessage%3E%3CBuyerCookie%3ENA%3C%2FBuyerCookie%3E%3CPunchOutOrderMessageHeader+operationAllowed%3D%22create%22%3E%3CTotal%3E%3CMoney+currency%3D%22NZD%22%3E4.00%3C%2FMoney%3E%3C%2FTotal%3E%3CShipping%3E%3CMoney+currency%3D%22NZD%22%3E20.00%3C%2FMoney%3E%3CDescription+xml%3Alang%3D%22en%22%3E%2420.00+per+order%3C%2FDescription%3E%3C%2FShipping%3E%3C%2FPunchOutOrderMessageHeader%3E%3CItemIn+quantity%3D%224%22%3E%3CItemID%3E%3CSupplierPartID%3E1000010%3C%2FSupplierPartID%3E%3CSupplierPartAuxiliaryID%2F%3E%3CIdReference+domain%3D%22unimarketProductId%22+identifier%3D%22ca1be02d-60f2-47ce-9090-1add34657995%22%2F%3E%3C%2FItemID%3E%3CItemDetail%3E%3CUnitPrice%3E%3CMoney+currency%3D%22NZD%22%3E1.00%3C%2FMoney%3E%3C%2FUnitPrice%3E%3CDescription+xml%3Alang%3D%22en%22%3EProduct+Code+10%3C%2FDescription%3E%3CUnitOfMeasure%3EEA%3C%2FUnitOfMeasure%3E%3CClassification+domain%3D%22UNSPSC%22%3E44000000%3C%2FClassification%3E%3C%2FItemDetail%3E%3CSupplierID+domain%3D%22DUNS%22%2F%3E%3C%2FItemIn%3E%3C%2FPunchOutOrderMessage%3E%3C%2FMessage%3E%3C%2FcXML%3E
Example Punchout Order Message (Decoded to XML):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.021/cXML.dtd">
<cXML payloadID="c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d" timestamp="2020-05-01T13:42:52.536+12:00" version="1.2.021" xml:lang="en">
<Header>
<From>
<Credential domain="unimarket-id">
<Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
</Credential>
</From>
<To>
<Credential domain="unimarket-id">
<Identity/>
</Credential>
</To>
<Sender>
<Credential domain="unimarket-id">
<Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
<SharedSecret>SuperSecretPasswordHere</SharedSecret>
</Credential>
<UserAgent>UMKT</UserAgent>
</Sender>
</Header>
<Message>
<PunchOutOrderMessage>
<BuyerCookie>NA</BuyerCookie>
<PunchOutOrderMessageHeader operationAllowed="create">
<Total>
<Money currency="NZD">4.00</Money>
</Total>
<Shipping>
<Money currency="NZD">20.00</Money>
<Description xml:lang="en">$20.00 per order</Description>
</Shipping>
</PunchOutOrderMessageHeader>
<ItemIn quantity="4">
<ItemID>
<SupplierPartID>1000010</SupplierPartID>
<SupplierPartAuxiliaryID/>
<IdReference domain="unimarketProductId" identifier="ca1be02d-60f2-47ce-9090-1add34657995"/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
</ItemDetail>
<SupplierID domain="DUNS"/>
</ItemIn>
</PunchOutOrderMessage>
</Message>
</cXML>