Concept - cXML Punchout



1 Introduction

Info

This concept is valid for ICM version 7.10.31 and higher.

With the cXML Punchout feature the Commerce Management application offers an external interface (cXML) for B2B customers, so that external systems can access product data via REST calls. Therefore, the cXML transfer format is utilized.

The cXML Punchout is accessible via REST calls, many of which are already used by the PWA, the Intershop REST-Client.

cXML-punchout-schema

1.1 Glossary

TermDescription
cXML Commerce eXtensible Markup Language Protocol or Commerce XML  used by ERP/Purchasing Systems when connecting to external Punchout catalogs.
ICMIntershop Commerce Management
SMCSystem Management Console

1.2 References

The following documentation is related to the cXML Punchout feature:

1.3 Features

To understand cXML Punchout, a list of features is given below.

For more detailed information on the REST calls, refer to Reference - Punchout API 2.1.0

1.3.1 User Management Features

FeatureDescription
List Punchout UsersShows all customer-specifc and Punchout-specific users (/punchouts/cxml1.2/users)
User CreationAccount admins can create Punchout users.
Edit UserAccount admins may update a Punchout user's e-mail or password and set them to active/inactive.
Delete UserAccount admins can delete a Punchout user.

1.3.2 General cXML Features

An external (procurement) system can log on as cXML Punchout user onto an Intershop Commerce Management system with REST. This feature is already supported by the Intershop PWA storefront. The user can then browse the storefront, add products to the cart and transfer a cart back to the caller (initially identified by the BrowserFormPost URL in the setup request).

FeatureDescription
cXML catalog browsingInitial step to open a cXML session (/punchouts/cxml1.2/setuprequest)
cXML TransferTriggers the transfer of a basket to a previously defined URL (/punchouts/cxml1.2/transfer)
cXML order injectionIt allows to create an order in the Intershop Commerce Management system. See Concept and Cookbook for details on how this works.

2 Functionality

This chapter describes technical insights of the cXML Punchout implementation in ICM.

For every outbound connection from the external system into the Intershop system a new basket is created. The lifetime of the basket is limited to the session. Therefore, every cXML Punchout connection, even with the same user, creates a new session including an empty basket. Usually only a single cXML Punchout user per customer is configured, which is then used for multiple employees in the connected external system. A customer account administrator can configure one or more cXML Punchout users via REST API.

2.1 cXML Punchout Catalog Browsing

Browsing and logging in is possible with a valid cXML session ID via REST. A cXML Punchout user can perform most actions of a standard Buyer like search and add products to a shopping cart which can be transferred back to a referenced (procurement) system (see BrowserFormPost URL).

The Intershop PWA allows to log on to the storefront as cXML Punchout user. Afterwards a reduced storefront (e.g., no footer) is available.

2.1.1 Login URL

The cXML Punchout URL of an ICM system should be publicly available, so that any cXML Punchout user with valid credentials can access it. The pattern of the URL is described below:

URL pattern
https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/setuprequest

The following parameters contained in this XML are required in the cXML PunchOutSetupRequest body to access the cXML Punchout PWA storefront for browsing:

PunchOutSetupRequest example data
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.041/cXML.dtd">
<cXML xml:lang="en-US" payloadID="933695160894" timestamp="2002-08-15T08:47:00-07:00">
  <Header>
    <From>
      <Credential domain="NetworkId">
        <Identity>OilCorp</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="DUNS">
        <Identity>inTRONICS_Business</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="NetworkId">
        <Identity>cxml_demo_user@test.intershop.de</Identity>
        <SharedSecret>!InterShop00!</SharedSecret>
      </Credential>
      <UserAgent>SomeUserAgent</UserAgent>
    </Sender>
  </Header>
  <Request deploymentMode="production">
    <PunchOutSetupRequest operation="create">
      <BrowserFormPost>
        <URL>https://{procurement-url}/punchout/cxml/%7B07F11422-C45F-B9E7-D312-E6F86929DBE4%7D</URL>
      </BrowserFormPost>
      <SupplierSetup>
        <URL>https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/setuprequest</URL>
      </SupplierSetup>
      <ShipTo>
        <Address addressID="TEST">
          <Name xml:lang="en">TEST</Name>
          <PostalAddress>
            <Street>123 Street Address</Street>
            <City>Rockville</City>
            <State>MD</State>
            <PostalCode>20850</PostalCode>
            <Country isoCountryCode="US">US</Country>
          </PostalAddress>
        </Address>
      </ShipTo>
    </PunchOutSetupRequest>
  </Request>
</cXML>


ParameterDescription

<Sender><Credential ...> <Identity>

