Implementation Guide

Whether implementing a new Kibo client or migrating from an existing eCommerce or Order Management solution, certain steps must be taken to implement the Unified Commerce Platform with all of the configurations and data necessary to maintain catalogs and handle orders.

This guide offers a breakdown of each pieces of the implementation, highlighting some of the differences between Unified Commerce and the classic Order Management solution, as well as notes indicating which team is responsible for each step:

  • Client/SI (Systems Integrator, sometimes may be Kibo Professional Services)
  • Kibo Professional Services (PS)
  • Kibo Engineering/Developers
  • Third Party

Upgrading from OMS

The following list is a summary of the currently known changes to be aware of between the previous version of OMS and Unified Commerce, specifically for a client upgrading to use only the order management side of UCP. These are expanded upon further in the relevant sections of this guide.

  • Authenticate for Unified Commerce APIs with a new endpoint using OAuth 2.0 JWT
  • Inventory networks no longer exist; instead, locations are organized into groups
  • Inventory import files have a new naming format and can be exported through S3 as well as SFTP
  • Location settings include new configuration options
  • API calls and some interfaces reflect renamed fields, such as catalogs now being called sites
  • There is no longer a Manufacturer or Retailer UI – just Order Admin, Order Routing, Inventory, and Fulfiller

Locus of Work

The responsibilities for each party are listed here:

  • Accounts and Credentials: Client/SI + Kibo PS + Kibo Support  
  • API Implementation: Client/SI + Kibo PS   
  • Catalog and Product Data: Client/SI + Kibo PS
  • Inventory: Client/SI + Kibo PS
  • Locations: Client/SI + Kibo PS
  • Location Groups: Client/SI + Kibo PS
  • Payment: Client/SI + Kibo PS + Third Party Payment Providers
  • Shipment: Client/SI + Kibo PS
  • Fulfillment: Client/SI + Kibo PS + Kibo Engineering
  • Order Routing: Client/SI + Kibo PS
  • Transaction Logs: Client/SI + Kibo PS + Kibo Engineering
  • Event Notifications: Client/SI + Kibo PS
  • Customer Accounts: Client/SI + Kibo PS 
  • Customer Messaging: Client/SI + Kibo PS
  • Customer Care: Client/SI + Kibo PS + Customer Service Representatives
  • Training: Client/SI + Kibo PS + Kibo Technical Writers
  • Testing: Client/SI + Kibo PS + Kibo Engineering
  • Launch: Client/SI + Kibo PS + Kibo Engineering

Accounts and Credentials

The client will receive keys for any test accounts and sandboxes, and then the required credentials for production accounts when ready to launch. 

A new standard authentication mechanism using OAuth 2.0 JWT is now supported, with the access token being obtained from /api/platform/applications/authtickets/oauth as outlined in the documentation. The Inventory, Fulfillment and Order Routing services only accept this JWT bearer token in the header.

The implementation responsibilities are:

  • Client/SI: Adds/invites users
  • Kibo Professional Services: Submits ticket for Support to create accounts
  • Additional Resources: Kibo Support creates clients and sends out invite

API Implementation

Clients are only responsible for the development work required to implement custom Kibo API implementations. Kibo Professional Services will assist in designing the best integration plan to meet business needs, and supports clients using APIs.

The implementation responsibilities are:

  • Client/SI: Works with Kibo PS to generate integration map/API workflow, implements all relevant APIs, and tests all APIs against test account(s)
  • Kibo Professional Services: Provides support for API implementation 

Catalog and Product Data

If Unified Commerce is being implemented with the front-end eCommerce solution, then all accounts must have at least one catalog in which the product data and pricing information is maintained and settings such as supported fulfillment methods or payments are enabled. 

If implementing an OMS-only instance of Unified Commerce, this step may be skipped as a catalog is not part of the order management solution – only inventory data is utilized in that case.

The implementation responsibilities are:

  • Client/SI: Define product catalog structure
  • Kibo Professional Services: Team configures individual catalog settings for fulfillment, language, payment, messaging, user login, and internal configurations

Managing Inventory Data

Clients import a daily inventory update as a formatted CSV or XML file, as well as provide real-time updates via the APIs through the endpoint /api/commerce/inventory/ as outlined in the documentation.

Note that there is no longer a need to set up inventory networks. The process for configuring the fetch and export settings remains the same as Classic OMS, as does the overall API calls for Inventory Refresh, Update, etc.

The implementation responsibilities are:

  • Client/SI: Requests or provides SFTP or S3 endpoint, requests timing to receive daily export, uploads inventory files in defined format
  • Kibo Professional Services: Configures location and timing for inventory file export, confirms file structure and sets job for export

