Introduction

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

Dependency Version Information 

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.
4. Order Details will 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 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.

Glossary

Delivery

The component set f_iomconnector (IOM Connector) is composed of the following cartridges:

• ac_iomconnector_common
• ac_iomconnector_order
• ac_iomconnector_inventory
• ac_iomconnector_orderhistory
• as_iomconnector
• init_iomconnector
• demo_iomconnector

There are also a few test and development cartridges:

• ac_iomconnector_order_test
• dev_iomconnector_reverse_service

References

• Guide - IOM Demo Data Setup for IOM Connector 2.0, 3.0 and 4.0
• Public Release Note - Intershop Order Management 2.1
• System Requirements - Intershop Order Management 2.1
• Public Release Note - Intershop Commerce Management B2C/B2X 7.7
• System Requirements - Intershop Commerce Management B2C/B2X 7.7
• Concept - Managed Service Framework
• Guide - ICM & IOM Configuration Tasks

Feature Overview

Integration

As mentioned before, the IOM Connector is to be set up alongside a standard ICM installation. It adds additional cartridges that define the following managed services:

• IOM Order Service - Exports order data from ICM to IOM
• IOM Order State Service - Changes the order history section in a way that orders' statuses are fetched from IOM whenever the customer requests them
• IOM Download Service - After customers request a return, they will be able to download, or directly print a return slip. This return slip can be downloaded from the link shown on the Prepare Return Documents page.
• IOM Reverse Service - Ensures order cancellation is available to the customer (so customers can even print a return slip, which can be used for order returns)
• IOM Inventory Service - Provides a way to obtain the inventory levels from Intershop Order Management to Intershop Commerce Management and perform product reservations 

The chevrons at the shapes of the services in the diagram below indicate the data communication direction. The picture below illustrates this.

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.

As mentioned before, a couple IOM Services, although not mandatory, are to be created in the context of channel. This way you can ensure that the communication exchange between ICM and IOM is realized on the intended level.

Communication

End Points

The services mentioned in the previous chapter are realized with web services. They are exchanging data between the two systems in a specific format, but they also need to be configured. Web services require an end point that is different for each of them. In the table below you can see the end points, 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 realize this, you must create a user in IOM with permissions necessary 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 grain the permissions for each service as they all will need a user name/password combination.

Should you use prepared demo data (you do not if you do not know what this is) here are some prepared values:

Identifiers

Both systems exchange data so they need a common ground as a base 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

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). As mentioned before, on the configuration page you may tweak the export settings, but we generally use "on order creation" trigger.

The look and feel and the business processes in the standard ICM is 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 and additional information details are exported to IOM upon order placement. They are accessible in the Attributes section.

Mapping

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

A note on shipping and carriers. They're different in their nature. While the sales channels in ICM have shipping methods which are select-able by the customers, IOM "knows" about carriers that execute those shipping methods. For example, in ICM one might have two shipping methods "DHL Express" and "DHL Standard" both of which are covered by single carrier "DHL".

Order History

This feature is governed by the IOM Order State Service. Once this service is configured and activated, the order status information in My Account -> Order history is taken in real time from IOM.

My Account -> Order History	Order search 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 the moment when someone requests their order history. In the table below you find the mapping between order statuses in the two systems.

Payment Statuses

The actual information about payment is very important for our customer. After you submit your order you can see details information about the order in "Order History". When you click on "view" it should show "Order Detail" page with "Payment Section" this section contains details information for your payment status represented with payment statuses (Paid,Part Paid,Not Paid) and progress bar :

The progress bar will be shown in "percent" how much money is remaining to be paid. The customer also should see this information in "Open Invoiced Amount" represented as money ($ 10.25). When the Order is completely paid the customer should see green progress bar with 100% and also $0 in Open Invoiced Amount.

My Account -> Order History ->View	Order Invoice in IOM

Order Return

Return Line Item(s)