Login name of a storefront user with the role cXML Punchout user, e.g.: test_cxml_user
<Sender><Credential ...> <SharedSecret>Password of the cXML Punchout user

<BrowserFormPost> <URL>

Transfer the cXML Punchout data back to this URL. Usually a reference to the calling, external (procurement) system,

e.g.: https://{procurement-url}/punchout/cxml/%7B07F11422-C45F-B9E7-D312-E6F86929DBE4%7D

<SupplierSetup> <URL>

The URL of the system which provides the Punchout catalog via cXML,

e.g.: https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/setuprequest

2.2 cXML Transfer Format

The cXML data is transferred using the cXML format. See cXML Reference Guide Version 1.2.050 [PDF - 4.009 KB] for details.

Example Response
<?xml version="1.0"?><!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="933695160894" timestamp="2021-06-10T08:47:00-07:00">
 <Header>
  <From>
   <Credential domain="DUNS">
    <Identity>83528721</Identity>
   </Credential>
  </From>
  <To>
   <Credential domain="DUNS">
    <Identity>65652314</Identity>
   </Credential>
  </To>
  <Sender>
   <Credential domain="inSPIRED">
    <Identity>inTRONICS_Business</Identity>
   </Credential>
   <UserAgent>any cXML Application</UserAgent>
  </Sender>
 </Header>
 <Message>
 <PunchOutOrderMessage>
  <BuyerCookie>1CX3L4843PPZO</BuyerCookie>
  <PunchOutOrderMessageHeader operationAllowed="edit">
   <Total>
    <Money currency="USD">763.20</Money>
   </Total>
  </PunchOutOrderMessageHeader>
  <ItemIn quantity="1">
   <ItemID>
    <SupplierPartID>5555</SupplierPartID>
    <SupplierPartAuxiliaryID>E000028901</SupplierPartAuxiliaryID>
   </ItemID>
   <ItemDetail>
    <UnitPrice>
     <Money currency="USD">763.20</Money>
    </UnitPrice>
    <Description xml:lang="en"><ShortName>Excelsior Desk Chair</ShortName>Leather Reclining Desk Chair with Padded Arms</Description>
    <UnitOfMeasure>EA</UnitOfMeasure>
    <Classification domain="UNSPSC">5136030000</Classification>
    <LeadTime>12</LeadTime>
   </ItemDetail>
  </ItemIn>
 </PunchOutOrderMessage>
 </Message>
</cXML>


2.3 cXML Order Injection

The cXML order injection allows to create an actual order based on the transferred basket data. This can be data from a basket previously created with a cXML Punchout or your own data.

See details in cXML order injection documentation Concept and Cookbook.

3 Localized Name, Description and Unit Mapping



ICM Version

This concept is valid from ICM version 7.10.35.0.

3.1 Introduction

In the first implementation of cXML Punchout and order injection (ICM 7.10.31), the configuration of data like unit mapping and locale configuration were limited.

The newly introduced UserPreference table allows now to store user specific cXML configuration data, like the unit mapping and locale.

The unit mapping converts procurement system units like box or piece etc. to units used in ICM and vice versa.

For both a global configuration can be stored in properties.

The UserPreference table data allows to customize those values per user aka cXMLUser. (see references documents for details)

3.1.1 Glossary

cXML - is a standard for Punchout similar to OCI. Besides the Punchout to an external B2B store, it also supports an order injection with basket data.

3.2 References

Concept - UserPreference table

Overview - Punchout - is the starting page for all ISH documents related to Punchout with cXML and OCI

Concept - Dependency Injection and ObjectGraphs

3.3 The CXMLPunchoutConfigurationProvider

This provider is used to supply the configurations for the global or user specific locale and the unit mapping. It is used for both, the cXML punchout basket and the cXML order injection.

The provider currently has two methods:

configuration provider methods
Map<String, String> getUnitMappings(UserBO userBO); 
LocaleInformation getPunchoutLocale(UserBO userBO);

They both have a hierarchy from which source the configuration is retrieved. The details are described in the next chapters for locale and unit mapping.

  • In case the hierarchy logic or the source of the configuration must be different in a customized project, it can be replaced.
  • Replaced by implementing your own customCXMLPunchoutConfigurationProviderImpl and use Guice to wire it to the interface.

3.4 Locale for Product Texts

  • The locale configuration is used for localized product texts when transferring the punchout basket.

  • It is possible to create a property with key "intershop.cxml.punchout.locale" to define a "global" configuration.

  • It is also possible to create a preference in table UserPreferences with name "punchout.locale" and group "cxml" to define a user specific configuration.

3.4.1 Hierarchy

