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

User Management Features

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

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 were successful a punchout session id is returned.

Afterwards the second step - the Catalog Browsing (Shopping Experience Browsing) - starts automatically. The Intershop PWA allows to log on to the storefront as 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 BrowserFormPost URL) 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.

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:

<?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 of 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 response would be like this:

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

In case the cXML Punchout user does not exist or the credentials are not correct, the following response body would be returned:

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

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

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.

{
    "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 has to be transferred back to the external procurement system. This can be done using the following REST endpoint:

URL

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.

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

Localized Name, Description and Unit Mapping

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 unit 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. It could also be that different procurement systems 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.

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:

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

Both retrieve the configuration from a hierarchy. 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.

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 key intershop.cxml.punchout.locale. It is also possible to create a preference in table UserPreferences with name punchout.locale and group cxml to define a user-specific configuration.

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.

Unit Mapping

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

Global Mapping Configurations

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.

User-Specific Mapping Configurations

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

Key and Value - Unit Explained

The left-hand side of the configuration aka 'key' are 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 stored with the given user.
   It overwrites/replaces any already existing global values and adds non-existing user configurations.

2. The 'global' configuration 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

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

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

# 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: