The IOM Connector is a set of cartridges that allows data exchange and communication between Intershop Commerce Management and Intershop Order Management. It is an extension (or "service") module for Intershop Commerce Management. As such, it requires a base version against which it can be deployed. The table below describes the version dependencies between those entities.
IOM Connector | Intershop Commerce Management B2X | Intershop Order Management | |
---|---|---|---|
Version | 7.0 | 7.10.31.2+ | 3.1+ |
This version has the same range of features as the IOM Connector 6.5, but it offers support for Tomcat 9 and the updated dependencies.
Below you can find some general information about the IOM Connector - both technical and business information.
In a nutshell, Intershop set up with IOM Connector affects the following:
Intershop Commerce Management B2X features such as order approval or additional order information are fully compatible with the IOM Connector. Orders will be exported to IOM only if the corresponding approval processes are completed. In addition, any information stored to the order - such as message to merchant, cost center and project - will be exported as well.
As with any Intershop feature that connects ICM to another system, all features are realized using the Managed Services framework.
Intershop recommends creating and managing the IOM Services in the context of channels.
Term | Description |
---|---|
ICM | The abbreviation for Intershop Commerce Management |
IOM | The abbreviation for Intershop Order Management |
The component set f_iomconnector (IOM Connector) contains the following cartridges:
Of these cartridges, the following are delivered as source files (while the rest is delivered via the artifact repository):
There are also a few test and development cartridges. Additionally, the sample assembly inspired-iomconnector is provided as source too.
The IOM Connector is set up alongside a standard ICM installation. It adds additional cartridges that define the following managed services:
Both ICM and IOM follow the same hierarchical concept of organizations that have expandable entities. These entities differ, however. In ICM one sales organization may have multiple channels, while in IOM one sales organization may have multiple shops.
Intershop recommends considering channels and shops as synonyms in the context of this document and your setup. Although not the same, they are in close relation to each other.
As mentioned before, a couple of IOM services, although not mandatory, are created in the context of a channel. This way you can ensure that the communication exchange between ICM and IOM is performed on the intended level.
The services mentioned in the previous chapter are realized with web services. They exchange data between the two systems in a specific format, but they also need to be configured. Web services require an end point that is different for each of them. In the table below you can see the end points, with IOM server host/address shown as a placeholder.
Service | End Point | IOM REST API | Note |
---|---|---|---|
https://<iom-host>/webservices/OrderService/v1.2 | deprecated - use IOM Order Export Service instead | ||
https://<iom-host>/webservices/OrderStateService/v1.0 | deprecated - use IOM Order History Service instead | ||
IOM Download Service | https://<iom-host>/webservices/DownloadService/v1.0 | ||
IOM Reverse Service | https://<iom-host>/webservices/ReverseService/v1.0 | ||
IOM RMA Service | https://<iom-host>/rest/rma | RMA v2.10 | |
IOM Inventory Service | https://<iom-host>/servlets/services/ | ||
IOM Order Export Service | https://<iom-host>/rest/order-service | Order 2.0 | |
IOM Order History Service | https://<iom-host>/rest/order-service | Order 2.0 |
When doing the configuration mentioned in the step above, you must also specify a shop. Usually, a channel in ICM represents a shop in IOM.
Consumers of the services must authorize themselves for IOM before any data is processed - either as input or output. To do so, you have to create a user in IOM with the required permissions for the operations performed by the service. An easy way to ensure this is to assign the ShopServiceClient
role to the corresponding user. However, you may fine-tune the permissions for each service as they need a username/password combination.
If you use prepared demo data, consider these prepared values:
Consumer Web-Service | consumer_ws |
---|---|
Company | inSPIRED |
Shop(s) | inTRONICS |
inTRONICS Business |
Both systems exchange data, so they need a common basis for this communication. The following table shows the mappings between IOM and ICM:
Identifier | ICM | IOM |
---|---|---|
Product | Channel's product SKU | Shop product ID |
Customer | Customer No. | Shop customer number |
Order | Order document No. | Shop order number |
These identifiers must be identical for each item in both systems. For example, if an order with a line item that has the SKU 00910 is placed and then exported to IOM, the web services layer will report an error if the product with this product ID is not present in IOM.
The IOM Connector provides instruments that route any order placed from ICM to IOM. To use this feature, you must configure the order export (see Configure Order Export), which depends on an existing service configuration (see Configure IOM Order Service). As mentioned before, you may tweak the export settings on the configuration page, but we generally use on order creation as trigger.
The look and feel as well as the business processes in the standard ICM are not altered in any way, but placed orders are routed to IOM.
Order Confirmation in ICM
Order Details in IOM
Order approval and additional order information works out of the box with order export to IOM. Orders are exported to IOM once they are approved by the responsible user(s) in the customer's organization. All approval-related and additional information is exported to IOM upon order placement. It is accessible in the Attributes section.
The table below lists the mapping of data exchanged between ICM and IOM.
ICM | IOM |
---|---|
Order Details | |
Order Document Number | Shop Order Number |
Creation Date | Shop Order Creation Date |
InventoryReservationId (Custom Attribute) | Reservation ID |
Custom Attributes | Additional Attributes |
Invoice & Shipping Address | |
Location | |
Country Code | Country Code |
Main Division | District |
Postal Code | Post Code |
City | City |
Address Line 1 | Street |
Address Line 2 | Address Addition |
Address Line 3 | Address Addition |
Post Box | Post Box |
Contact | |
Phone Home | Phone |
Fax | Fax |
Phone Mobile | Mobile |
Receiver | |
Company Name 1 | Company Name |
Person | |
Honorific | Title |
Title | Salutation |
First Name | First Name |
Last Name | Last Name |
Shipping Bucket | |
Order Shipping Method ID | Shipping Method |
Custom Attributes | Additional Attributes |
Shipping Costs / Surcharges | Charges |
Line Item Information | |
Position | Number |
Quantity | Quantity |
Quantity Unit | Product Unit |
Custom Attributes | Additional Attributes |
Product Information | |
SKU | Number |
Display Name | Name |
EANCode (Custom Attribute) | EAN |
ISBN (Custom Attribute) | ISBN |
Price Information | |
(specific) Net price | Net |
(specific) Gross Price | Gross |
Tax Information | |
Amount | Amount |
Tax Class | Type |
Payment Information | |
Payment Service ID | Payment Method |
Note
Shipping and carriers are different in their nature. While the sales channels in ICM have shipping methods which are selectable by the customers, IOM has carriers listed that execute those shipping methods. For example, one might have two shipping methods DHL Express and DHL Standard in ICM, both of which are covered by the single carrier DHL.
Mapping the payment attributes supported by IOM (PaymentProviderOrderNo
, PaymentProviderRefNo
and PaymentProviderMerchantAccount
) highly depends on the specific payment service implementations. Therefore, it is not possible to provide a default payment mapping that covers all payment services. Instead, custom mappers can be integrated into the order export process via the extension point: type = IOMConnectorPaymentMappingExtension.class, id = "OrderMapper.bindPayment".
This feature is controlled by the IOM Order History Service. Once this service is configured and activated, the order status information in My Account | Order History is provided by IOM in real time. In order to reduce the number of internal requests between the systems, it supports the caching of the results for a short time interval (few seconds).
My Account | Order History
Order Details | Carrier Tracking Information
Orders of a Customer in IOM
Real time means that order statuses are updated the moment they are updated in IOM. Thus, any action taken in IOM, for example confirmation of delivery, will be shown in ICM as soon as someone requests the Order History. The table below lists the mapping between order statuses in the two systems.
Intershop Commerce Management | Intershop Order Management |
---|---|
initial order | INITIAL |
in validation | CHECKED NOT_CHECKED |
canceled | CANCELED NOT_CHECKED_DO_CANCEL |
checked | CHECKED |
approval required | ORDER_APPROVAL_REQUIRED DEPRECATED (from IOM version 2.15) |
in approval | DO_CREATE_APPROVALTRANSMISSION DEPRECATED (from IOM version 2.15) CREATED_APPROVALTRANSMISSION DEPRECATED (from IOM version 2.15) CHECK_ANNOUNCED |
waiting for approval | DO_APPROVE |
not approved | NOT_APPROVED |
approved | APPROVED |
assigning supplier | DO_ANNOUNCE |
will be canceled | NOT_ANNOUNCED |
assignment failed | NOT_ANNOUNCED_DO_CANCEL |
suppliers assigned | ANNOUNCED |
optimising supplier | DO_OPTIMIZE |
optimised | OPTIMIZED |
prepare response | DO_PREPARE_RESPONSE |
prepare documents | DO_PREPARE_DOCUMENT |
documents prepared | PREPARED_DOCUMENT |
ready to transmit | DO_CREATE_TRANSMISSION |
waiting for transmission | WAIT_FOR_TRANSMIT |
order transmission | CREATED_TRANSMISSION |
reservation commissioned | RESERVATED |
partly canceled | RESERVATION_PARTLY_RETURNED |
partly commissioned | PARTLY_COMMISSIONED |
partly shipped | PARTLY_COMMISSIONED_PARTLY_DISPATCHED COMMISSIONED_PARTLY_DISPATCHED |
partly returned | PARTLY_COMMISSIONED_PARTLY_RETURNED PARTLY_COMMISSIONED_PARTLY_DISPATCHED_PARTLY_RETURNED COMMISSIONED_PARTLY_DISPATCHED_PARTLY_RETURNED DISPATCHED_PARTLY_RETURNED |
transmitted | COMMISSIONED |
partly canceled/returned | COMMISSIONED_PARTLY_RETURNED |
shipped | DISPATCHED |
returned | RETURNED |
canceled | CANCELED |
export failed | order transfer to IOM system failed |
For more information on the IOM order status models, see IOM Order Status Model.
The current status of the payment is very important for customers. After an order has been submitted, you can see information details in the Order History section. Click on View to show the Order Details page with the Payment panel. This panel contains information about the payment status (Paid, Part Paid, Not Paid) and a progress bar:
Paid | The order is completely paid. |
Part Paid | The order is partially paid. |
Not Paid | The order is not paid. |
The progress bar shows the percentage of the order that has already been paid. The total amount of money to be paid can be seen in the line Open Invoiced Amount. If an order is fully paid, the customer sees a green progress bar showing 100%, and the line Open Invoiced Amount states $ 0.
My Account | Order History | View
Order Invoice in IOM
Customers are able to trigger returns of orders. Once the order is shipped and its delivery confirmation is tracked in the IOM, its status is changed to shipped. From the Order History page, every order that has been shipped can be selected for a return by clicking the Return Items button. For each individual item, a return quantity and a reason can be specified. Return reasons are requested from the IOM. For convenience, the ICM provides a drop-down list to select a return reason.
The list of existing return requests for an order can be viewed from the Order History page by using the View Returns button. The list contains the current processing status of the request and some general information.
Activate Service
The IOM RMA Service needs to be configured and activated to use the Order Return feature.
Once a return request has been approved and the return slip has been generated in the IOM or in the My Account section, it can be downloaded from the link displayed on the Order History page of the order.
Activate Service
Printing return slips directly in the My Account section is currently only supported with the IOM Reverse Service. The IOM RMA Service currently does not have this feature. They should not be used together.
To be able to download return documents, the IOM Download Service needs to be configured and active.
This feature allows to display attached documents (notes/information) on the Order Details page. The Order Document retrieval from IOM has a cache handling mechanism that preserves the information for a given time interval. ICM's Order Details page rendering process requests IOM to report the number of documents attached to the specific order. The badge to the right of the View All link indicates the number of documents. Click View All to display a list of all documents. The list shows information such as note type (invoice, credit , etc.), note creation date/time, and a link for the downloading the document.
Note
Information about an order's documents are also available via the IOM Connector REST API. For more detailed information, please refer to:
The main task of the Inventory Service is to check the product availability status for a particular product in IOM. IOM Inventory Service works in real time, but at the same time it supports caching the results for a given time interval (e.g., 5 seconds). When the page with the customer's desired product is open, the Inventory Service requests IOM for an ATP (available to promise) status. If the product is available, the customer will see the button Add to Cart and a field to specify the desired quantity of the product. On the other hand, if the product is not available, a button with the text Notify me when available appears.
Note
Ensure to mark the checkbox Availability check on failure in the service configuration to guarantee that the product availability will be at least checked in the local database in case of a communication problem with the IOM system.
Note
Deactivate SimpleInventoryService
The SimpleInventoryService has to be deactivated if IOM Inventory Service should be used.
[2017-09-27 10:41:31.362 +0100] ERROR localhost ES2 appserver0 [inSPIRED-inTRONICS_Business-Site] [-] com.intershop.component.mvc.internal.inventory.InventoryServiceResolverImpl [] [Storefront] [-igcxxhSVC0cx0GZqycdxxgt17cb0TXN_T4xWB9E] [ESIFAFnLcgUBAAB_-1-07] "ESIFAFnLcgUBAAB_-1-07" Only one adapter allowed to be executable of InventoryService, but 2 adapters found. System Information
The IOM Connector release package is available via Intershop's public Artifactory server. To add it to your release, the following preconditions must be met:
iomConnectorCartridges
and iomConnectorInitCartridges
in the code example of the section IOM Connector 7.0 - Setup | Configure the Assembly) and parts that are distributed as source (see iomConnectorSourceCartridges
and iomConnectorSourceInitCartridges
in the code example), so they can be easily copied and modified in a project.Several IOM Connector cartridges are delivered as source files. These need to be included in the project's component set and adapted manually to work in the project context:
Unzip and copy the contents to your component set directory. The demo assembly inspired-iomconnector does not need to be extracted.
On Windows, certain tools have trouble dealing with path names longer than 255 characters. When in doubt, please use 7-Zip to extract the source packages.
Change the build.gradle file of the extracted cartridges to reference the connector libraries from the repository and local dependencies from your component set.
Cartridge | Reference to Change | New Line |
---|---|---|
app_sf_responsive_carriertracking | compile project(':ac_iomconnector_order') | compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_order' |
ac_iomconnector_orderhistory | compile project(':ac_iomconnector_common') | compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_common' |
compile project(':ac_iomconnector_order') | compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_order' | |
compile project(':ac_iomconnector_rest_common') | compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_rest_common' | |
demo_iomconnector | compile project(':ac_iomconnector_common') | compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_common' |
Change the build.gradle file of your project.
Add the provider of the IOM Connector to the section versionRecommendation
as Ivy dependency.
versionRecommendation { provider { // ... ivy('IOMconnector', 'com.intershop.services.iomconnector:iomconnector-filter'){} } }
Create a file .ivyIOMconnector.version in the project directory with the used IOM Connector version as content:
7.0.2
Re-publish your multiproject.
To add the IOM Connector to your Intershop Commerce Management system, you can either incorporate the cartridges into an already existing assembly or create a new assembly inheriting from an ICM-based assembly. For details on how to create a new assembly, see Recipe: Create a New Assembly Inheriting From an Existing Assembly. If you want to incorporate the cartridges into an already existing assembly, perform the following steps:
Open the build.gradle file of your assembly, add a list of the IOM Connector's cartridges in the assembly
directive and include this list into the assembly's cartridges list:
assembly { // ... cartridges { // ... def iomConnectorCartridges = [ 'ac_iomconnector_common', 'ac_iomconnector_rest_common', 'ac_iomconnector_order', 'ac_iomconnector_inventory', 'ac_iomconnector_rma', 'ac_iomconnector_orderexport', 'ac_iomconnector_orderexport_b2b' ] //old: include (*(iomConnectorCartridges.collect { project(":$it") }), in: [development, test, production]) //new: include (*(iomConnectorCartridges.collect { "com.intershop.services.iomconnector:$it" }), in: [development, test, production]) def iomConnectorCartridgesInit = [ 'init_iomconnector' ] //new: remove snippet to load Intershop development/test cartridges // def iomConnectorCartridgesInitDev = [ // 'dev_demo_iomconnector' // ] // include (*(iomConnectorCartridgesInitDev.collect { project(":$it") }), in: init) // def iomConnectorCartridgesTest = [ // 'ac_iomconnector_order_test', // 'ac_iomconnector_rma_test' // ] // include (*(iomConnectorCartridgesTest.collect { project(":$it") }), in: [development, test]) //old: include (*(iomConnectorCartridgesInit.collect { project(":$it") }), in: init) //new: include (*(iomConnectorCartridgesInit.collect { "com.intershop.services.iomconnector:$it" }), in: init) // These are the cartridges which are delivered as source code. def iomConnectorCartridgesInitSource = [ 'demo_iomconnector' ] include (*(iomConnectorCartridgesInitSource.collect { project(":$it") }), in: init) def iomConnectorCartridgesSource = [ 'ac_iomconnector_orderhistory', 'app_sf_responsive_carriertracking', 'as_iomconnector' ] include (*(iomConnectorCartridgesSource.collect { project(":$it") }), in: [development, test, production]) order = listFromAssembly(baseAssembly) \ + iomConnectorCartridges \ + iomConnectorCartridgesSource \ + iomConnectorCartridgesInit \ + iomConnectorCartridgesInitSource // new: (disabled) // + iomConnectorCartridgesInitDev \ // + iomConnectorCartridgesTest } }
In the same build.gradle file, add the following cartridges to assemblyBuild.database
:
assemblyBuild { database { inherit('<base-assembly>') initCartridges = [ // ... 'ac_iomconnector_common', 'ac_iomconnector_order', 'init_iomconnector', 'demo_iomconnector' ] } }
Exclude conflicting versions from the assembly build.
To do so, add the following lines at the end of the build.gradle file of your assembly. If you have already defined the configurations.all
directive, just add the excludes listed below to it.
configurations.all { exclude group: 'stax', module: 'stax-api' }
Define a unique order sequence.
Both Intershop Commerce Management and Intershop Order Management assign a unique identifier to any order placed in the corresponding system. These identifiers are often referred to as "order document number" or "order ID". In order to have a seamless integration between the two systems, you must synchronize these identifiers. Since ICM has the "leading role" as the orders are created and submitted from customers in the web shop, system administrators need to apply an additional configuration to the order number generation.
The IOM Connector requires an order number generation providing unique order numbers for both systems.
Info
If you are deploying the IOM Connector with ICM and IOM anew - in other words you have no orders placed in both systems - it is safe to skip this step. However, you may want to define a unique order sequence just in case. All you need to do is negotiate a starting number with all parties involved and then add a deployment step that alters the /share/system/config/cluster/database.properties file, namely the property intershop.sequence.startsWith
.
After having created and appropriately having configured the assembly, you must deploy it to the intended target environment.
For details on how to deploy an assembly, see Recipe: Run the Deployment (Initial Installation / Upgrade / Downgrade).
You must run a database initialization to use the IOM Connector.
DBInit is required for the following cartridges:
The cartridge demo_iomconnector can be used to initialize some settings for demonstration purposes in combination with the inSPIRED sample organization.
To execute a full database initialization, use:
gradlew dbinit
To execute the database initialization used for a selected set of cartridges, use:
dbinit -t=ac_iomconnector_common,ac_iomconnector_order,init_iomconnector,demo_iomconnector
For details on managing assembly artifacts, see:
Info
There is no configuration required to deploy the IOM Connector with Intershop Commerce Management.
For a proper interaction of the two systems (IOM and ICM), however, some configuration is necessary. For information on how to do this, refer to Guide - ICM and IOM Configuration Tasks.
Additionally, in order to get the IOM working with the ICM 7.10 demo scenario (inSPIRED storefront), specific demo content needs to be uploaded into IOM. For information on how to do this, please refer to the IOM documentation.
Do not use warranties. Intershop Order Management currently does not support service product types.
Do not use gift cards and certificates (limited tender payments). Intershop Order Management currently does not support multiple payments. Only a single so-called open tender payment method can be used.
Both Intershop Commerce Management and Intershop Order Management assign a unique identifier to any order placed in the corresponding system. These identifiers are often referred to as order document number or order ID. To have a seamless integration between the two systems, you must synchronize these identifiers. Since ICM has the "leading role" as the orders are created and submitted from customers in the web shop, system administrators need to apply an additional configuration to the order number generation.
Info
Intershop Commerce Management's server(s) should be turned off before the steps below are executed.
Go to <server-installation-dir>/local/bin and execute environment.<bat|sh>.
./iomconnector/server/local/bin/environment.sh
Go to <server-installation-dir>/local/tools/misc and execute ant
export-sequence-info -f oracle/database.xml
.
Note
The steps (2. and 3.) to determine the currently configured block size are only valid when using an Oracle database. If you use MS SQL server, please ask the responsible administrator for the configured block size. The default block size is 50.
[/iomconnector/server/local/tools/misc]# ant export-sequence-info -f oracle/database.xml Buildfile: /iomconnector/server/local/tools/misc/oracle/database.xml dbenvironment.environment.decrypt: dbenvironment.environment: environment: export-sequence-info: [sql] Executing commands [sql] 1 of 1 SQL statements executed successfully [sql] Executing commands [sql] 1 of 1 SQL statements executed successfully log: [echo] [02/17/2016 03:20:56 PM] The used enfinity specific sequence informations were successfully exported to file 'sequences-info.properties'. BUILD SUCCESSFUL Total time: 2 seconds
In <server-installation-dir>/local/tools/misc, open the newly generated file called sequences-info.properties.
It looks as displayed in the code block below:
#,LAST_NUMBER,INCREMENT_BY,SEQUENCE_NAME,DOMAIN_SPECIFIC,DOMAINNAME,IDENTIFIER #,51,10,SQHHBAQDGBYQAAAAFUCBLM4M0_,TRUE,inSPIRED-inTRONICS,SellerOrder.DocumentNo.NfsKAB1PpEUAAAFTFT89kGWR # Largest last_number is: SellerOrder.DocumentNo.NfsKAB1PpEUAAAFTFT89kGWR - inSPIRED-inTRONICS #intershop.sequence.blockSize = 10 #intershop.sequence.startsWith = 51
Memorize or write down the number of intershop.sequence.startsWith
and intershop.sequence.blockSize
.
Define an unused order sequence.
Note
It is advised to first pick the bigger number between biggest order ID taken from IOM's orders list and the intershop.sequence.startsWith
from step 3. Next, add the block size from your current configuration and finally add 1. You may also add a date prefix to the order number, or put a unique machine identifier, as long as it contains only numbers.
In this example, ICM's order ID is 51 and IOM's oder ID is 20160128017063. The bigger one is 20160128017063. So add the value of intershop.sequence.blockSize
to it - 20160128017063 + 10 = 20160128017073 - and then add 1. The end result is 20160128017074.
Remove #
from the line intershop.sequence.startWith=
and change its value to the unused order sequence determined in step 7.
################################################################################ ## ## Series (Sequence) Creation Options ## ## ## series numberPattern settings ## #intershop.sequence.numberPattern=00000000 ## ## blockSize - "increment by <n>" ## startsWith - "start with <n>" ## cacheSize - "cache <n>" or "nocache" if <n> = 0 ## orderFlag - "order" if true or "noorder" if false ## #intershop.sequence.blockSize=50 intershop.sequence.startsWith=20160128017074 #intershop.sequence.cacheSize=0 #intershop.sequence.orderFlag=true
The latest IOM versions support multiple shipping addresses. When the feature is enabled for ICM, there is an error printed into the log file when a new return request is created.
Caused by: java.lang.IllegalStateException: There might be multiple ship-to addresses. Call this method only if multiple shipments are not supported. at com.intershop.sellside.appbase.b2c.internal.order.OrderBOImpl.getCommonShipToAddressBO(OrderBOImpl.java:373)
The issue was located, has no influence to the functionality and has to be fixed in ICM. If not required, you can disable the support for multiple shipping.