The hierarchy or priority for the locale is as follows:

  1. The user specific preference stored with the given user.

  2. The 'global' configuration stored in a property, read via ConfigurationMgr.

  3. The locale stored for the current application.

  4. The system wide lead locale.

3.5 Unit Mapping

  • The unit mapping is used for both, punchout and order injection.

  • It converts units available in the calling Procurement system to units available in ICM and vice versa.

  • It is possible to create a property with key prefix "intershop.cxml.unitmapping" to define "global" mapping configurations.

    • example: intershop.cxml.unitmapping.EA=pcs  or  intershop.cxml.unitmapping.BX=Box  etc.

  • It is also possible to create a preference in table UserPreferences with name "unitmapping" and group "cxml" to define a user specific mapping configuration.

    • Here the configuration data is expected to be stored in one line.

    • The key and values are separated by a ':', the different groups(key-value-pairs) are separated by a '\t' tabulator character.

    • example stringValue: EACH;pcs   BOX;box   DOZ;DOZEN

    • Any configuration which doesn't fit the pattern, will be printed out as a warn log message and ignored for processing!

3.5.1 Hierarchy

The unit mapping actually used in the REST calls, can come from user specific preference configurations, from a global property configurations and a combination of both.

The hierarchy or priority for the unit-mapping is as follows:

  1. The user specific preference stored with the given user.

    • it overwrites/replaces any aleady existing global values and adds not existing user configurations

  2. The 'global' configuration stored in properties, read via ConfigurationMgr.

Examples:

key

user value

global value

value used for mapping

EA

stück

pcs

stück

BOX

box


box

DOZ


dozen

dozen

  • It is possible to use a global configuration and just replace the few specific to the user.

  • To use only user specific configuration, by not creating a global configuration with properties.

  • Or use only global configuration with properties, by not having an user specific data.

4 Architecture

The following artifacts are of interest when developing in the area of Punchout.

4.1 Cartridges

The following cartridges contain code artifacts:

CartridgeDescription
bc_punchoutCode to retrieve basic cXML Punchout-related data.
bc_punchout_cxmlIncludes generated cXML Java classes, and some basic functionality.
app_sf_rest_b2b_punchoutPunchout WebShop REST API
ac_cxml_order_injectionPunchout Order Injection REST API (Concept & Cookbook)
init_b2bRoles and permissions

4.2 Roles and Permissions

For cXML Punchout a new role and new permissions have been introduced.

Role

Description

APP_B2B_CXML_USER

The B2B cXML user.

New permissions for the role:

Permission

Description

APP_B2B_SEND_CXML_BASKET

Permission to allow transferring cXML baskets. This permission is assigned to the new role APP_B2B_CXML_USER.

APP_B2B_SEND_PUNCHOUT_BASKETPermission to send Punchout basket using any Punchout standard, currently OCI and CXML. This permission is assigned to the new role APP_B2B_CXML_USER and the APP_B2B_OCI_USER.

The Punchout user may have Punchout standard-specific roles. Currently in the punchoutconfiguration.properties the APP_B2B_CXML_USER is set for the cXML Punchout.

The cXML user has limited access to storefront functionality such as quotes. Therefore, the storefront user's role is checked.

4.3 Configuration

A Punchout standard can be configured in the punchoutconfiguration.properties (see bc_punchout). The Punchout user roles and also individual fields can be specified via Punchout standard here.

The cXML standard, however, has only a configured role in the property file. Any other configuration is not configured in this property file.

4.3.1 Punchout Standard

Currently the Intershop Commerce Management system comes with the OCI Punchout standard, and as of 7.10.31 with the cXML Punchout standard as well.

Punchout standard
# e.g., punchout.configuration.standards=oci,<punchout-type>
punchout.configuration.standard=oci,cxml

4.3.2 Punchout-Specific User Roles

For the existing cXML Punchout standard the default Intershop Commerce Mangement system has the role APP_B2B_CXML_USER set for specific Punchout users.

Punchout-specific user roles
# Define the users related to a given punchout type
# e.g., <punchout-standard>.users.roles=<my-custom-role>,<another-custom-role>
cxml.users.roles=APP_B2B_CXML_USER

5 REST API

The Punchout feature is implemented and documented as part of the REST API documentation, see Reference - Punchout API 2.1.0 or access it via Intershop System Management, see Cookbook - Developer Tools ac_swagger | Recipe: Show API Documentation for details.

The following use cases are supported:

  • Show list of Punchout standards
  • Show/create/delete Punchout users
  • Set Punchout user e-mail and password
  • Activate/deactivate single Punchout users
  • Setup Request
  • Transfer Basket

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets