Document Properties
Kbid
3126A4
Last Modified
04-Dec-2024
Added to KB
04-Sep-2024
Public Access
Everyone
Status
Online
Doc Type
Release Notes
Product
  • IOM 4.7
  • IOM 5.0
  • ICM 12
  • IOM 5.1
Public Release Note - IOM Connector 9

Introduction

The IOM Connector is a customization, comprised by 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 these entities.

Dependency Version Information


IOM ConnectorIntershop Commerce Management B2XIntershop Order Management
Version9.012.0+4.7+
9.112.2+4.7+

Below you can find some general technical and business information about the IOM Connector.

In a nutshell, Intershop Commerce Management set up with IOM Connector affects the following:

  • Orders placed in the e-commerce shop are routed to IOM.
  • Order history, available in the My Account section, shows real-time IOM data of orders' statuses.
  • Order Details contain a field that presents information about the Order Documents and Notes.

Intershop Commerce Management B2X features such as order approval or additional order information are fully compatible with the IOM Connector. Orders are not exported to IOM until the appropriate approval processes have been completed. In addition, any information stored with the order, such as message to merchant, cost center, and project, is also exported.

As with any Intershop feature that connects ICM to another system, all features are implemented using the Managed Services framework.

Intershop recommends creating and managing the IOM Services in the context of channels.

Glossary

TermDescription
ICMThe abbreviation for Intershop Commerce Management
IOMThe abbreviation for Intershop Order Management

Delivery

The customization set f_iomconnector (IOM Connector) contains the following cartridges:

  • ac_iomconnector_inventory
  • ac_iomconnector_orderexport
  • ac_iomconnector_orderexport_b2b
  • ac_iomconnector_orderhistory
  • ac_iomconnector_rest_common
  • ac_iomconnector_rma
  • as_iomconnector
  • init_iomconnector
  • demo_iomconnector
  • ft_iomconnector
  • ft_iomconnector_demo

References

Feature Overview

Integration

The IOM Connector is set up alongside a standard ICM installation. It adds additional cartridges that define the following managed services:

  • IOM Order Export Service - Exports order data from ICM to IOM.
  • IOM Order History Service - Changes the order history section in a way that the orders' statuses are fetched from IOM whenever the customer requests them.
  • IOM RMA Service - Allows a customer to request a return of an order. The customer can select the items to be returned, a reason for the return, and optionally a pickup address where the return parcel is picked up by the carrier.
  • IOM Inventory Service - Provides a way to retrieve inventory levels from Intershop Order Management, pass them to Intershop Commerce Management, and to perform product reservations.

 

Channels and Shops

Both ICM and IOM follow the same hierarchical concept of organizations that have expandable entities. However, these entities are different. In ICM, a sales organization can have multiple channels, while in IOM, a sales organization can 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.

Although not mandatory, some IOM services are created in the context of a channel. This ensures that the communication exchange between the ICM and the IOM takes place at the intended level.

Communication

Endpoints

The services mentioned in the previous chapter are implemented using web services. They exchange data between the two systems in a specific format, but they also need to be configured. Web services require an endpoint that is different for each of them. In the table below you can see the endpoints, with IOM server host/address shown as a placeholder.

ServiceEndpointIOM REST APINote
IOM RMA Servicehttps://<iom-host>/rest/rmaRMA v2.10
IOM Inventory Servicehttps://<iom-host>/servlets/services/

IOM Order Export Servicehttps://<iom-host>/rest/order-serviceOrder 2.0
IOM Order History Servicehttps://<iom-host>/rest/order-serviceOrder 2.0

Shop

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.

Authorization

Consumers of the services must authorize themselves to IOM before any data is processed, either as input or output. To do this, you must create a user in the IOM with the appropriate permissions for the operations performed by the service. An easy way to ensure this is to assign the ShopServiceClient role to the appropriate user. However, you can fine-tune the permissions for each service, as they require a username/password combination.

If you are using prepared demo data, you should consider these prepared values:

Consumer Web-Serviceconsumer_ws
CompanyinSPIRED
Shop(s)inTRONICS
inTRONICS Business

Identifiers

Both systems exchange data, so they need a common basis for this communication. The following table shows the mappings between IOM and ICM:

IdentifierICMIOM
ProductChannel's product SKUShop product ID
CustomerCustomer No.Shop customer number
OrderOrder 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.

Order Export

The IOM Connector provides instruments that route any order placed from ICM to IOM. To use this feature, you need to configure the order export (see Configure Order Export), which depends on an existing service configuration (see Configure IOM Order Service). You can 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

Extended B2B Features

Order approval and additional order information works out of the box with order export to IOM. Orders are exported to IOM once they have been approved by the responsible user(s) in the customer's organization. All approval-related and additional information is exported to IOM when the order is placed. It is available in the Attributes section.

Mapping

The table below lists the mapping of data exchanged between ICM and IOM.

ICMIOM
Order Details
Order Document NumberShop Order Number
Creation DateShop Order Creation Date
InventoryReservationId (Custom Attribute)Reservation ID
Custom AttributesAdditional Attributes
Invoice & Shipping Address
Location
Country CodeCountry Code
Main DivisionDistrict
Postal CodePost Code
CityCity
Address Line 1Street
Address Line 2Address Addition
Address Line 3Address Addition
Post BoxPost Box
Contact
EmailEmail
Phone HomePhone
FaxFax
Phone MobileMobile
Receiver
Company Name 1Company Name
Person
HonorificTitle
TitleSalutation
First NameFirst Name
Last NameLast Name
Shipping Bucket
Order Shipping Method IDShipping Method
Custom AttributesAdditional Attributes
Shipping Costs / SurchargesCharges
Line Item Information
PositionNumber
QuantityQuantity
Quantity UnitProduct Unit
Custom AttributesAdditional Attributes
Product Information
SKUNumber
Display NameName
EANCode (Custom Attribute)EAN
ISBN (Custom Attribute)ISBN
Price Information
(specific) Net priceNet
(specific) Gross PriceGross
Tax Information
AmountAmount
Tax Class

Type

Payment Information
Payment Service IDPayment Method

Note

Shipping and carriers are different in nature. While the sales channels in ICM have shipping methods that can be selected by the customer, in IOM the carriers that execute these shipping methods are listed. For example, you might have two shipping methods in ICM, DHL Express and DHL Standard, both of which are covered by a single carrier, DHL.

Mapping Payment Attributes

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

