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.
Term | Description |
---|---|
cXML | Commerce eXtensible Markup Language Protocol or Commerce XML used by ERP/Purchasing Systems when connecting to external Punchout catalogs |
ICM | Intershop Commerce Management |
SMC | System Management Console |
PWA | Intershop Progressive Web App |
The following documentation is related to the cXML Punchout feature:
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.
Feature | Description |
---|---|
List cXML Punchout Users | Shows all cXML Punchout users (/punchouts/cxml1.2/users) for a customer. |
cXML Punchout User Creation | Account admins can create cXML Punchout users. |
Edit cXML Punchout User | Account admins may update a cXML Punchout user's e-mail or password and set them to active/inactive. |
Delete cXML Punchout User | Account admins can delete a cXML Punchout user. |
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).
Feature | Description |
---|---|
cXML Catalog Browsing / Basket Transfer | The 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 Injection | Allows 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. |
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.
The cXML Punchout URL of an ICM system should be publicly available, so that any cXML Punchout user with valid credentials can access it.
The pattern of the URL is described below.
POST https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/setuprequest
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>
Parameter | Description |
---|---|
<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 |
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").
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.
GET https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/sessions/<sid>
Headers: "authentication-token" = <access-token>
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" } }
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:
POST https://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest/customers/OilCorp/punchouts/cxml1.2/transfer?sid=<sid>
An empty body should be sent.
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>
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.
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.
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.
The hierarchy or priority for the locale is as follows:
The user-specific preference stored with the given user.
The 'global' configuration stored in a property, read via ConfigurationMgr.
The locale stored for the current application.
The system-wide lead locale.
The unit mapping is used for both, Punchout and order injection.
It is possible to create a property with key prefix intershop.cxml.unitmapping
to define "global" mapping configurations.
Example: intershop.cxml.unitmapping.EA=pcs
or intershop.cxml.unitmapping.BX=Box
etc.
It is also possible to create a preference in table UserPreferences
with name unitmapping
and group cxml
to define a user-specific mapping configuration.
Here the configuration data is expected to be stored in one line.
The key and values are separated by a ';
', the different groups(key-value-pairs) are separated by a '\t' tabulator character.
Example stringValue: EACH;pcs BOX;box DOZ;DOZEN
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:
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.
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:
The user-specific preference stored with the given user.
It overwrites/replaces any already existing global values and adds non-existing user configurations.
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:
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).
The following artifacts are of interest when developing in the area of Punchout.
The following cartridges contain code artifacts:
Cartridge | Description |
---|---|
bc_punchout | Common Punchout-related code, valid for both supported standards (OCI, cXML) |
bc_punchout_test | Test cartridge for bc_punchout containing integration tests |
bc_punchout_orm | Common punchout-related code, valid for both supported standards (OCI, cXML) regarding ORM (persistence) |
bc_punchout_cxml | Includes generated cXML Java classes and some basic functionality for cXML Punchout and cXML order injection |
bc_punchout_cxml_test | Test cartridge for bc_punchout_cxml containing integration tests |
app_sf_rest_b2b_punchout | Punchout WebShop REST API (OCI and cXML) |
app_sf_rest_b2b_punchout_test | Test cartridge for app_sf_rest_b2b_punchout containing integration tests |
ac_cxml_order_injection | Punchout order injection REST API (Concept - cXML Order Injection and Cookbook - cXML Order Injection) |
ac_cxml_order_injection_test | Test 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\*.*) |
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_PUNCHOUT | Permission to view available Punchout standards and their details |
APP_B2B_MANAGE_PUNCHOUT | Permission 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_SEND_PUNCHOUT_BASKET | Permission 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.
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.
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
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
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 Handler | Description | Version-independent |
---|---|---|
CreateCXMLPunchoutHandlerV2 | Handler 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 |
RemoveSessionCXMLPunchoutHandler | Handler that removes the cXML session. | yes |
MoveBasketToHistoryCXMLPunchoutHandler | Handler that moves the Punchout basket to the basket history. | yes |
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.