Guide - ICM and IOM Configuration Tasks (valid to 2.17)

Introduction

Introduction

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 shows version dependencies between those entities.

Below you find some general information about IOM Connector - both technical and business.

In a nutshell, Intershop set up with IOM Connector will affect the following:

  1. Orders placed in the e-commerce shop will be routed to IOM.
  2. Order history, available in My Account section, will show real-time IOM data about orders' statuses.
  3. Order return will be available as feature in said section.

Extended B2B features such as order approval or additional order information are fully compatible with the IOM Connector. Orders will be exported to IOM only after 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 Managed Services framework.

Intershop recommends to create and manage the IOM Services in the context of channels.

Dependency Version Information


IOM ConnectorIntershop Commerce ManagementB2B Extension ModuleIntershop Order Management
1.07.51.22.0
2.07.6-2.1
3.07.7.2.3-2.1
5.07.9-2.2
6.07.10-2.9
6.37.10.17.2-2.15

Glossary

Term

Description

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

References

General ICM Configuration

Multiple Shipping Addresses

Multiple shipping addresses are currently not supported by the IOM Connector.


Assume an order supports multiple shipments, those shipments could be processed from different sources. However, IOM currently only expects single shipping.
The reason behind this is the nature of the business features supported by the Intershop Order Management itself. 

This configuration adjustment is automatically realized with the deployment and database initialization of the IOM Connector. 

You can check either on the checkout pages in the storefront or in the database to see if "Shipping to multiple addresses" is disabled.

Verify the Absence of "Ship to Multiple Addresses" on Checkout Pages

Warning

You need to either configure properly or unshare IOM Inventory Service in order to complete the checkout process.


  1. Go to the storefront.
    Open http://<e-commerce-shop-url>/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewHomepage-Start with your browser.
  2. Order two or more products.

    Use the Express Shop functionality for quickly ordering some products at the homepage.

  3. Go to the Shopping Cart page and click Proceed to Checkout.
  4. Check the Shipping address section and verify that there is no Ship to multiple addresses option.
    Your shop's checkout address page should look similar to the screenshot shown in the left table column below.

    Multiple shipments disabledMultiple shipments enabled

Verify the Absence of "Ship to Multiple Addresses" in the Database

Alternatively to verifying the setting in the storefront, the setting can also be checked in the database. Proceed as follows:

  1. Open a terminal and connect to the database.

    sqlplus <username>/<password>@<connection-info>
  2. Check the default preferences.

    SQL> select defaultvalue from preferencedefinition where preferencename = 'MultipleShipmentsSupported';
    DEFAULTVALUE
    --------------------------------------------------------------------------------
    false
    SQL>
  3. Check the domain preferences.

    SQL> select stringvalue from preference where preferencename = 'MultipleShipmentsSupported';
    no rows selected
    SQL>

    The query shown above will return no rows selected with the default installation scenario of the IOM Connector. If you have changed or customized it in your project, make sure that the return result is false.

ICM 7.5.x Configurations

The following configurations must be considered after the system is set up to Intershop Commerce Management 7.5.x. They must also be maintained during the project duration.

Application Management

Warning

In the standard Intershop Commerce Management there is no way to enforce those rules without customization.
  1. Use only one currency per application.
  2. Use only one shipping method per order.
  3. Do not use surcharges.
  4. Use only promotions that affect line items, e.g., discounts on line item.

Product Information Management

Do not use warranties. IOM has yet to support service product types.

Shopping Cart & Checkout Configuration

Disable pack slip messaging, gift wrapping and messaging and desired delivery date. Those features can be turned on and off for each application in the system individually. For this task you need the permission to manage applications.

Perform the following steps:

  1. Open the application you want to manage.
  2. Click on Shopping Cart & Checkout tab.
    Application's shopping cart preferences will be displayed.
  3. Disable the following settings and click Apply
    • Pack Slip Messaging under Gifting Options
    • Gift Wrapping under Gifting Options
    • Gift Messaging under Gifting Options
    • Desired Delivery Date under Shipping Options

Shipping Configuration

You need to disable shipping instructions for every shipping method that was created in the system.

The following example shows how to disable shipping instructions for Standard Ground shipping:

  1. From the menu bar select Orders | Shipping Configuration.
  2. Click Shipping Methods.
  3. Click on Shipping Method Name or Shipping Method ID to edit the shipping method.


  4. If checked, uncheck the box after Enable Special Shipping Instructions and click Apply.
  5. Repeat steps 3 to 4 for every shipping method.


Create IOM User

It is necessary to create a new user whose credentials will be used to enable communication between IOM and ICM. Said user requires a special permission ShopServiceClient. When configuring ICM managed services, those credentials will be used. Each time a service is called, an attempt is made to identify the ICM to the IOM by using these credentials.

Create a New User in Intershop Order Management