Customers are able to trigger returns of orders. Once the order is shipped, and its delivery confirmation is tracked in IOM, its status is changed to shipped. From the order history page, every order that has been shipped can be triggered for return by clicking the Return link. For each individual item, a return quantity and a reason can be specified. Return reasons are requested from IOM and available for selection to the customers.

The required service for order return is IOM Reverse Service. Without it configured and activated, customers will not be able to use this feature.

Print the Return Slip

Once someone has requested a return, they will be able to download, or directly print a return slip. This return slip can be downloaded from the link shown on the Prepare Return Documents page.

As with the rest of IOM features, this one is also realized by using managed service - IOM Download Service. You must configure it first before using it.

Order Documents

This feature allows for the document and note information within the order to be displayed on the Order Details page. The Order Document retrieval from the IOM has a cache handling mechanism that preserves the information for a given time interval. When the order details page loads, a request is sent to the IOM, which in turn responds (if successful) with a report that contains various order information - in that number the order documents/notes. Then the documents and notes are handled accordingly and finally presented in the details page. The documents list is shown when the customer clicks the "View All" link at the bottom left side of the page. The info shown about the documents consists of: note type (invoice, credit , etc.), note creation date/time and a link for the document to be downloaded from. Also when the Download button is clicked that activates the download of the document. The badge on the right hand side of the "View all" link shows the actual number of documents which are available for viewing/downloading.

After downloading the document/note should look similar to the example shown below:

And the "see all" dialog box link as shown here:

Inventory Service

The main task that the Inventory Service does is to check the product availability status for a particular product in IOM. IOM Inventory Service performs in real time, but at the same time it supports caching of the results for a given time interval (e.g., 5 seconds). When the page with the customers desired product is open, the Inventory Service sends a request to IOM that asks for the ATP (available to promise) status. If the product is available then the customer will see the button Add to Cart and a field in which to specify the desired quantity of the product. On the other hand, if the product is not available, on the screen will be shown the following: a button with the text Notify me when available. If in the service configuration the checkbox Availability check on failure is not ticked, then in the case of a problem with the communication with the IOM system, the Simple Inventory Service will be activated and the selected product will be checked for ATP (ICM) in the local database.

Setup

Precondition

IOM Connector release package is available via Intershop's public Nexus server. To add it to your release you must:

1. Set up and configure CI - continuous integration - environment.
   See Cookbook - Setup CI Infrastructure (valid to Gradle Tools 2.7) for details.
   See Concept - Continuous Delivery Tools (valid to 7.10) for basic information about Continuous Integration.
2. Install Intershop Commerce Management matching the system requirements - see section Dependency Version Information.
3. Knowledge of how to add the delivered artifacts to the continuous integration environment.
4. Knowledge of how to deploy to a test or production environment.

The IOM Connector contains parts that are distributed as binary artifacts (see iomConnectorCartridges below) and parts that are distributed as source (see productionCartridges below), so they can be copied and modified easily in a project.

You can retrieve the source cartridges from the public Nexus under com.intershop.public.source.f_iomconnector.

1. As Deployment User: Download the latest version of the IOM Connector component set f_iomconnector.
   http://<your-reposerver:port>/nexus/content/repositories/ish-releases/com.intershop.public.source/f_iomconnector/3.0.0/zips/f_iomconnector-zip-src-3.0.0.zip

2. Unzip and copy the component set contents to your project directory <ProjectHome>/projects/intershop-project /<myCustomComponentset> .

   Long path names on Windows

   On Windows certain tools have trouble dealing with path names longer than 255 characters. When in doubt, please use 7-Zip 15.12 to uncompress the source packages.

3. Edit the gradle.properties in your component set and add the following:

   # dependency versions
   ...
   version.com.intershop.services.iomconnector.ac_iomconnector_common = 3.0.0
   version.com.intershop.services.iomconnector.ac_iomconnector_order = 3.0.0
   version.com.intershop.services.iomconnector.ac_iomconnector_inventory = 3.0.0
   version.com.intershop.services.iomconnector.init_iomconnector = 3.0.0
   ...

