Concept - cXML Punchout


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

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
PWAIntershop Progressive Web App

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

1.3.1 User Management Features

FeatureDescription
List cXML Punchout UsersShows all cXML Punchout users (/punchouts/cxml1.2/users) for a customer.
cXML Punchout User CreationAccount admins can create cXML Punchout users.
Edit cXML Punchout UserAccount admins may update a cXML Punchout user's e-mail or password and set them to active/inactive.
Delete cXML Punchout UserAccount admins can delete a cXML 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 Browsing / Basket TransferThe initial step to open a cXML session (/punchouts/cxml1.2/setuprequest) for catalog browsing. As in any "normal" web shop, products can be added to or removed from the shopping cart. At the end of the Punchout session, the cart will be transferred back to the procurement system (/punchouts/cxml1.2/transfer).
cXML Order InjectionAllows to create an order in the Intershop Commerce Management system directly from an external procurement system. This is described in separate documents.
See Concept - cXML Order Injection and Cookbook - cXML Order Injection for details.

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

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

2.1.1 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

2.1.2 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>
ParameterDescription

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

Login name of a storefront user with the role cXML Punchout user, e.g.: cxmluser@test.intershop.de
<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

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

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>

In case the cXML Punchout user does not exist or the credentials are not correct, the following response body would be 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").

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

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

2.2.2 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"
    }
}

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

2.3.1 URL

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

2.3.2 Request

An empty body should be sent.

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

3 Localized Name, Description and Unit Mapping


ICM Version

The feature described in this section is available from ICM version 7.10.35.1.

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:

configuration provider 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.localeIt 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

Note

Any configuration that does not fit the pattern will be printed out as a warn log message and ignored for processing.

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:

Key

User value

Global value

Value used for mapping

EA

stück

pcs

stück

BOX

box


box

DOZ


dozen

dozen

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

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

5 Architecture

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

5.1 Cartridges

The following cartridges contain code artifacts:

CartridgeDescription
bc_punchoutCommon Punchout-related code, valid for both supported standards (OCI, cXML)
bc_punchout_testTest cartridge for bc_punchout containing integration tests
bc_punchout_ormCommon punchout-related code, valid for both supported standards (OCI, cXML) regarding ORM (persistence)
bc_punchout_cxmlIncludes generated cXML Java classes and some basic functionality for cXML Punchout and cXML order injection
bc_punchout_cxml_testTest cartridge for bc_punchout_cxml containing integration tests
app_sf_rest_b2b_punchoutPunchout WebShop REST API (OCI and cXML)
app_sf_rest_b2b_punchout_testTest cartridge for app_sf_rest_b2b_punchout containing integration tests
ac_cxml_order_injectionPunchout order injection REST API (Concept - cXML Order Injection and Cookbook - cXML Order Injection)
ac_cxml_order_injection_testTest cartridge for ac_cxml_order_injection containing integration tests
init_b2b (partly)Roles and permissions
b2b (partly)REST tests based on Spock (src\remoteTest\groovy\rest\com\intershop\specs\punchout\*.*)

5.2 Roles and Permissions

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

Role

Description

APP_B2B_CXML_USER

The B2B cXML user

Available permissions for the role:

Permission

Description

APP_B2B_VIEW_PUNCHOUTPermission to view available Punchout standards and their details
APP_B2B_MANAGE_PUNCHOUTPermission to manage Punchout users and configurations

APP_B2B_SEND_CXML_BASKET

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

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

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.

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

5.3.1 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

5.3.2 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

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

Name of HandlerDescription

Version-independent

CreateCXMLPunchoutHandlerV2Handler that creates the cXML object that is sent to the procurement system.no
CreateLicenseTransactionCXMLPunchoutHandler

Handler that creates a license transaction for the cXML transfer basket action.

yes
RemoveSessionCXMLPunchoutHandlerHandler that removes the cXML session.yes
MoveBasketToHistoryCXMLPunchoutHandlerHandler that moves the Punchout basket to the basket history.yes
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