Introduction

With the cXML Punchout feature, Intershop Commerce Management (ICM) provides an external interface (cXML) for B2B customers, so that procurement systems can access product data directly. Therefore, the cXML transfer format is utilized.
ICM provides several REST endpoints to support cXML Punchout. The Intershop Progressive Web App (PWA) uses these endpoints to provide a proper cXML Punchout end to end process.

The following figure shows an overview of the general process. A more detailed workflow plan can be found in section cXML Punchout Catalog Browsing.

Glossary

References

The following documentation is related to the cXML Punchout feature:

• Reference - Punchout REST API 2.2.0 (ICM 7.10)

• Concept - cXML Order Injection - Basic concepts, cXML Punchout functionality via REST calls

• Cookbook - cXML Order Injection - Recipes on frequently asked questions and possible modifications

• Concept - Order Creation | Basic Handler Chain Framework

• Cookbook - Order Creation

• cXML - Standard - Documentation Site

Features

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

For more detailed information on the REST calls, refer to Reference - Punchout REST API 2.2.0 (ICM 7.10). 

User Management Features

General cXML Features

An external (procurement) system can log on as a 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 the cart back to the caller (initially identified by the BrowserFormPostURL in the setup request).

cXML Punchout Catalog Browsing

This chapter describes technical insights of the cXML Punchout implementation in ICM (except cXML Order Injection).

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 Punchout 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.

The following picture shows the detailed overall process of a cXML punchout session.

The cXML Punchout Catalog Browsing is a two-step process. First of all, the PunchoutSetupRequest initiates a new Punchout session and validates the provided cXML user credentials. When the checks are successful, a Punchout session ID is returned.

Afterwards, the second step - Catalog Browsing (Shopping Experience Browsing) - starts automatically. The Intershop PWA allows you to log on to the storefront as a cXML Punchout user. Afterwards, a reduced storefront (e.g., less visual elements (no footer, etc.), missing functionality like quoting, wish list, etc.) is available. A cXML Punchout user can perform most actions of a standard buyer, such as searching and adding products to a shopping cart that can be transferred back to a referenced procurement system (see BrowserFormPostURL) at the end.

The parts will now be explained with example responses.

PunchoutSetupRequest

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

URL

The pattern of the URL is described below.

URL pattern

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

Request

Depending on the procurement system, the cXML data sent by a PunchoutSetupRequest may look different. The following example contains only the minimal data set that is required to access the cXML Punchout PWA storefront for browsing:

PunchOutSetupRequest example data

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.041/cXML.dtd">
<cXML payloadID="1539050765.0492@example.com" timestamp="2018-10-09T02:06:05+00:00">
  <Header>
    <Sender>
      <Credential domain="NetworkId">
        <Identity>cxmluser@test.intershop.de</Identity>
        <SharedSecret>!InterShop00!</SharedSecret>
      </Credential>
    </Sender>
  </Header>
  <Request>
    <PunchOutSetupRequest>
        <BrowserFormPost>
            <URL>https://{procurement-url}/punchout/cxml/%7B07F11422-C45F-B9E7-D312-E6F86929DBE4%7D</URL>
        </BrowserFormPost>      
    </PunchOutSetupRequest>
  </Request>
</cXML>

Response

The response to a PunchoutSetupRequest can either be a failure or a success. The HTTP response code is always 200, for failure as well as for success. Only the response content differs.

If the PunchoutSetupRequest does not contain all required data, such as the BrowserFormPost URL, the following response is returned:

Example Response SetupRequest Failure Bad Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.049/cXML.dtd">
<cXML xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" xmlns:ns3="http://uri.etsi.org/01903/v1.3.2#">
    <Response>
        <Status code="400" text="Bad Request (Missing browser form post URL)"/>
    </Response>
</cXML>

If the cXML Punchout user does not exist or the credentials are not correct, the following response is returned:

Example Response SetupRequest Failure Unauthorized

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.049/cXML.dtd">
<cXML xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" xmlns:ns3="http://uri.etsi.org/01903/v1.3.2#">
    <Response>
        <Status code="401" text="Unauthorized"/>
    </Response>
</cXML>

A response body for a successfully created session only contains a URL pointing to the PWA storefront (StartPage) with a Punchout session ID and an access-token as parameters.

Example Response SetupRequest Success

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.049/cXML.dtd">
<cXML xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" xmlns:ns3="http://uri.etsi.org/01903/v1.3.2#">
    <Response>
        <Status code="200" text="OK"/>
        <PunchOutSetupResponse>
            <StartPage>
                <URL>http://localhost:4200/punchout?sid=71wKAB2GNRwAAAF8iuw5eDsy&access-token=encryption0%40PLAIN%3ALQBahs154Vc%3D%7CTG53S0FCMkd2Y3dBQUFGOC52OGpLQmViQDE2MzMwODA3NjU1NzdASUQ%3D</URL>
            </StartPage>
        </PunchOutSetupResponse>
    </Response>
</cXML>

The returned PWA URL is the External Base URL maintained in the Progressive Web App application properties (tab General) in ICM.

The Punchout session ID (sid) is required to retrieve details for the session and to transfer the Punchout basket back to the procurement system.
The access-token is required to authorize all subsequent REST requests (header "authentication-token").

cXML Punchout Session

The created cXML Punchout session is persisted until the cXML basket transfer has been executed. The successful cXML basket transfer will automatically dismiss the cXML Punchout session.

In case the cXML basket transfer is not executed, the cXML Punchout session will be available until the created basket becomes "invalid" and the Job - Cleanup Outdated cXML Punchout Sessions has been executed.
The Punchout basket is a standard basket that is automatically moved to the history and later set to invalid after a certain time (configurable).

During the lifetime of a cXML Punchout session, it is possible to retrieve all necessary information contained in the PunchoutSetupRequest using the session ID (sid) and the access-token.

URL

URL pattern

GET https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/sessions/<sid>

Headers: "authentication-token" = <access-token>

Response

If the session ID is valid, the response contains relevant information for the Punchout session. Passwords (SharedSecrets) are not stored and not returned. Fields with null values are not part of the PunchoutSetupRequest.

Session details

{
    "operation": null,
    "basketId": "xv8KAB2GjBgAAAF8h4o5eDtD",
    "returnURL": "https://{procurement-url}/punchout/cxml/%7B07F11422-C45F-B9E7-D312-E6F86929DBE4%7D",
    "creationDate": 1633081854600,
    "buyerCookie": null,
    "credentialFrom": null,
    "credentialTo": null,
    "credentialSender": {
        "domain": "NetworkId",
        "identity": "cxmluser@test.intershop.de"
    }
}

cXML Punchout Basket Transfer

When the cXML Punchout catalog browsing is finished, the cXML Punchout basket is transferred back to the external procurement system. This can be done using the following REST endpoint:

URL

URL pattern

POST https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/transfer?sid=<sid>

Request

An empty body should be sent.

Response (PunchOutOrderMessage)

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>

CXML Punchout Configuration

This section describes how certain values can be configured. Since order injection does not handle localized text, this description relates only to the unit mapping configuration.

A new database table "UserPreference" was introduced to store user-specific cXML configuration data such as the unit mapping (UOM code mapping) and the export locale.

The unit mapping converts procurement system units (usually UOM codes) like BX (box) or PC (piece) to units that are maintained as product packing units in the ICM and vice versa. This is necessary because procurement systems usually only support UOM codes and the product unit in the ICM does not have to follow any standard. Different procurement systems can support a different set of UOM codes. Since the settings are user-specific, multiple cXML users with individual mappings can support multiple procurement systems.

It is also possible to store a global configuration for unit mapping and the export locale in properties which will be overruled by user-specific settings, if they exist.

Definition of Available UserPreference Fields (from 12.0.0)

As mentioned before, the "UserPreference" database table contains the user-specific cXML configuration data. All user preferences that are to be used must be declared in a properties file as the "intershop.cxml.punchout.user.preference.fields" property.
Any preferences that are not declared here will be ignored when reading the user-specific cXML configuration. Only global properties or default values are returned. Writing these entries via REST API will result in an error. Also, the customer/user import will only import declared preferences and skip all others with a warning message.

cxmlpunchoutconfiguration.properties

// all allowed user-preference fields must be mentioned here
intershop.cxml.punchout.user.preference.fields=unitmapping,punchout.locale,punchout.classificationCatalogID,punchout.mapper.supplierPartID,punchout.useShortNameTagInDescriptionTag

Validation of UserPreference Fields (from 12.0.0)

For all defined cXML user preferences (see previous paragraph), a validation expression (RegEx) can be optionally added. When a preference value should be set via Customer/User-Import or via REST API, the provided value will be evaluated against the configured regular expression (intershop.cxml.punchout.user.preference.XXX.validation). If the value does not match the regular expression, the request will be rejected with the provided error message (intershop.cxml.punchout.user.preference.XXX.validation.message).

cxmlpunchoutconfiguration.properties

# all allowed user-preference fields must be mentioned here
intershop.cxml.punchout.user.preference.fields=unitmapping,punchout.locale,punchout.classificationCatalogID,punchout.mapper.supplierPartID,punchout.useShortNameTagInDescriptionTag

# Strings like "Aa;Ba\tCc;Dd" etc.
intershop.cxml.punchout.user.preference.unitmapping.validation=^[a-zA-Z0-9]+;[a-zA-Z0-9]+(\\t[a-zA-Z0-9]+;[a-zA-Z0-9]+)*$
intershop.cxml.punchout.user.preference.unitmapping.validation.message=Value must be a tab-separated list of 'value1;value2' pairs e.g. 'value1;value2\tvalue3;value4\tvalue5;value6'.

# Locale like "en_US"
intershop.cxml.punchout.user.preference.punchout.locale.validation=^([a-z]{2})_([A-Z]{2})$
intershop.cxml.punchout.user.preference.punchout.locale.validation.message=Value must be two small letters for language and two capital letters for region separated by '_'. E.g. 'en_US'.

# non-empty string
intershop.cxml.punchout.user.preference.punchout.classificationCatalogID.validation=^(?!\\s*$).+
intershop.cxml.punchout.user.preference.punchout.classificationCatalogID.validation.message=Value must be non-empty string.

# non-empty string
intershop.cxml.punchout.user.preference.punchout.mapper.supplierPartID.validation=^(?!\\s*$).+
intershop.cxml.punchout.user.preference.punchout.mapper.supplierPartID.validation.message=Value must be non-empty string.

# either "true" or "false"
intershop.cxml.punchout.user.preference.punchout.useShortNameTagInDescriptionTag.validation=^(true|false)$
intershop.cxml.punchout.user.preference.punchout.useShortNameTagInDescriptionTag.validation.message=Value must be either 'true' or 'false'.

The CXMLPunchoutConfigurationProvider

This provider is used to supply the configurations, e.g., 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 the following methods:

configuration provider methods

Map<String, String> getUnitMappings(UserBO userBO); 
LocaleInformation getPunchoutLocale(UserBO userBO);
String getClassificationCatalogID(UserBO userBO); 
String getSupplierPartIDMapperID(UserBO userBO);

Normally, all configuration values are retrieved from a hierarchy (user-specific, global, default). The details are described in chapters for Locale for Product Texts, Unit Mapping, Mapping of SupplierPartID, and Product Classifications.

If the hierarchy logic or the source of the configuration must be different in a customized project, it can be replaced.

This can be done by implementing your own customCXMLPunchoutConfigurationProviderImpl and using Concept - Dependency Injection and ObjectGraphs to wire it to the interface.

Locale for Product Texts

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

A "global" configuration can be defined by creating a property with the intershop.cxml.punchout.locale key. It is also possible to create a preference in the UserPreferences table with the punchout.locale name and the cxml group to define a user-specific configuration.

Hierarchy

The hierarchy or priority for the locale is as follows:

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

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

3. The locale is stored for the current application.

4. The system-wide lead locale.

Unit Mapping

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

Global Mapping Configurations

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

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

User-Specific Mapping Configurations

It is also possible to create a preference in the UserPreferences table with the unitmapping name and the cxml group 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

Key and Value - Unit Explained

The left side of the configuration aka 'key' is the units in the procurement system.

The right part aka 'value' is the unit available in the ICM.

Example mapping:

• For the cXML Punchout process, the mapping happens from value to key configuration (ICM to calling procurement system).

• For the Order Injection process, the mapping happens from key to value configuration (order injecting procurement system to ICM).

Default Key or Value

If the value for the unit is not available, default values for the key and the value can be defined, see Cookbook - cXML | Recipe: Add Default Custom Unit Mappings. 

This means, for example, that if no unit is defined for a product, the default configuration is used instead, if available.

Hierarchy

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

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

