Introduction

With the cXML Punchout feature, Intershop Commerce Management (ICM) provides B2B customers with an external interface (cXML) that enables procurement systems to access product data directly. This is done using the cXML transfer format.
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 diagram provides an overview of the general process. For a more detailed workflow plan, see the cXML Punchout Catalog Browsing section.

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 on to 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 provides technical insights into the cXML Punchout implementation in ICM (excluding cXML Order Injection).

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

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

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.

After that, 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. You will then see a reduced storefront (e.g., fewer visual elements (no footer, etc.), missing functionality such as quotes, wish list, etc.).

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 next sections explain the process with sample 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:

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 to a PunchoutSetupRequest can be either a failure or a success. The HTTP response code is always 200, for both failure and success. Only the content of the response is different.

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

Example Response: 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: 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 contains only a URL pointing to the PWA storefront (StartPage) with a Punchout session ID and an access-token as parameters.

Example Response: 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 session details 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.

If 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

The pattern of the 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.

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

The pattern of the 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 the 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.

Global Default Values

It is possible to define a global default value for each available configuration. This value will be used if no user-specific preference is set, except for the “unitmapping” field, see Unit Mapping.

The default values are retrieved from properties files via the configuration framework, for example, cxmlpunchoutconfiguration.properties.

The property values should be defined as follows:

intershop.cxml.XXX=<default value>

In this line, XXX is the placeholder for the configuration name, for example: unitmapping, punchout.locale, punchout.useShortNameTagInDescriptionTag, see section Available Configurations.

For some of the configurations, ICM already defines global default values. These global default values can also be overridden in user-defined projects by providing the same property with a new value that is defined in a customer-specific properties file.
For example,
ISH-Standard (cxmlpunchoutconfiguration.properties):

intershop.cxml.punchout.classificationCatalogID=UNSPSC

Custom project (cxmlpunchoutconfigurationcustom.properties):

intershop.cxml.punchout.classificationCatalogID=ecl@ss

This changes the global default value of this configuration "punchout.classificationCatalogID" for this customer project from "UNSPSC" to "ecl@ss", which can also be overridden by a user-specific configuration.

When neither global default values nor user-specific settings are defined, additional fallbacks are sometimes used. For example, for punchout.locale there are fallbacks to the application locale or the system-wide lead locale.

User Preferences

As the name suggests, user-specific preferences can be set differently for different cXML users. This is useful and necessary when connecting different external procurement systems that require different configurations. For this purpose, a new database table UserPreference was introduced to store user-specific cXML configurations.

cXML user-specific preferences can either be imported via customer/user import or set/changed using the cXML Punchout REST API, see Overview - Intershop Commerce Management REST API.

Customer/User Import

Example of an import file (see tag user-preferences):

...
<user business-partner-no="cxmluser1">
	<business-partner-no>cxmluser1</business-partner-no>
	<profile>
		...
		<user-preferences>
			<user-preference name="punchout.locale" group="cxml">de_DE</user-preference>
			<user-preference name="unitmapping" group="cxml">PC;pcs	EA;each</user-preference>
			<user-preference name="punchout.classificationCatalogID" group="cxml">eCl@ss</user-preference>
			<user-preference name="punchout.mapper.supplierPartID" group="cxml">SKU</user-preference>
			<user-preference name="punchout.useShortNameTagInDescriptionTag" group="cxml">false</user-preference>
		</user-preferences>
	</profile>
	...
</user>
....

Getting/Setting Configurations with cXML Punchout REST API (from 12.0.0)

A new rest endpoint configurations has been introduced for cXML users in ICM 12.0.0.
URL: PATCH /customers/{CustomerKey}/punchouts/cxml1.2/users/{CXMLPunchoutUserKey}/configurations

For Intershop REST API documentation, refer to Overview - Intershop Commerce Management REST API.

Versioning

There are two major versions of the (cXML) Punchout REST API under customers/{CustomerKey}/punchouts/cxml1.2 (2.x.x, 3.x.x)

• Version 2.x.x contains OCI and cXML functionality combined into one REST API. For cXML, the first draft a getting/setting cXML user-specific configurations is contained. This should no longer be used as it has been reworked and extracted into a new separate “cXML Punchout REST API” without OCI. The accept header for this 2.x.x version is application/vnd.intershop.punchout.v2+json.

• Version 3.x.x (since 12.2.0) contains cXML functionality only. The configurations endpoint has been reworked so that the data returned is structurally different from version 2.x.x and contains additional information. Intershop recommends to use this API version for all cXML-related actions. The accept header for this 3.x.x version is application/vnd.intershop.punchout.cxml.v3+json.

