Document Properties
Kbid
31Y096
Last Modified
04-Dec-2024
Added to KB
15-Dec-2023
Public Access
Everyone
Status
Online
Doc Type
Release Notes
Product
  • ICM 11
  • IOM 4.0
  • IOM 4.1
  • IOM 4.2
  • IOM 4.3
  • IOM 4.4
  • IOM 4.5
  • IOM 4.6
  • IOM 4.7
Public Release Note - IOM Connector 8

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 those entities.

Dependency Version Information


IOM ConnectorIntershop Commerce Management B2XIntershop Order Management
Version8.111.6+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 will be exported to IOM only if the corresponding approval processes are completed. In addition, any information stored on 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.

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 obtain the 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. 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.

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.

Communication

Endpoints

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 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 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-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 must configure the order export (see Configure Order Export), which depends on an existing service configuration (see Configure IOM Order Service). 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

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

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 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 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. In order 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 (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 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 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:

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

Inventory Service

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.

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

The customization image for the IOM Connector is available in Intershop's public repository.


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 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 while developing 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 necessary 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 adding "ft_demo ft_iomconnector_demo" to the CARTRIDGE_LIST section is sufficient.

  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, refer to 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.

Additionally, in order to get the IOM working with the ICM 11 demo scenario (inSPIRED storefront), specific demo content needs to be uploaded into IOM. For information on how to do this, please refer to 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 so-called open tender payment method can be used.

Error Log Entries for RMA

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 on the functionality and needs to be resolved in ICM. If not required, you can disable the support of multiple shipping.

Changelog

Version IOM Connector 8.1.1

  • Improved documentation of the "Order IOM Extension" REST API:
    The general API description now includes a section about the extensions to the standard Order REST API by the Order History Service of the IOM Connector.
    These documentation enhancements raise the version of the "Order IOM Extension" REST API to 1.0.1.
    For details, see Reference - Order IOM Extension REST API 1.0.1
  • Improved error logging:
    Error messages related to the REST communication between the IOM Connector and the IOM now include detailed response information, such as the HTTP status code and the response body, if available.

Version IOM Connector 8.1.0

  • Implemented parts of the return management (RMA) REST API supplementing the storefront order REST API. For details, see Reference - Order IOM Extension REST API 1.0.1. The implemented REST resources reflect the functionality of the respective RMA REST resources of the IOM. 
    • GET /orders/return-reasons
    • GET /orders/{orderID}/return-requests
    • POST /orders/{orderID}/return-requests
    • GET /orders/{orderID}/return-requests/returnables
    • GET /orders/{orderID}/return-requests/{returnRequestID}/custom-attributes
    • GET /orders/{orderID}/return-requests/{returnRequestID}/positions
    • GET /orders/{orderID}/return-requests/{returnRequestID}/positions/{returnRequestPositionID}/custom-attributes
  • Introduced a new "Order IOM Extension" section within the OpenAPI specification including all REST resources which are added by the IOM Connector:
    • RMA REST resources (/orders/return-reasons, /orders/{orderID}/return-requests/*)
    • Order document REST resources (/orders/{orderID}/documents/*)

Version IOM Connector 8.0.2

  • Migration to ICM 11

  • Services which are deprecated either in IOM or due to termination of SOAP support in ICM were removed:

    • IOM Order Service

    • IOM Order State Service

    • IOM Reverse Service

    • IOM Download Service


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.