Introduction
This concept is valid for ICM version 7.10.31 and higher.
cXML Order Injection is a B2B feature that describes the receiving and processing of a cXML order request, generally sent from a procurement system. After receiving a cXML file, it is parsed, a basket is created with certain values from the cXML file, and an order is created.
References
Glossary
cXML is a standard for Punchout similar to OCI. Besides the Punchout to an external B2B store, it also supports order injection with basket data.
General Concept
This feature is very flexible and will most likely be implemented differently in every project. Therefore, one of the main goals for this implementation was the exchangeability and extensibility of the provided functionality. To achieve this, the handler chain framework has been chosen. This allows projects to easily extend, replace, or remove standard functionality.
Before the handler chain is being executed, ICM receives the cXML content via a pipeline call and tries to determine the version of the cXML file by evaluating the cXML DOCTYPE tag. If the version cannot be determined, the registered default handler chain will be used, in standard case the CXMLOrderInjectionChainV2. The handler chain manages everything else, like unmarshalling the provided cXML, checking user credentials, creating a basket, mapping different values to the basket, and finally creating the order. In any case, a response will be sent, either including a success message or some information about any problems that occurred, based on the cXML Standard.
Handler Chain
There are two main chains implemented in the standard implementation and several handlers. Some of the handlers are version-independent, and some work with version-specific classes. This can be differentiated by the package name. Version-independent handlers can easily be reused in a different chain for a new version.
The first is PreCXMLOrderInjectionChainV2. It handles all kinds of preparation to place the order later. Currently, (7.10.31) implemented handlers are:
Name of Handler | Description | Version-independent |
|---|---|---|
ParseCXMLOrderInjectionHandler | Handler that parses the input stream to an object. | no |
CheckBasketCXMLOrderInjectionHandler | Handler that checks if the basket provided via cXML is valid. | no |
CheckUserCXMLOrderInjectionHandler | Handler that checks if the user data sent in the cXML Header are valid. | no |
MapBasketCXMLOrderInjectionHandler | Handler that maps the cXML OrderRequest to a basket. | yes |
MapLineItemsCXMLOrderInjectionHandler | Handler that adds items from a cXML order request to a basket. | no |
MapShippingMethodCXMLOrderInjectionHandler | Handler that adds a shipping method to the basket from cXML. | no |
MapOrderAddressesCXMLOrderInjectionHandler | Handler that adds an invoice address and shipping address for the whole order if specified in the cXML. | no |
MapPaymentCXMLOrderInjectionHandler | Handler that sets the configured payment method at the basket. | yes |
PrepareBasketForOrderCreationCXMLOrderInjectionHandler | Handler that prepares a basket for the order creation by validating and calculating. | yes |
The second chain CreateOrderCXMLOrderInjectionChainV2 creates the actual order and has only one handler:
Name of Handler | Description | Version-independent |
|---|---|---|
CreateOrderCXMLOrderInjectionHandler | Handler that creates an order from a basket, which was created from a cXML order request. | yes |
In a development environment, the actual loaded handlers can be checked via a pipeline call to InspectHandlerChains-Start, like https://<yourServer>/INTERSHOP/web/WFS/inSPIRED-inTRONICS_Business-Site/en_US/-/USD/InspectHandlerChains-Start.
If there is a failure in any of the handlers, the chain will be rolled back. In standard implementation, that means the reverseInvoke() from MapBasketCXMLOrderInjectionHandler will be called, which moves the basket into the basket history.
Versioning
The cXML order injection feature released with 7.10.31 is based and tested on cXML Version 1.2.049. In ICM, the implemented cXML feature is referred to as V2.
Other minor cXML versions will most likely work with V2 as well, but that has not been tested.
If another feature version is needed, this can be done by implementing a new handler chain for the according version and registering it via Guice. Please refer to Cookbook - cXML Order Injection | Recipe: How To Support Another Version of cXML.
Testing
https://punchoutcommerce.com/tools/cxml-order-tester offers a testing tool for your environment.
If your environment is only available internally, you can follow Cookbook - cXML Order Injection | Recipe: How to Test My System.
Configuration
The feature described in this section is available from ICM version 7.10.35.1.
This section describes how certain values can be configured.
A new database table "UserPreference" was introduced to store user-specific cXML configuration data such as the unit mapping (UOM code mapping) and the export locale.
The unit mapping converts procurement system units (usually UOM codes) like BX (box) or PC (piece) to units that are maintained as product packing units in the ICM and vice versa. This is necessary because procurement systems usually only support UOM codes and the product unit in the ICM does not have to follow any standard. 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, e.g., for global or user-specific unit mapping. It is used for both, the cXML Punchout basket and the cXML order injection.
The provider has several methods for retrieving configuration data. The following method is to provide the unit mappings:
configuration provider methods
... Map<String, String> getUnitMappings(UserBO userBO); ...
The configuration is retrieved from a hierarchy. The details are described in the next chapter 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.
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 the UserPreferences table with the unitmapping name and the cxml group to define a user-specific mapping configuration.
Here the configuration data is expected to be stored in one line.
The key and values are separated by a ';', the different groups(key-value-pairs) are separated by a '\t' tabulator character.
Example stringValue: EACH;pcs BOX;box DOZ;DOZEN
Any configuration that does not fit the pattern will be printed out as a warning log message and ignored for processing.
Key and Value - Unit Explained
The left side of the configuration aka 'key' is the units in the procurement system.
The right part aka 'value' is the unit available in the ICM.
Example mapping:
For the cXML Punchout process, the mapping happens from value to key configuration (ICM to calling procurement system).
For the Order Injection process, the mapping happens from key to value configuration (order injecting procurement system to ICM).
Default Key or Value
If the value for the unit is not available, default values for the key and the value can be defined, see Cookbook - cXML | Recipe: Add Default Custom Unit Mappings.
This means, for example, that if no unit is defined for a product, the default configuration is used instead, if available.
Hierarchy
The final unit mapping used in the REST calls can come from user-specific preference configurations, from a global property configuration, and/or a combination of both.
The hierarchy or priority for the unit-mapping is as follows:
The user-specific preference is stored with the given user.
It overwrites/replaces any already existing global values and adds non-existing user configurations.The 'global' configuration is 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