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

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.

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

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.

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:

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

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.

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:

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.

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

To add the customization image for the IOM Connector to your project, it has to be added to the dependencies of your customization. To achieve this, the following steps are required:

1. Register customization image:

   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:

   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:

   build.gradle.kts

   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. Start your application server.
   There are several ways to do this. The three main use cases are:
   1. Development mode:
      1. Use Gradle to manage the server instance by using the command gradlew startAS
      2. Run gradle tasks to see available tasks or check for further options.

   2. Local Docker environment using docker-compose:
      Adapt the used compose file in order to tell ICM which cartridges to load. This can be achieved by the environment variable CARTRIDGE_LIST of the appserver.

      version: "3.8"
      services:
        # when using demo data
        #customize-demo:
        #	image: icm-as-customization-demo-data:<TAG>
        #  volumes:
        #    - customizations:/customizations
        customize-iom:
          image: icm-as-customization-iom-connector:<TAG>
          volumes:
            - customizations:/customizations
        # ... other services ... #
        appserver:
          # ... other appserver settings ...
          container_name: appserver
          environment:
            # ... more environment variables ...
            
            # example cartridge list including IOM Connector. Please adapt to your needs.
            CARTRIDGE_LIST: "ft_myproject"
      	  # example cartridge list with demo data
      	  # CARTRIDGE_LIST: "ft_demo ft_iomconnector_demo ft_myproject"
            
      # ... more configuration ...

   3. Production environment using Helm charts:
      Also when using Helm to manage the ICM instances, the cartridge list needs to be adjusted. Please follow the Concept - Customization - Deployment - ICM 11+ to add the IOM Connector cartridges to that list.

References

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.

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