1. The user-specific preference is stored with the given user.
   It overwrites/replaces any already existing global values and adds non-existing user configurations.

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

Examples:

There are basically three different possibilities for configuration:

• A global configuration where some user-specific configurations are replaced

• Exclusive use of user-specific configuration

• Exclusive use of global configuration

Mapping of SupplierPartID (from 12.0.0)

In order to customize the PunchoutOrderMessage, it is possible to adjust the mapping of the item's supplier part ID. Out-of-the-box it can be selected between ProductRef and SKU. It is also possible to add their own implementations to get different values.
See Cookbook - cXML Punchout: Recipe How to Change the mapping for SupplierPartID in the PunchOutOrderMessage (from12.0.0) for a detailed explanation how to do this.

Nested ShortName Tag in Description (from 12.0.0)

According to the CXML standard definition (see https://xml.cxml.org/current/cXMLUsersGuide.pdf (pp 96), the Description tag (within the ItemDetail tag) contains a nested tag called ShortName to hold the name of the product.
See excerpt from the linked user guide:

cXML Standard Definition - ShortName tag

<Description xml:lang="en-US">
<ShortName>Big Computer</ShortName>
This wonder contains three really big disks,
four CD-Rom drives, two Zip drives, an ethernet
card or two, much more memory than you could
ever use, four CPUs on two motherboards. We’ll
throw in two monitors, a keyboard and the
cheapest mouse we can find lying around.
</Description>

Some procurement systems like Microsoft Dynamics 365 Finance and Operations do not accept this nested tag and propose to include the product name in the Description tag instead.
In order to support both cases - the cXML standard with the ShortName tag and the simple adaption to put the product information directly in the Description tag - it is possible to configure if the ShortName tag is used or not. See also Cookbook - cXML Punchout: Recipe How to solve issues with the nested ShortName tag.

useShortNameTagInDescriptionTag=true (Default)
See original example above.

useShortNameTagInDescriptionTag=false

cXML Standard Definition - ShortName tag

<Description xml:lang="en-US">Big Computer
This wonder contains three really big disks,
four CD-Rom drives, two Zip drives, an ethernet
card or two, much more memory than you could
ever use, four CPUs on two motherboards. We’ll
throw in two monitors, a keyboard and the
cheapest mouse we can find lying around.
</Description>

The ShortName tag is missing and the content of the Description starts with the product name followed by the product description separated by a line break (\n).

Product Classifications

The cXML standard supports multiple product classifications like eCl@ss or UN/SPSC. For some ERP systems, a UN/SPSC classification entry is required for cXML Punchout.

The ICM cXML Punchout also supports product classifications. All classifications* (see info box below) of a product are automatically included in the cXML "ItemDetail" section as follows:

<Classification domain="#ClassificationCatalogType#">#AssignedCategory#</Classification>
...

#ClassificationCatalogType# is the placeholder for the type of the classification catalog, e.g., "eCl@ss", "UNSPSC", "ETIM", and the #AssignedCategory# will be replaced with the assigned category, e.g., "5136030000".

The ICM Classification Catalogs are maintained in Intershop Organization Management (see first figure below) as well as in Intershop Commerce Management at the organization level (second picture below).

Intershop Organization Management:

Intershop Commerce Management:

Classification assignments for products can either be maintained in the channel for local channel products or at organization level for shared products (classification assignments are also shared). The product classifications category assignment by the example of ETIM is described here.

For local and shared products, it is necessary to share the classification catalog(s) in the affected channel(s) to include product classifications in the cXML document. This can also be done in the ICM back office (see figures below).

Architecture

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

Cartridges

The following cartridges contain code artifacts:

Roles and Permissions

For cXML Punchout there is one role and a set of permissions:

Available permissions for the role:

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

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

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 the Punchout standard there.

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

Punchout Standard

Intershop Commerce Management 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

Punchout-Specific User Roles

For the existing cXML Punchout standard, the APP_B2B_CXML_USER role is set by default for specific Punchout users in Intershop Commerce Management.

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

Handler Chain

To achieve easy exchangeability and extensibility also for cXML Punchout, a handler chain was implemented for the transfer basket action and is executed when calling POST on /customers/{CustomerKey}/punchout/cxml1.2/transfer. Some of the handlers are version-independent and some work with version-specific classes.

Implemented handlers for 7.10.36.0 are: