eMarketplace Punch-out (ERP to Unimarket)

  • Updated

Unimarket can be configured as a centralized eMarketplace that sits on top of your existing ERP system (such as Workday, PeopleSoft, Oracle, or TechnologyOne). In this setup, your ERP system treats Unimarket as a single Punchout (Roundtrip) destination.

 

Why Use a Marketplace Punchout?

The traditional method of integrating individual suppliers into an ERP is costly and inefficient. Each new supplier requires a separate firewall configuration, Punchout setup, and PO/Invoice integration.

 

Benefits of the Marketplace approach:

  • Single Integration: Access all your suppliers through one connection to Unimarket.

  • Lower Maintenance: Adding or changing suppliers requires no further technical integration on the ERP side.

  • Enhanced Security: Minimizes the number of "holes" in your corporate firewall by consolidating third-party traffic.

 

The Punchout Process

The integration adheres to the cXML standard, making it compatible with any ERP that supports cXML. Please click, to download a process overview of the punch-out process.

 

1. Punchout Setup Request

When a user clicks the Unimarket link in your ERP, the ERP sends a PunchOutSetupRequest. This message authenticates the session and identifies the user.

Key XML Requirements:

  • Sender Credentials: Contains the Identity and SharedSecret for authentication.

  • Extrinsics: Must include the user's email, first name, and last name to determine which Unimarket cart to use.

  • BrowserFormPost: The URL where Unimarket will post the cart data back to the ERP.

 

2. Punchout Cart Return (PunchOutOrderMessage)

Once the user finishes shopping in Unimarket, the marketplace sends a PunchOutOrderMessage back to the ERP. This "returns" the items to the ERP requisition.

Key Data Returned:

  • ItemDetail: Includes unit price, description, unit of measure, and UNSPSC classification.

  • SupplierID: Identifies which marketplace supplier the item belongs to.

  • BuyerCookie: Matches the return message to the original setup request session.

 

Setup and Testing

To successfully establish the "handshake" between your ERP and Unimarket:

  1. Retrieve Credentials: Log in to Unimarket and navigate to Edit Community > Integration to find your specific credentials.

  2. Configure ERP: Set the Identity, Shared Secret, and Punchout URL in your ERP's supplier maintenance module.

  3. Test the Connection: Use the Unimarket Roundtrip Tester to simulate a request and verify the XML structure.

 

Technical Resources

For full schema details and DTD definitions, refer to the following:

  • cXML User Guide: For deep-dives into message structures.

  • cXML.dtd: The official document type definition for message validation (link at the bottom of the screen).

 

Sample 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>


Sample 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>