4. Update dependency declarations of cartridges you've received as source: ac_iomconnector_orderhistory, as_iomconnector and demo_iomconnector.

   1. Change build.gradle of ac_iomconnector_orderhistory

      Find	Replace with
      compile project(':ac_iomconnector_common')	compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_common'
      compile project(':ac_iomconnector_order')	compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_order'

   2. Change build.gradle of as_iomconnector

      Find	Replace with
      compile project(':ac_iomconnector_common')	compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_common'
      compile project(':ac_iomconnector_order')	compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_order'
      compile group: 'com.intershop.responsive', name: 'as_responsive_b2b'	compile project(':as_responsive_b2b')

   3. Change build.gradle of demo_iomconnector

      Find	Replace with
      compile project(':ac_iomconnector_common')	compile group: 'com.intershop.services.iomconnector', name: 'ac_iomconnector_common'

5. Re-publish your component set.

Configure the Assembly

To add IOM Connector you may either:

1. Include the IOM Connector's cartridges into an existing assembly.
   

   • Open the file build.gradle of your assembly, add a list of IOM Connector's cartridges in assembly directive and include this list into assembly's cartridges

     build.gradle

     assembly {
     ...
     	cartridges {
             def iomConnectorCartridges = [
                 'ac_iomconnector_common',
                 'ac_iomconnector_order',
                 'ac_iomconnector_inventory',
                 'init_iomconnector',
             ]
             
             include (*(iomConnectorCartridges.collect {"com.intershop.services.iomconnector:$it"}), in:[development, test, production])
         
             def productionCartridges =
             [
     			'<your-cartridge1>',
     			'<your-cartridge2>',
                 'ac_iomconnector_orderhistory',
                 'as_iomconnector',
                 'demo_iomconnector'
             ]
     
             include (*(productionCartridges.collect {"<your-assembly-group>:$it"}), in:[development, test, production])		
     
             order = listFromAssembly('<your-assembly>') + storefrontCartridges + iomConnectorCartridges + productionCartridges + initCartridges + developerCartridges + testCartridges
         }
     ...
     }

   • In the same build.gradle file add add the following two cartridges to assemblyBuild.database .

     assembly {
         ...
     }
     
     assemblyBuild {
         database {
             inherit('<your-assembly>')
             initCartridges =
             [
                 'ac_iomconnector_common',
                 'demo_iomconnector',
                 'init_iomconnector'
             ]
         }
     }

2. Alternatively, you can create a new assembly inheriting from an Intershop Commerce Management-based assembly.

   For details about creating a new assembly, see Recipe: Create a New Assembly Inheriting From an Existing Assembly.

3. Exclude conflicting versions from the assembly build.

   Add the following directive at the end of build.gradle file of your assembly. If you already have defined configurations.all directive just enrich it with the excludes listed below.

   build.gradle

   configurations.all {
       exclude group: 'org.apache.geronimo.specs', module: 'geronimo-activation_1.1_spec'
       exclude group: 'org.apache.geronimo.specs', module: 'geronimo-jta_1.1_spec'
       exclude group: 'org.apache.geronimo.specs', module: 'geronimo-javamail_1.4_spec'
       exclude group: 'org.apache.geronimo.specs', module: 'geronimo-stax-api_1.0_spec'
       exclude group: 'stax', module: 'stax-api'
       exclude group: 'asm', module: 'asm'
       exclude group: 'javax.servlet', module: 'servlet-api'
   	exclude group: 'org.apache.ws.commons.schema', module: 'XmlSchema'
    }