There are a few changes to note about the inventory management process in Unified Commerce:

  • When importing inventory files, the file names follow a new convention. The name should identify the tenant being imported for, as well as whether its a REFRESH or UPDATE file, e.g. “T_17215_REFRESH_YYMMDDhhmmss.” 
  • There are also several changes to the data parameter names, including that baseProductCode is now PartNumber, variationProductCode is now UPC, manufacturerID is now tenant, locationID is now locationCode, and catalogID is now siteId. See the documentation for the fully updated parameter list.
  • When exporting bulk inventory data, a S3 bucket can be configured as the drop point instead of an SFTP site. However, S3 does not support inventory import so data cannot be uploaded here from the client.
  • The blockAssignment setting can now be set via Inventory API. When true, order routing will not suggest that any shipments with that item be assigned to that location until the inventory record is updated again.
  • Additionally, the Inventory UI is now exposed to administrators, allowing them to manually alter the onHand stock of inventory items.

Locations

Fulfillment locations will need to be imported into Kibo through either manually adding locations in the Admin interface or making calls to the Locations API. This data should include all stores, distribution centers, and third-party drop fulfillment locations. Orders will be able to be assigned to these fulfillment locations based on inventory data and order routing rules. 

The implementation responsibilities are:

  • Client/SI: Sets up locations through the interface or, provides a list of locations if not comfortable configuring them in the interface
  • Kibo Professional Services: Supports loading locations and configuring locations

A few new Boolean fields have been added to location configurations, which are relevant to order management. Once a location has been created, the following options can be set:

  • Express - Indicates whether the location can fulfill express orders.
  • IncludeInInventoryAggregrate – Indicates whether to include a location’s inventory in getAggregateInventory API calls. 
  • IncludeInLocationExport – Location inventory is included in location level inventory export.
  • WarehouseEnabled – Indicates whether the location is also a warehouse.
  • TransferEnabled – Indicates whether a location is eligible to be assigned for transfer orders.

Location Groups

A new concept of location groups and location group configurations is introduced in the Unified Commerce Platform, organizing locations into sets with similar configurations to enhance order routing options. 

Location groups can be managed at the APIs for /api/commerce/admin/locationgroups, and configured through /api/commerce/admin/locationgroupconfiguration.

The implementation responsibilities are:

  • Client/SI: Defines how locations should be grouped, sets up location groups via the Admin Interface or API
  • Kibo Professional Services: Supports the setup of language groups

Location Groups can be associated to one or more Sites, but a Site cannot use Location Groups that have overlapping Locations (such as Location Group 2 and 3 in the below diagram). This allows a database of locations to be created for multiple sites, but only exposed to the sites that they can fulfill for.

Chart illustrating how sites map to location groups and then locations through configurations

Payments

Payment gateways will be configured for each payment type that needs to be supported using client account credentials, including third-party vendors that the client has a relationship with.

Tax overrides can be provided if desired by the client, which will replace the tax cost for each order that would otherwise be calculated by Kibo.

The implementation responsibilities are:

  • Client/SI: Confirms payment auth/capture workflow, specifies tax overrides, manages relationships with unbundled payment gateways, configures payment gateways (such as CyberSource) in Admin UI
  • Kibo Professional Services: Supports client’s gateway configuration and builds new gateways if needed, submits request to engineering to configure payment credentials
  • Third Party: Third-party payment vendors support integration needs

Shipment

Once an order is submitted, at least one shipment is created for the items in the order and assigned to  at least one fulfillment location. All the actions like price modifications, cancellations, fulfillment, and returns happen at this shipment level, so these are done through the Shipment API instead of an Order API as in the Classic OMS platform. These APIs are located at /api/commerce/shipments

The implementation responsibilities are:

  • Client/SI: Manages relationship with shipping providers, maps shipment types (Standard, Express 1-Day, Express 2-Day) to shipment strategies
  • Kibo Professional Services: Completes carrier credentials and location group shipment configuration

Fulfillment

While orders and returns are managed in the Unified Commerce Order Admin, the actual fulfillment of shipments is performed through the Fulfiller UI.

Fulfillers can use either the fulfiller interface application of the Unified Commerce Platform or integrate the Kibo APIs to manage orders. Pick wave functionality can be configured to match client needs (but is now managed through the Fulfillment APIs rather than a separate Pick Wave API).

The implementation responsibilities are:

  • Client/SI: Sets up fulfiller for fulfillment strategy, determines fulfillment plan: via interface or API, edits pick and pack templates,  or provide customize copy if not comfortable with HTML
  • Kibo Professional Services: Customizes pick wave and packing slip templates if needed, supports API integration, requests custom BPM from developers
  • Kibo Engineering: Creates custom BPM and any new order or shipment statuses