Definition of Available UserPreference Fields (from 12.2.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. The list of declared fields can also be extended by projects using the intershop.cxml.punchout.user.preference.fields.custom property. It is also possible to replace the default list, see Cookbook - cXML Punchout | Recipe: Add Custom Configuration Value for User-specific Punchout Configurations (from 12.2.0) for detailed information.

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

Additional Information for UserPreference Fields (from 12.2.0)

From ICM 12.2.0, it is possible to provide optional additional information for the user preferences. This includes:

Non-localized Properties

inputtype:

• Input field type to tell the UI which input field to use

• Values: “text-short” (default, standard text field), “text-long” (textarea)

• If no value is specified, the default value “text-short” is used.

validation:

• RegEx pattern to validate the input values (via REST API and user import)

• If no pattern is provided, no validation will be performed.

The values can be defined for each field in cxmlpunchoutconfiguration.properties, where XXX is the placeholder for the field name:

• intershop.cxml.punchout.user.preference.XXX.inputtype=...

• intershop.cxml.punchout.user.preference.XXX.validation=...

Localized Properties

validation.message:

• Localized (error/warning) message to be displayed when RegEx validation fails

• If a validation pattern is provided, there must also be a message.

description:

• Localized additional description of the field that is displayed on the input screen of the cXML user-specific configuration page

These are localized strings which are defined in locale-specific property files cxmlpunchoutconfiguration_YY.properties, where YY is the placeholder for the supported languages, e.g. de, en, fr, and XXX is the placeholder for the field name:
intershop.cxml.punchout.user.preference.XXX.validation.message=...
intershop.cxml.punchout.user.preference.XXX.description=...

Validation is discussed in more detail in the next section.

Validation of UserPreference Fields (from 12.2.0)

As mentioned before, a validation expression (RegEx) can be added for any defined cXML user preference. When a preference value is set via customer/user import or via REST API, the provided value is evaluated against the configured regular expression (intershop.cxml.punchout.user.preference.XXX.validation). If the value does not match the regular expression, a localized error/warning message (intershop.cxml.punchout.user.preference.XXX.validation.message) is created.

When setting values via the REST API, if one or more invalid values are sent, the entire request is rejected as invalid.
During the customer/user import, invalid user settings are displayed only as warnings and are ignored. The import process will still continue and will not be canceled.

cxmlpunchoutconfiguration.properties

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.punchout.locale.validation=^([a-z]{2})_([A-Z]{2})$
intershop.cxml.punchout.user.preference.punchout.classificationCatalogID.validation=^(?!\\s*$).+
intershop.cxml.punchout.user.preference.punchout.mapper.supplierPartID.validation=^(?!\\s*$).+
intershop.cxml.punchout.user.preference.punchout.useShortNameTagInDescriptionTag.validation=^(true|false)$

cxmlpunchoutconfiguration_en.properties

intershop.cxml.punchout.user.preference.unitmapping.validation.message=The value of the ''unitmapping'' field must be a \u0026-separated list of ''value1;value2'' pairs, for example, ''value1;value2\u0026value3;value4\u0026value5;value6''.
intershop.cxml.punchout.user.preference.punchout.locale.validation.message=The value of the ''punchout.locale'' field must be two lowercase letters for language and two uppercase letters for region, separated by ''_''. For example, ''en_US''.
intershop.cxml.punchout.user.preference.punchout.classificationCatalogID.validation.message=The value of the ''punchout.classificationCatalogID'' field must be a non-empty string.
intershop.cxml.punchout.user.preference.punchout.mapper.supplierPartID.validation.message=The value of the ''punchout.mapper.supplierPartID'' field must be a non-empty string.
intershop.cxml.punchout.user.preference.punchout.useShortNameTagInDescriptionTag.validation.message=The value of the ''punchout.useShortNameTagInDescriptionTag'' field must be either ''true'' or ''false''.

cxmlpunchoutconfiguration_de.properties

intershop.cxml.punchout.user.preference.unitmapping.validation.message=Der Wert des Feldes ''unitmapping'' muss eine durch \u0026-Zeichen getrennte Liste von ''value1;value2''-Paaren sein, zum Beispiel ''value1;value2\u0026value3;value4\u0026value5;value6''.
...

cxmlpunchoutconfiguration_fr.properties

intershop.cxml.punchout.user.preference.unitmapping.validation.message=La valeur du champ \u00AB unitmapping \u00BB doit \u00EAtre une liste de paires \u00AB value1;value2 \u00BB s\u00E9par\u00E9es par des \u0026, par exemple \u00AB value1;value2\u0026value3;value4\u0026value5;value6 \u00BB.
...

Available Configurations

Locale for Product Texts

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

Unit Mapping

intershop.cxml.unitmapping.EA=pcs
intershop.cxml.unitmapping.BX=Box
intershop.cxml.unitmapping.DZ=Dozen
intershop.cxml.unitmapping.CS=Case

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

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 the value 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 part of the configuration aka 'key' represents 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 is performed from the value to the key configuration (ICM to calling procurement system).

• For the Order Injection process, the mapping is performed from the key to the 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 will be used instead, if available.

Examples:

Product Classification (from 12.0.0)

Classification specifies the commodity grouping of the line item to the buyer. The cXML standards requires a product classification, preferably UNSPSC.

To customize the PunchoutOrderMessage, it is possible to specify which classification (catalog) should be used to provide the product classification.
Therefore, the “type” of the classification catalog has to be specified here, also see section Product Classifications.

See also Cookbook - cXML Punchout: Recipe: How to Adjust the Classification Catalog Used (from 12.0.0).

Mapping of SupplierPartID (from 12.0.0)

To customize the PunchoutOrderMessage, it is possible to adjust the mapping of the item's supplier part ID. Out of the box, you can choose between ProductRef and SKU. It is also possible to add your 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 on how to do this.

Nested ShortName Tag in Description (from 12.0.0)

As defined by the cXML standard, 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 (line 2). See the excerpt from the linked user guide for what it looks like when useShortNameTagInDescriptionTag=true:

<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, such as Microsoft Dynamics 365 Finance and Operations, do not accept this nested tag and suggest putting the product name in the Description tag instead.
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 whether the ShortName tag should be used or not.

See also Cookbook - cXML Punchout: Recipe How to solve issues with the nested ShortName tag.

When the flag is set to false (useShortNameTagInDescriptionTag=false), the text looks like this:

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

Access the Configuration Values

The CXMLPunchoutConfigurationProvider should be used to retrieve all the configurations.

The provider currently has the following methods:

// Before ICM 12.2.0
Map<String, String> getUnitMappings(UserBO userBO); 
LocaleInformation getPunchoutLocale(UserBO userBO);
String getClassificationCatalogID(UserBO userBO); 
String getSupplierPartIDMapperID(UserBO userBO);

// Since ICM 12.2.0
Map<String, String> getUnitMappings(UserBO userBO); // get Unit mappings as Map
LocaleInformation getPunchoutLocale(UserBO userBO); // get Punchout locale information object
CXMLPunchoutFieldConfiguration getUserSpecificConfiguration(String fieldName); // get information for defined user-specific configuration given by the fieldName like inputtype, description etc.
List<CXMLPunchoutFieldConfiguration> getUserSpecificConfigurations();  // get the list of defined user-specific configurations
String getStringValue(String fieldName, UserBO userBO) // get user-specific (string) value for given field (if no preference is set the global default value is returned)
String getStringValue(String fieldName, UserBO userBO, CXMLPunchoutFieldConfigurationAccessType accessType) // get user-specific (string) value for given field based on accessType (User preference, default value, both combined)

String getClassificationCatalogID(UserBO userBO);  // deprecated, will be removed in 13.0.0
String getSupplierPartIDMapperID(UserBO userBO);   // deprecated, will be removed in 13.0.0

As already mentioned before, configuration values are retrieved from a hierarchy (user-specific, global default, fallback). The details are described in the previous section Available Configurations.

Get String Value(s)

The standard way to get the user-specific configuration value for a particular field as plain string is to call the following method:
String getStringValue(String fieldName, UserBO userBO)
This method automatically traverses the hierarchy and returns the configuration value for the requested field if one is set (at any level: 1. user-specific preference; 2. global default; 3. fallback).

It is also possible to get only specific values, either user preferences or only default values, without traversing the hierarchy. To do this, use the following method:
String getStringValue(String fieldName, UserBO userBO, CXMLPunchoutFieldConfigurationAccessType accessType)

CXMLPunchoutFieldConfigurationAccessType is an enum defined in the interface class CXMLPunchoutConfigurationProvider and has the following types:

• USER_PREFERENCE_ONLY - Returns user preferences only

• DEFAULT_VALUE_ONLY - Returns default values only (incl. fallbacks)

• USER_PREFERENCE_AND_DEFAULT - Returns both

Especially for more complex configurations like unitmapping, it is useful to also provide the values in a structured way. That’s why for some preferences it’s also possible to Get Object Value(s). See next paragraph.

Get Object Value(s)

To get the unitmappings in a map, use the following method:
Map<String, String> getUnitMappings(UserBO userBO)

(Internally, the method getStringValue("unitmapping", UserBO userBO) is used to retrieve value.)

To provide a convenient way to get the LocaleInformation object instead of the string (e.g. “en_US”), the following method can be used:
LocaleInformation getPunchoutLocale(UserBO userBO);

(Internally, the method getStringValue("punchout.locale", UserBO userBO) is used to retrieve the value.)

Get Available Configurations

To get a list of all defined user-specific preferences, call the method:
List<CXMLPunchoutFieldConfiguration> getUserSpecificConfigurations()

It is also possible to get the information for a single configuration field:
CXMLPunchoutFieldConfiguration getUserSpecificConfiguration(String fieldName)

The returned CXMLPunchoutFieldConfiguration object(s) contain(s) additional information, see paragraph Additional Information for UserPreference Fields, and also the defined default value.
This information is used for UI to change user-specific configurations.

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.

Product Classifications

The cXML standard supports multiple product classifications, such as eCl@ss or UN/SPSC. Some ERP systems require a UN/SPSC classification entry 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 classification catalog type, 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 be maintained either in the channel for local channel products or at the organization level for shared products (classification assignments are also shared). The assignment of product classifications to categories is described here using ETIM as an example.

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

General 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 for the transfer basket action has been implemented 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: