IBM Sterling OMS Starter Kit by Kibo eCommerce

Configuration Guide

Current Version: 1.0.0 (April 2016)
More Info: Version History

IBM’s Sterling OMS provides enterprise retailers with a centralized, cross-channel order processing, fulfillment, and inventory platform.

The IBM Sterling OMS Starter Kit by Kibo eCommerce is a baseline integration that allows enterprise retailers to capture ecommerce orders from a Kibo eCommerce site, then process and fulfill those orders with an IBM Sterling OMS implementation. The starter kit synchronizes all order fulfillment and inventory information between platforms.

Note: The code for this application is provided as a starting point for a custom integration. Kibo eCommerce does not guarantee support for this starter kit in any way.

Starter Kit Features

Starter Kit Prerequisites

In order to successfully use the starter kit, you must meet the following prerequisites:

Dev Center Setup

In order for the starter kit to communicate with your Kibo eCommerce tenant, you must first setup your Dev Center account and prepare it for the starter kit application.

Dev Center allows your starter kit application to communicate with Kibo eCommerce.

Complete the following steps to setup your Dev Center account and prepare it for the starter kit application:

1. Create a Dev Center Application

This Dev Center application is a container that facilitates communication between Kibo eCommerce and the starter kit application.

  1. Log in to Dev Center.
  2. Click Develop > Applications.
  3. Click Create Application.
  4. In the Create application dialog box, do the following:
    1. In the Name text box, enter a user-friendly name for the application, such as IBM Sterling.
    2. In the Application ID text box, enter an id for the application, such as ibm_sterling.
      Kibo eCommerce appends the Application ID to the reverse domain name for your Dev Account. The allowed characters include numbers, letters, and underscore.
    3. Click Save.

2. Prepare an Endpoint

Since this is a starter kit, you must host the application on your own web server and then point Dev Center to the URL endpoint where your IBM Sterling application listens for events.

  1. Prepare a web server that will host your IBM Sterling application.
  2. Note the URL endpoint of the IBM Sterling application configuration page, such as https://<Domain>/<IBMSterlingApp>/configure.
  3. In (Undefined variable: Variables.DevCenterNalome), open the IBM Sterling application details page.
  4. Click Packages, and then click the Details tab.
  5. Under Configuration URL, add the URL endpoint of the IBM Sterling application configuration page.

3. Subscribe to Events

You must tell Dev Center which Kibo eCommerce events to which it must listen, such as order create or order update.

  1. In the Application grid, double-click the IBM Sterling application you just created.
  2. Click Packages.
  3. On the Events tab, click Add Event Subscription.
  4. In the Endpoint text box, add the URL endpoint where your IBM Sterling application listens for events, such as https://<Domain>/<IBMSterlingApp>/events.
  5. In the Event category list, select Application.
  6. In the Event list, select all application events.
  7. In the Event category list, select Order.
  8. In the Event list, select all order events.
  9. Click Save.

4. Register Behaviors

Behaviors grant the application permission to complete specific actions in Kibo eCommerce.

  1. In the Select Behaviors dialog box, under Behavior category, select Order.
  2. Select all Order behaviors, except Order Delete.
    The IBM Sterling application does not delete orders in Kibo eCommerce.
  3. Click Save.

5. Install the Application to a Sandbox

Installing the Dev Center application to a sandbox allows to you properly test configuring the application in a Kibo eCommerce tenant.

  1. In the Application editor, click Install.
  2. Select your IBM Sterling application and click OK.
  3. Click Sandboxes. Right-click the appropriate sandbox and click View.
  4. In Admin, click System > Applications.
  5. Verify that the IBM Sterling application appears in the list.
  6. Double-click the application and click Enable App.

Build the Starter Kit

Kibo eCommerce provides the starter kit as a starting point for a custom integration; therefore, you will need to download the source code, modify it as necessary, and then build and host it on your own web server.

1. Obtain Source Code

Before you can build the starter kit, you'll need to obtain the source code:

  1. Go to https://github.com/Mozu/IBMSterling.
  2. Clone the repository on your local computer.

The starter kit is built on Java. Kibo eCommerce recommends modifying the starter kit source code to suit your purposes using a Java based IDE, such as the Eclipse IDE for Java Developers.

2. Kibo eCommerce Configuration File

The starter kit includes a configuration file, which configures the starter kit to interact with Kibo eCommerce and Dev Center, as well as your job scheduler.

The configuration file is located in your local repo at: root/src/main/resources/mozu_config.properties.

Refer to the following table for information about the required fields and their values of the configuration file:

Field Value
ApplicationId The application's Application Key found in the application details page in Dev Center.
SharedSecret The application's Shared Secret found in the application details page in Dev Center. Note:  Kibo eCommerce recommends encrypting this shared secret. Refer to Encrypt the Shared Secret for more information.
BaseAuthAppUrl The Kibo eCommerce URL to which your application connects, most likely https://home.mozu.com.
spice The salt/spice key that is hashed together with the application's shared secret to create an encrypted shared secret. Refer to Encrypt the Shared Secret for more information.

Configuration File Example

# PROD
ApplicationId=a0842dd.ibm_sterling.1.0.0.bob
SharedSecret=Fyq0sbV/9oh7cf/MwCYuEfnUyfocQcZKVqbsFfFV7k9Cqyao6xeC5pe4g7D5oHZT
BaseAuthAppUrl=https://home.mozu.com
spice=o;uhdsfios079sghvuyhydspo;9uhkhaHjtylkjhg
Tip:  While Kibo eCommerce allows authenticating using only an application's shared secret, it is highly recommend that you encrypt the shared secret to prevent unauthorized users and/or applications obtaining access. To learn how to do this, refer to the Kibo eCommerce Java SDK topic.

3. Gradle Build

Once you have the Kibo eCommerce configuration file configured properly, you can then build the starter kit using Gradle. If you already have Gradle installed on your system you can build the application using the gradle build; however Kibo eCommerce recommends using the included Gradle Wrapper (gradlew), because it ensures that the correct Gradle version is used to run the install task. Refer to Chapter 5. The Gradle Wrapper in the Gradle documentation for more information about the Gradle Wrapper.

To build the starter kit using the Gradle Wrapper:

  1. From the root folder, run gradlew build.
    If you don't already have Gradle installed on your system, the Gradle Wrapper automatically installs the correct Gradle version for the starter kit.
  2. Use the WAR file located at: root/build/libs in the following steps.

The included Gradle Wrapper also includes other Gradle tasks that you might find useful. For a complete list of all Gradle tasks, run gradlew tasks

4. Deploy WAR File

The Gradle Wrapper builds a WAR file that you can then deploy on your own Java web server. Kibo eCommerce recommends using an Apache Tomcat web server to deploy the WAR file.

This WAR file is located at: root/build/libs.

Refer to the documentation for your selected web server for more information about configuring the web server and deploying the WAR file.

Once you've successfully deployed the WAR file to your web server, you can use the appropriate URLs in the Dev Center Setup section.

Configure the Starter Kit

Once you've completed the Dev Center Setup and Building the Starter Kit you can configure the starter kit within a Kibo eCommerce tenant sandbox.

Configuring the application's connection settings, site mappings, locations, and shipping settings enable the application to communicate properly with your IBM Sterling OMS.

To can access the application's configuration settings:

  1. In (Undefined variable: AdminName), go to System > Customization > Applications.
  2. Click IBM Sterling OMS Starter Kit by Mozu.
  3. Click the Configuration link:

Complete the following sections to properly configure all the required settings.

Connection Settings

The connection settings configure how the application connects to your IBM Sterling OMS instance and what queue events it listens to in IBM Sterling OMS.

To configure the connection settings:

  1. In the Mozu IBM Sterling Application window, click the Connection tab.
  2. Complete all required fields: Note:  Contact your IBM sales representative if you need help gathering the information in the connection settings.
  3. Click Save.

For example, you can configure the following connection settings:

Site Mapping

Use the Site Mapping settings to properly map your Kibo eCommerce sites to your IBM Sterling OMS seller organizations.

Map each of your seller organizations to their appropriate Kibo eCommerce sites, which you want to be synchronized with IBM Sterling OMS. You are not required to map all seller organizations to a particular Kibo eCommerce site

For example, you can configure the following site mapping:

Refer to the table in the Hierarchy Mappings to help you map these hierarchies to each other.

Locations

Use the Locations settings to properly map your Kibo eCommerce locations to your IBM Sterling OMS shipping nodes.

Map each of your shipping nodes to their appropriate Kibo eCommerce locations, which you want to be synchronized with IBM Sterling OMS. For inventory accuracy, Kibo eCommerce recommends mapping all of the appropriate shipping nodes with their respective Kibo eCommerce locations.

For example, you can configure the following location mapping:

If you do not already have the appropriate locations set up in Kibo eCommerce, you can import them to Kibo eCommerce from your IBM Sterling OMS. To import the locations/shipping nodes from IBM Sterling OMS, click Import and Map Locations in the Locations tab.

Shipping

Use the Shipping settings to properly map your Kibo eCommerce shipping settings (carriers and methods) to your IBM Sterling OMS shipping carriers.

Map each of your shipping carriers to their appropriate Kibo eCommerce carriers/methods, which you want to be synchronized with IBM Sterling OMS.

For example, you can configure the following shipping mapping:

Hierarchy Mappings

The organizational hierarchy you use to model your enterprise in IBM Sterling OMS differs from the organizational hierarchy available in Kibo eCommerce.

Use the following table to help you map these hierarchies to each other:

IBM Sterling OMS Kibo eCommerce
Hub Tenant
Enterprise Master Catalog
Sterling Seller Organization Site
Buyer N/A
Node (Shipping Nodes) Locations
Carrier Shipping Carrier/Method

Enable the App

After configuring the application, enable it in Kibo eCommerce to apply it’s functionality to your tenant:

  1. In Admin, go to System > Customization > Applications.
  2. Click IBM Sterling OMS Starter Kit by Mozu.
  3. Click Enable App.