4. Define version directives for IOM Connector cartridges.
   Open gradle.properties of your assembly and add following lines:

   # IOM binary delivered cartridges (Nexus)
   version.com.intershop.services.iomconnector.ac_iomconnector_common = 3.0.0
   version.com.intershop.services.iomconnector.ac_iomconnector_order = 3.0.0
   version.com.intershop.services.iomconnector.ac_iomconnector_inventory = 3.0.0
   version.com.intershop.services.iomconnector.init_iomconnector = 3.0.0
   
   # IOM source delivered cartridges (local)
   version.com.intershop.responsive.ac_iomconnector_orderhistory = YourAssemblyVersion-local
   version.com.intershop.responsive.as_iomconnector = YourAssemblyVersion-local
   version.com.intershop.responsive.demo_iomconnector = YourAssemblyVersion-local

5. Define a unique order sequence.
   Both Intershop Commerce Management and Intershop Order Management assign an unique identifier to any order placed in the corresponding system. These identifiers are often referred to as "order document number" or "order ID". In order to have a seamless integration between the two systems you must synchronize these identifiers. Since ICM has the "leading role" as the orders are created and submitted from customers in the web shop, system administrators need to apply an additional configuration to the order number generation.
   IOM Connector requires an order number generation that provides unique order numbers for both systems.
   If you are deploying IOM Connector with ICM and IOM anew, in other words you have no orders placed in both systems, it is safe to skip this step. However, you may want to define unique order sequence just in case. All you need to do is to negotiate a starting number with all parties involved and then add a deployment step that alters /share/system/config/cluster/database.properties file, namely the property intershop.sequence.startsWith. Open settings.gradle of your assembly and add following lines:

   settings.gradle

   deployment {
       ...
       filters {
           overrideProperties('uniqueOrderSequence') {
               dir = target.shareDirectory
               include 'system/config/cluster/database.properties'
               properties['intershop.sequence.startsWith'] = <negotiated-order-sequence>
           }
       }
   }

   For more details about see Recipe: Change Deployed File Content With Filters.

   For details about adding new configuration files, see Recipe: Deploy Custom Files.

Deploy the Assembly

After creating and appropriately configuring the assembly, you must deploy it to the intended target environment.
For details about deploying an assembly, see Recipe: Run the Deployment (Initial Installation / Upgrade / Downgrade)

Initialize the Database

You must run a database initialization to use the IOM connector.

DBInit is necessary for the following cartridges:

• ac_iomconnector_common
• demo_iomconnector
• init_iomconnector

To execute full database initialization use:

gradlew dbinit

To execute the database initialization use on selected set of cartridges:

dbinit -t=ac_iomconnector_common,demo_iomconnector,init_iomconnector

References

For details about managing assembly artifacts, see:

• Concept - Gradle Assembly Tools
• Reference - Gradle Assembly Tools
• Cookbook - Gradle Assembly Tools (valid to 7.8)
• Concept - Managed Service Framework
• Guide - ICM & IOM Configuration Tasks

Configuration

In order to deploy IOM Connector with Intershop Commerce Management, you do not need to configure anything.

For a proper interaction of the two systems (IOM and ICM), however, some configuration is necessary. For more detailed information on how to do this, refer to Guide - ICM & IOM Configuration Tasks.

Additionally in order to get the IOM working with the ICM 7.7 demo scenario (inSPIRED storefront) specific demo content needs to be uploaded into the IOM. The description and the content can be found here: Guide - IOM Demo Data Setup for IOM Connector 2.0, 3.0 and 4.0

Limitations

Application Management

• Use only one currency per application.
• Use only one shipping method per order.
• Do not use surcharges.
• Use only promotions that affect line items, e.g., discounts on line item.

Product Information Management

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

Synchronize Order Numbers

Both Intershop Commerce Management and Intershop Order Management assign an unique identifier to any order placed in the corresponding system. These identifiers are often referred to as order document number or order ID. In order to have a seamless integration between the two systems you must synchronize these identifiers. Since ICM has the "leading role" as the orders are created and submitted from customers in the web shop, system administrators need to apply an additional configuration to the order number generation.