When using the demo data from Guide - IOM Demo Data Setup for IOM Connector, the user will be created automatically.


  1. Go to http://<intershop-order-managment-url>/omt/app and log in as administrator.

    Note

    For earlier versions (below IOM version 2.2) replace omt using bakery.omt

  2. Click Admin and open User Management.
  3. Click Create new user.
  4. Enter the required data and click Create User.

    Active checkbox

    To activate the user, make sure to check the Active checkbox. 

Assign a Role to a User

You need to to assign the role ShopServiceClient to the web service user. This role contains all permissions that are required to act with the IOM web services using the IOM Connector.

  1. Click Admin and open Role Assignments.
  2. At the Role Assignments click on the newly created user

  3. Click Assign new role.
  4. Assign the role ShopServiceClient to this user at the given organization and click Assign Role.
    1. Select the role ShopServiceClient.
    2. Select the organization(s) where the role should be assigned too.
    3. Click Assign Role.

ICM Service Configuration

The communication between ICM and IOM is realized by utilizing Concept - Managed Service Framework. As with any managed service the following tasks must be performed for IOM-specific services to become operational:

  1. Enable the managed service in the Operations back office.
  2. Create a managed service configuration in the context of a channel.
  3. Fill out the necessary configuration directives.

Once the IOM-Connector is installed, step 1 and 2 can be done with scripts. Afterwards the configuration has to be entered manually into the individual Managed Services. Alternatively, you can also perform these steps completely manually.
Therefore refer to the ICM Online Help for basic information on how to enable a managed service and how to create a managed service configuration.

This information is also available as PDF, e.g., Intershop Commerce Management - Managing Online Shops. See chapter Operation and Maintenance section Services Management.

Note

This document assumes that the setup process of Intershop Commerce Management with IOM Connector extension and Intershop Order Management has been completed and both system are started.

With one exception, all of the managed services require the shop's name in order to function. The exception is IOM Inventory Service which requires the actual shop ID. In order to get the required information ask your IOM database admin to provide you with the result of the following query:

OmsDB=# select ID,name from "ShopDO";

The result should look similar to the one below.

  id   |        name
-------+--------------------
     0 | All Shops
     1 | OMS internal Shop
 10000 | inTRONICS
 10001 | inTRONICS Business

(4 rows)

When you configure one IOM Order Service, IOM Download Service, IOM Order State Service or IOM Reverse Serivce enter the shop's name in the configuration field Shop Name, e.g. inTRONICS.
When configuring IOM Inventory Service you must enter the actual shop ID, e.g. 10000, as configuration value of Shop ID.


Configure IOM Order Service

Note

Deprecated since IOM Connector 6.3

Starting with IOM Connector 6.3 the new IOM Order Export Service is available. This service replaces the IOM order Service. Both services should not be active at the same time.

IOM Order Service requires several technical attributes that must be configured. In general, they control the connection settings to the IOM. Ask your system administrator if you do not have them at hand. Those settings include:

ParameterDescriptionExample
Endpoint

The URI of the IOM order webservice.

Since IOM Connector 5.0 use http://<myhost>/webservices/OrderService/v1.2

http://<your-iom-server>/webservices/OrderService/v1.2
UsernameAn authorization combination against IOM. The IOM's user that is authenticated with these credentials must have the permission to use web services in IOM.consumer_ws
Password!InterShop00!
Shop NameThe name of the shop as used in the IOM.inTRONICS
TimeoutRequests to IOM consume time. This setting determines after how many milliseconds a given request will be aborted automatically.90000
OrderMessageQueueHandlerConfig
Enable the OrderMessageQueueIf set to true, the communication between IOM and ICM will be logged in the database. Database administrators can extract those records.true
Delete Non-Error recordsIf the communication operation completes with success, i.e., the order has exported successfully, enabling this option will trigger automatic deletion of this record.true
Log Request Messages on ErrorSet to true to enable logging of errors to the system error log (usually located on the file system).true

Logging and Monitoring sections are inherited from the standard managed service configuration. You may skip them at the moment.


Configure IOM Order State Service

Note

Deprecated since IOM Connector 6.3

Starting with IOM Connector 6.3 the new IOM Order History Service is available. This service replaces the IOM Order State Service. Both services should not be active at the same time.

The IOM Order State Service requires several technical attributes that must be configured. In general, they control the connection settings to the IOM. Ask your system administrator if you do not have them at hand. Those settings include:

ParameterDescriptionExample
EndpointThe URI of the IOM order state webservice.http://<your-iom-server>/webservices/OrderStateService/v1.0
UsernameAn authorization combination against IOM. The IOM's user that is authenticated with these credentials must have the permission to use web service in IOM.consumer_ws
Password!InterShop00!
Shop NameThe name of the shop as used in the IOM.inSPIRED
TimeoutRequests to IOM consume time. This setting determines after how many milliseconds a given request will be aborted automatically.90000

Logging and Monitoring sections are inherited from the standard managed service configuration. You may skip them at the moment.

Configure IOM Download Service

Configure at least the following properties for the IOM Download Service:

ParameterDescriptionExample
EndpointThe URI of the IOM download web service.http://<your-iom-server>/webservices/DownloadService/v1.0
UsernameCredentials for user authentication and authorization in IOM. The user must have the permission to use the service.consumer_ws
Password!InterShop00!
Shop NameThe name of the shop as used in the IOM.inTRONICS
TimeoutRequests to IOM consume time. This setting determines after how many milliseconds the given request will be aborted automatically.90000

Logging and Monitoring sections are inherited from the standard managed service configuration. You may skip them at the moment.

Configure IOM Reverse Service

Note

Deprecated since IOM Connector 6.3

Starting with IOM Connector 6.3 the new IOM RMA Service is available. This service replaces the IOM Reverse Service. Both services should not be active at the same time.

The IOM Reverse Service requires several technical attributes that must be configured. In general, they control the connection settings to the IOM. Ask your system administrator if you do not have them at hand. Those settings include:

ParameterDescriptionExample
EndpointThe URI of the IOM reverse web service.http://<your-iom-server>/webservices/ReverseService/v1.0
UsernameAn authorization combination against IOM. The IOM's user that is authenticated with these credentials must have the permission to use web services in IOM.consumer_ws
Password!InterShop00!
Shop NameThe name of the shop as used in the IOM.inTRONICS
TimeoutRequests to IOM consume time. This setting determines after how many milliseconds a given request will be aborted automatically.90000

Logging and Monitoring sections are inherited from the standard managed service configuration. You may skip them at the moment.

Configure IOM Inventory Service

Note

Since IOM Connector 2.0

Configuring the IOM Inventory Service is only necessary when using the 2.0 Connector (or later) alongside with IOM 2.1 and ICM 7.6.

The IOM Inventory Service provides a way to communicate inventory levels from Intershop Order Management to Intershop Commerce Management. ICM and IOM exchange inventory information via HTTP and thus some necessary communication parameters must be established before the service is activated:

Parameter

Description

Example

IOM REST Services URL

Base URL of the IOM REST services.

http://<your-iom-server>/servlets/services/

Username

An authorization combination against IOM. The IOM's user that is authenticated with these credentials must have the permission to use web services in IOM.

consumer_ws

Password

!InterShop00!

Shop ID

The ID of the shop as used in the IOM.

Note

You need the actual shop-ID for this service and not the name of the shop as provided for the other IOM Managed Services.

10000

Configuration parameter

Description
Global cacheEnables caching of responses for 5 secondstrue
Availability check on failureIf there is an error with service execution, e.g., network problems, configuration failure, it checks the "available" flag of a product instead.true
Configuration parameterDescription
Reservation Type

The reservation type:

  • COMPLETE = products are only reserved if all products of the request are reservable (default)
  • PARTLY = products are reserved, even when one or more of the reserved products are not reservable.
COMPLETE
Reservation lifetime

The lifetime / validity of the stock reservation in seconds. Max value is 2147483647.
Bigger values create a response with HTTP status code 400 caused by a JsonParseException.

Default is 10 minutes.

-

After the IOM Inventory Service is configureddelete or unshare the standard Inventory Service.
If you do not unshare or delete the standard Inventory Serivce, you will put several processes at risk, since the system is unable to determine which inventory service to use.

Info

You might as well deactivate it, but since it is shared to the channel's application by default, the applications will still use it. Therefore it must be unshared from those applications or deleted altogether. 

Configure IOM RMA Service

Note

Since IOM Connector 6.3

Configuring the IOM RMA Service is only necessary when using the 6.3 Connector (or later).

The IOM RMA Service requires several technical attributes that must be configured. In general, they control the connection settings to IOM. Ask your system administrator if you do not have them at hand. Those settings include:

ParameterDescriptionExample
EndpointThe URI of the IOM RMA REST service.http://<your-iom-server>/rest/rma
UsernameAn authorization combination against IOM. The IOM's user that is authenticated with these credentials must have the permission to use web service in IOM.consumer_ws
Password!InterShop00!
Shop NameThe name of the shop as used in the IOM.inTRONICS
TimeoutRequests to IOM consume time. This setting determines after how many milliseconds a given request will be aborted automatically.90000

Logging and Monitoring sections are inherited from the standard managed service configuration. You may skip them at the moment.

Configure Order Export

Configure ICM Order Export

Once IOM Order Service is configured and activated, the ICM order export has to be configured. Using this scenario will route orders to IOM.

As a prerequisite of this task is one must have completed Configure IOM Order Service.

  1. Switch to your preferred channel in Intershop Commerce Management.
  2. Click DATA VIEW (one of the major tabs in the header).
  3. Click Orders | Import & Export.
  4. In the Order Export section click New to create a new order export.

  5. Enter Name, Description and select a Configuration Type, i.e. IOMOrderService.

    The available options for Configuration Type are depend directly on the created services of type IOM Order Services. I.e., you have as many options here as you have created services. It is recommended to manage only one service of a type in order to avoid confusion.

  6. Click Apply.

  7. Click Actions and configure how the order and line items status should change.
    Configuration on this page will trigger upon successful order export.
  8. Click Scheduling and configure when the order export should be triggered.
    For example select On Order Creation to export the order immediately when it is captured.

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.