Order History

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. To reduce the number of internal requests between the systems, the IOM Order History Service supports the caching of the results for a short time interval (a 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 as soon as they are updated in IOM. For example, any action taken in IOM, such as confirmation of delivery, will show up in ICM as soon as someone requests the Order History. The table below shows the mapping between order statuses in the two systems.

Intershop Commerce ManagementIntershop Order Management
initial orderINITIAL
in validation

CHECKED

NOT_CHECKED

canceled

CANCELED

NOT_CHECKED_DO_CANCEL

checkedCHECKED
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 approvalDO_APPROVE
not approvedNOT_APPROVED
approvedAPPROVED
assigning supplierDO_ANNOUNCE
will be canceledNOT_ANNOUNCED
assignment failedNOT_ANNOUNCED_DO_CANCEL
suppliers assignedANNOUNCED
optimising supplierDO_OPTIMIZE
optimisedOPTIMIZED
prepare responseDO_PREPARE_RESPONSE
prepare documentsDO_PREPARE_DOCUMENT
documents preparedPREPARED_DOCUMENT
ready to transmitDO_CREATE_TRANSMISSION
waiting for transmissionWAIT_FOR_TRANSMIT
order transmissionCREATED_TRANSMISSION
reservation commissionedRESERVATED
partly canceledRESERVATION_PARTLY_RETURNED
partly commissionedPARTLY_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

transmittedCOMMISSIONED
partly canceled/returnedCOMMISSIONED_PARTLY_RETURNED
shippedDISPATCHED
returnedRETURNED
canceledCANCELED
export failed

(order transfer to IOM system failed, therefore no order status mapping available)

For more information on the IOM order status models, see IOM Order Status Model.

Payment Statuses

The current payment status is very important for customers. After an order has been submitted, you can see 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:

PaidThe order is completely paid.
Part Paid The order is partially paid.
Not PaidThe 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.

When an order is fully paid, the customer will see a green progress bar showing 100% and the Open Invoiced Amount line will show $0.

My Account | Order History | View

Order Invoice in IOM

Inventory Service

The main task of the Inventory Service is to check the product availability status for a given product in IOM. The 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 containing the customer's desired product is opened, the Inventory Service queries IOM for an ATP (available to promise) status. If the product is available, the customer will see the Add to Cart button and a field to specify the desired quantity of the product. 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.

Example error with SimpleInventoryService
[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

Setup

Helm Declaration of Extension for Deployment

Add customization to helm values:

icm-as:
	customizations:
		iom:
			repository: intershophub/icm-as-customization-iom-connector:<TAG>
...
	environment:
		CARTRIDGE_LIST: "ft_icm_as ft_iomconnector"

Using Docker Compose to Start the Server with the Extension Image

Before starting ICM with the IOM extension, ensure that all required services, the MSSQL database, and the web server are running.

Modify the compose file to specify which cartridges the ICM should load. This is done by setting the CARTRIDGE_LIST environment variable on the application server:

version: "3.8"
services:
	customize-iom:
		image: icm-as-customization-iom-connector:<TAG>
		volumes:
			- customizations:/customizations
...
	appserver:
		depends_on:
		- customize-iom
...
		environment:
			# ... more environment variables ...
			# Example cartridge list. Please adapt to your requirements.
			CARTRIDGE_LIST: "ft_icm_as ft_iomconnector"
...


When the application server is started, a DBPreparation process will run to configure the IOM service. Once this process is complete, you can log in to the back office. Under Services, the IOM service should be available for use.

To use the IOM service, configure the IOM service with the required credentials, Communication URLs, and other configuration parameters.

Customize the Connector

To customize the IOM Connector,  it is necessary to create a customization project for the payment connector.

To add the customization image for the IOM Connector to your project, add it to the dependencies of your customization.
To achieve this, perform the following steps:

  1. Register customization image in your main build.gradle.kts:

    val icmDockerRegistry = "docker.tools.intershop.com/icm/intershophub"
    
    // specified in gradle.properties
    val demoDataVersion: String by project
    val iomConnectorVersion: String by project 
    
    intershop {
        projectConfig {
            modules {
                // ... other modules ...
    
                register("iomconnector") {
                    dependency.set("com.intershop.services.iomconnector:iomconnector:${iomConnectorVersion}")
                    image.set("${icmDockerRegistry}/icm-as-customization-iom-connector:${iomConnectorVersion}")
                    testImage.set("${icmDockerRegistry}/icm-as-customization-iom-connector:${iomConnectorVersion}")
                }
    
    			// if the demo data is not necessary, the if statement can be removed entirely
                if(! demoDataVersion.isNullOrEmpty()) {
                    register("demodata") {
                        dependency.set("com.intershop.demodata:demodata:${demoDataVersion}")
                        image.set("${icmDockerRegistry}/icm-as-customization-demo-data:${demoDataVersion}")
                        testImage.set("${icmDockerRegistry}/icm-as-customization-demo-data:${demoDataVersion}")
                    }
                }
            }
        }
    }
    
    subprojects {
        // ... other settings ...
    
        plugins.withType<JavaPlugin> {
            dependencies {
                // ... other dependencies ...
    
                cartridge(platform("com.intershop.services.iomconnector:iomconnector_versions:${iomConnectorVersion}"))
                implementation(platform("com.intershop.services.iomconnector:iomconnector_versions:${iomConnectorVersion}"))
    
    			// if the demo data is not necessary, the if statement can be removed entirely
    			if(! demoDataVersion.isNullOrEmpty()) {
                    cartridge(platform("com.intershop.demodata:demo_versions:${demoDataVersion}"))
                    implementation(platform("com.intershop.demodata:demo_versions:${demoDataVersion}"))
                }
             }
        }
    }
  2. Add dependencies to the IOM Connector to your project's feature definition (e.g., ft_myproject/build.gradle.kts):

    dependencies {
        // ... more dependencies ...
    
        // IOM Connector (standard without demo)
        cartridgeRuntime "com.intershop.services.iomconnector:ft_iomconnector"
    
    	// Optional: if you are creating a separate demo cartridge within your project and require demo data, you can include the demo features directly via runtime dependency
    	// demodata
    	// cartridgeRuntime "com.intershop.demodata:ft_demo"
    	// IOM Connector with demo services
    	// cartridgeRuntime "com.intershop.services.iomconnector:ft_iomconnector_demo"
    }

    If you just want to set up the demo environment during development, without necessarily creating a dedicated demo cartridge, you can simply add the required demo cartridges to your development config of your main build script:

    intershop_docker {
    	// ... other configuration ...	
    	developmentConfig {
    		appserverAsContainer = true
    		if(! demoDataVersion.isNullOrEmpty()){
            	cartridgeList.set(setOf("ft_demo", "ft_iomconnector_demo", "ft_myproject"))
            	testCartridgeList.set(setOf("ft_demo", "ft_iomconnector_demo", "ft_mytest"))
    		} else {
            	cartridgeList.set(setOf("ft_iomconnector", "ft_myproject"))
            	testCartridgeList.set(setOf("ft_iomconnector", "ft_mytest"))
    		}
    	}
    }

    Info

    Note that all project configuration and dependencies are only needed if you want to have a dedicated demo cartridge and/or wish to use the demo setup while developing locally. For a setup using Docker Compose or Helm charts, add ft_demo ft_iomconnector_demo to the CARTRIDGE_LIST section.

  3. Define iomConnectorVersion in your gradle.properties:

    ...
    iomConnectorVersion = <TAG>
    ...
  4. Start your application server in development mode:
    • Use Gradle to manage the server instance by using the command gradlew startAS

    • Run gradlew tasks to see available tasks or check for further options.


For details on managing the artifacts, see:

Info

The IOM Connector requires additional post-deployment configuration steps. For details, see Guide - ICM and IOM Configuration Tasks.

Configuration

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.

In addition, for the IOM to work with the ICM 12 demo scenario (inSPIRED storefront), specific demo content must be uploaded to the IOM. For information on how to do this, see Guide - IOM Basic Business Configuration | Product Import.

Limitations

Product Information Management

Do not use warranties. Intershop Order Management currently does not support service product types.

Payment

Do not use gift cards and certificates (limited tender payments). Intershop Order Management currently does not support multiple payments. Only a single open tender payment method can be used.

Error Log Entries for RMA

The latest IOM versions support multiple shipping addresses. When this feature is enabled for ICM, an error is logged 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, does not affect functionality, and must be resolved in ICM. If not required, you can disable multiple shipping support.

Changelog

Version IOM Connector 9.1.0

  • Transmission of shipping cost taxes grouped by tax rate per bucket to IOM (ICM 12.2.0 feature)

  • Upgrade to IOM REST API - Order 2.4

Version IOM Connector 9.0.2

  • Fix dependency issues; IOM Connector 9.0.1 could not be integrated into an ICM 12.0.0 based customization project

Version IOM Connector 9.0.1

  • Migration to ICM 12


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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.