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

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.

Glossary

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

• Public Release Note - Intershop Order Management 4.x
• Public Release Note - Intershop Commerce Management 11
• Concept - Managed Service Framework
• Guide - ICM & IOM Configuration Tasks
• Cookbook - IOM Connector Customization
• Reference - Order IOM Extension REST API 1.0.1

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.

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.

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:

Identifiers

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

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.

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.

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:

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.

[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:

• Declaration customization image
• Add feature cartridge ft_iomconnector to cartridge list (See Concept - Customization - Deployment - ICM 11+)

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.

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

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:

• Concept - Customization - Development - ICM 11+
• Concept - Customization - Deployment - ICM 11+

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