Order Routing

Order Routing provides instant order assignment decisions based on inventory, client rules, location data and order data. The benefits of this are that clients can group and prioritize fulfillment locations as well as create order-specific assignment logic based on order attributes. 

The implementation responsibilities are:

  • Client/SI: Identifies business needs to be factored into order routing logic, creates fulfillment workflow diagram, creates order routing rules in the Order Routing interface
  • Kibo Professional Services: Supports clients with the design of order routing business logic, configuring the tool, and creating rules

There are a few changes to note about the order routing process in Unified Commerce, though overall the interface is largely unchanged from its original version with classic Kibo Order Management:

  • The interface is now exposed to client administrators.
  • Catalogs are now called “sites”, so the catalog selector tool has become the site selector.
  • Waiting for Manufacturer Acceptance is now a “Customer Care” route for both Ship to Home and BOPIS (ISPU) orders.
  • Express Orders are no longer a separate route.

Transactional Logs

Transactional logs will be implemented by the Kibo team and provide regular reports of order sales, returns, and so forth. These logs are delivered to the client through an SFTP endpoint.

The implementation responsibilities are:

  • Client/SI: Requests custom fields to be passed via API and included in logs, requests or provides SFTP endpoint, requests access to Datadog if they wish to customize them
  • Kibo Professional Services: Handles request for any custom fields or Datadog credentials
  • Kibo Engineering: Supports log customization requests

Event Notifications

Event notifications are payloads of data that are triggered by “events” in the fulfillment process, providing a record and alert of order updates. These events are the status changes of orders, shipments, and returns as those objects move through different steps in their fulfillment process.

The implementation responsibilities are:

  • Client/SI: Sets up JSON endpoint to receive notifications
  • Kibo Professional Services: Provides support and guidance about the handling and usage of notifications 

Customer Accounts

Customer data will already exist in the database for eCommerce clients that migrate to Unified Commerce. However, an automated process has not yet been set up to import OMS-only clients’ existing customer data.

Customers will be able to view their order history in the storefront. Their Consumer Account view is powered by real-time order status providing tracking information, order splits and Customer Care numbers for sub-orders, as well as any fulfillment status changes (such as items being cancelled or backordered).

The implementation responsibilities are:

  • Client/SI: Imports any existing customer data
  • Kibo Professional Services: Assists with importing and reconciliation of customer data

Customer Messaging

Email notifications are sent to customer to alert them of updates regarding their order, including confirmation, shipment notice with tracking numbers, cancellations, etc. These emails are designed with Hypr templates and customized for each implementation.

The implementation responsibilities are:

  • Client/SI: Confirms requested and suppressed email notifications, customizes email templates through the interface, or provides custom copy and logo if not comfortable editing
  • Kibo Professional Services: Supports configuration of email settings and customizes templates if needed

Customer Care

The Unified Commerce Order Admin Interface allows customer care representatives (CSRs) to place orders using product, catalog, pricing and customer data. All order data is synced to the front-end website and includes the image, description, pricing, and availability of the products. Existing customers can be looked up in the interface, and available shipping methods are displayed on their orders. CSRs can create new orders and calculate tax, shipping costs, and promotions on the customers’ order carts.

The implementation responsibilities are:

  • Client/SI: Provides training for their customer care representatives
  • Kibo Professional Services: Provides any training material for client use

Training

Client training is included with the integration process through Professional Services. These training programs explain the coordinated process and interfaces of each solution.

Training includes the use of the different user interfaces and APIs as appropriate.

The implementation responsibilities are:

  • Client/SI: Requests use cases for training, identifies availability for training design
  • Kibo Professional Services: Coordinates training

Testing

Testing environments are set up in sandboxes, allowing configurations and mock orders to be tested to ensure that the process works as expected and identify errors before updates are released to the production environment, which is the live site that customer orders and real payments are placed on.

The implementation responsibilities are:

  • Client/SI: Completes test plan cases for UAT, places test orders
  • Kibo Professional Services: Provides support for test orders, troubleshoots UAT
  • Kibo Engineering: Provides performance load testing support and troubleshooting where required

Launch

This platform can be launched for either completely new Kibo accounts or as a migration from an existing eCommerce or OMS solution. The most significant difference between these processes is that migrating from existing implementations may require handling data migrations depending on the case and original product (such as moving customer records from a previous OMS instance).

The implementation responsibilities are:

  • Client/SI: Coordinates timeline for launch, follows launch plan
  • Kibo Professional Services: Supports the transition and launch process, tests to the production account copy

Was this page helpful?

YesNo