1. Go to <server-installation-dir>/local/bin and execute environment.<bat|sh>.

   ./iomconnector/server/local/bin/environment.sh

2. Go to <server-installation-dir>/local/tools/misc and execute ant export-sequence-info -f database.xml.

   [/iomconnector/server/local/tools/misc]# ant export-sequence-info -f database.xml
   Buildfile: /iomconnector/server/local/tools/misc/database.xml
   dbenvironment.environment.decrypt:
   dbenvironment.environment:
   environment:
   export-sequence-info:
         [sql] Executing commands
         [sql] 1 of 1 SQL statements executed successfully
         [sql] Executing commands
         [sql] 1 of 1 SQL statements executed successfully
   log:
        [echo] [02/17/2016 03:20:56 PM] The used enfinity specific sequence informations were successfully exported to file 'sequences-info.properties'.
   BUILD SUCCESSFUL
   Total time: 2 seconds

3. In <server-installation-dir>/local/tools/misc open the newly generated file called sequences-info.properties.
   It looks like:

   #,LAST_NUMBER,INCREMENT_BY,SEQUENCE_NAME,DOMAIN_SPECIFIC,DOMAINNAME,IDENTIFIER
   #,51,10,SQHHBAQDGBYQAAAAFUCBLM4M0_,TRUE,inSPIRED-inTRONICS,SellerOrder.DocumentNo.NfsKAB1PpEUAAAFTFT89kGWR
   # Largest last_number is: SellerOrder.DocumentNo.NfsKAB1PpEUAAAFTFT89kGWR - inSPIRED-inTRONICS
   #intershop.sequence.blockSize  = 10
   #intershop.sequence.startsWith = 51

   Memorize or write down the number of intershop.sequence.startsWith and intershop.sequence.blockSize.

4. Log into IOM.
   Go to http://<iom-server-url>/bakery.omt/app/start and log in user your credentials.
   
5. Click on Orders or perform an order search .
   
6. Memorize or write down the biggest order number in the list.
   
7. Define unused order sequence.
   You have a lot of options, but they all should comply to one rule - A new order sequence should be unique for both systems now and in the future.
   It is advised to just pick the bigger number between biggest order ID taken from IOM's orders list and the intershop.sequence.startsWith taken at step 3. You may also add a date prefix to the order number, or put a unique machine identifier, as long as it contains only numbers.
   In this example, ICM's order ID is 51 and IOM's - 20160128017063. Bigger one is 20160128017063. So add the value of intershop.sequence.blockSize to it - 20160128017063 + 10 = 20160128017073 - and then add 1. The end result is 20160128017074.
8. Go to <server-installation-dir>/share/system/config/cluster, open the file database.properties.

9. Remove # from line intershop.sequence.startWith= and change its value to the unused order sequence determined in step 7.

   ################################################################################
   ##
   ## Series (Sequence) Creation Options
   ##
   ##
   ## series numberPattern settings
   ##
   #intershop.sequence.numberPattern=00000000
   ##
   ## blockSize  - "increment by <n>"
   ## startsWith - "start with <n>"
   ## cacheSize  - "cache <n>" or "nocache" if <n> = 0
   ## orderFlag  - "order" if true or "noorder" if false
   ##
   #intershop.sequence.blockSize=50
   intershop.sequence.startsWith=20160128017074
   #intershop.sequence.cacheSize=0
   #intershop.sequence.orderFlag=true

Changelog

Version IOM Connector 3.0.1

• Fix: ISEM-1945 - RuntimeExceptions lead to invalid order state (“exported”) RuntimeExceptions lead to invalid order state "exported"
• Fix: ISEM-1946 - Orders may be exported with the wrong shop customer number Orders may be exported with the wrong shop customer number
• Fix: ISEM-1947 - Invalid tax configuration might cause NPE in TaxClassResolverImpl Invalid tax configuration might cause NPE in TaxClassResolverImpl