OMS Connector Integration Architecture

This integration diagram shows a high-level overview of how the Connector integrates Magento Commerce and the Order Management System (OMS).

MC to OMS connection diagram

Modules

The following modules exist in the Connector to assist with integrating Magento Commerce and OMS:

  • Catalog module—Keeps product updates in sync with the OMS
  • Inventory module—Keeps inventory stock updates in sync with the OMS
  • Sales module—Sends new orders, order updates, and shipment updates to the Magento OMS
  • Post Sales module—Manages returns and refunds

Functionalities disabled/modified by the Connector

Out-of-the box, Magento provides an implementation of order management and inventory management tools, which may conflict with implementations of the Magento OMS. The following are standard Magento Commerce functionalities that are disabled or modified by the Connector.

Disabled functionalities

To avoid conflict between implementations, and stick to a “single data storage” concept, some of the Magento features are disabled or switched to read-only mode.

The following functionalities are disabled or read-only:

  • Order management—After an order is sent to the OMS, no order status changes will be processed by Magento Commerce. All changes will be initiated from the OMS.
  • Inventory management—You will not be able to change product quantity and stock status through the Backoffice. Stock status and product quantities are fully controlled by the OMS. For development and testing environments, it is possible to edit the stock manually in Magento Commerce Admin if Developer mode is enabled. If your catalog contains virtual products that don’t require stock management you can configure the product to have Stock Management disabled in the Magento Commerce Admin.
  • Shipping and payments methods—Shipping methods will synchronize automatically with your OMS via the magento.catalog.product_management.updated message. Then the shipping method is created as a SKU in your OMS catalog. For more information, check the Synchronize shipping methods page.

Modified functionalities

The following functionalities are modified:

  • The default stock values are ignored. All stock information is taken from the newly created stock aggregates (Stores > Stock Aggregates). To see th correct stock information in the product page, select the correct store view.
  • The quantity information displayed in the product grid is taken from the first stock aggregated that is found. Upon filtering the store view, the quantity will reflect the values from the associated aggregate to the store.
  • The order cancelation will first request the OMS to validate if the order is cancellable, will cancel it in the OME, and will update the newly canceled status in Magento Commerce to ensure the status of the order is consistent across both systems.
  • There is a new Export full catalog option visible in the product grid page, which will export the entire catalog to the OMS.

Integration points

The following integration points and areas have been implemented using the Shared Services approach/infrastructure.

Catalog integration point

Magento or a PIM system, as a catalog provider, should send generic product information to OMS - SKU, Name, and basic pricing. The product information is needed to validate information for the imported orders. If an order includes a SKU that don’t exist in the OMS catalog, the order will be rejected.

By default, the Connector will export to OMS a new product created or any product update made to any of the following attributes:

  • Name
  • Sku
  • Description
  • Short description
  • Any of the custom attributes configured for the export

Every time there is a product update, a new message (magento.catalog.product_management.updated) is sent to your OMS. Catalogs that are imported via CSV file will be exported to the OMS in batches of 5000 messages, so there might be a delay in seeing the products created in the OMS system.

In the Magento Commerce Admin you can trigger a full catalog export from Products > Catalog that might be useful to initiate a first synchronization after the full catalog import (this process is not meant to be used for regular updates).

Catalog

Product custom attributes

You can define, from the Magento Commerce Admin, which are the product custom attributes that should be exported to the OMS.

Order custom attributes

Inventory integration point

Magento should support multiple stocks for use in different stock aggregates on different websites. One Magento website can be assigned only to one stock aggregate, but one stock aggregate can be used by a few websites.

The OMS is responsible for aggregating and calculating stock information for each Magento stock.

Diagram Stock aggregates

A new page is available in the Magento Commerce Admin to configure the stock aggregates, in MCOM > Manage Stock Aggregate.

Stock aggregates interfaces

Every time a new stock update is sent from the OMS to Magento Commerce the quantity for each SKU will be reset to zero and then updated with the values provided in the message (if an SKU was not present in the message it will be automatically set to zero and out of stock).

The Connector will also update the Stock Status field as follows:

  • If the quantity > 0 the status will be “in stock” and will be visible in the frontend.
  • If the quantity <= 0 the status will be set to “out of stock” and will not be visible on the frontend.
  • If any of the products have been configured in the OMS to have “unlimited” stock, then upon the message reception, Magento Commerce will update the Manage Stock field to No. If the “unlimited” stock is not provided for a SKU that already has been set, for “unlimited”, the Manage Stock flag will remain set to No.

Advanced Inventory in MC

Order integration point

Magento will prepare and send all authorized orders to the OMS. By default, all orders with a pending status are exported asynchronously.

You can define specific order statuses that should be exported to the OMS, if there is a custom order flow that needs to make several checks to ensure the order is correctly authorized, via a configuratino setting.

Order status export

The OMS will notify Magento about order status changes via the Order Status Update message. In order to correctly export a new order from Magento Commerce (MC) to OMS, the MC will configure the system to store the external ID in the OMS, in Stores > Configuration > MCOM CONNECTOR > General > Sales Channel ID.

Order status update integration point

By default, the Connector will create and map new order statuses in MC as described in the table below. The OMS will notify Magento about the order status and order line status changes via the Order Status Update message.

Magento orders have two attributes which indicate the status of the order:

  • State—used to determine “order phase”; One state may have few statuses. This state is not configurable.
  • Status—used for display information about order status and is configurable in Admin (new statuses can be added).

Every time that order changes status, an order updated message is sent through the bus. Magento 2 will consume the message and set the new status for the order. If the status does not exist in Magento 2, it will be created. Any status that the OMS sends will be accepted in Magento 2.

Return integration point

Customer Service can create a return request through the Admin that will generate a return in status REQUESTED. Once the warehouse receives the parcel and confirms the reception, the OMS will update the status to ACCEPTED upon receiving the return-new feed.

Then customer service will be able to see the refund status in MC and the OMS.

Return Integration

In MC, there is a configuration that displays the return link in the menu of each order so you can see the returns associated with each order. The configuration is found in Stores > Configuration > SALES > Sales > RMA Settings > Enable RMA on Storefront (set it to Yes).

The usage of MC initiated RMAs is currently not compatible with the OMS return flow. Only activate it if you are extending the MC behavior to create the returns with OMS specifications.

Refund integration point

Refunds are created and managed by the OMS. A message will inform MC of the refund amount and the status of the actual refund (credit memo). In MC, the order summary page total will be recalculated to display the refunded amount.

Return Integration

Refunded

Stock updates

OMS will inform MC of stock quantities every time there is new information available to be exported. For the stock inventory updates, ensure that the messages are consumed in the correct order to avoid having values been overwritten inconsistently.

If, for instance, the OMS sends a FULL snapshot and a few minutes afterward generated a DELTA update, you must ensure MC is not processing the DELTA update before the FULL is completed (so that quantities are not overwritten).

In the messages sent to MC for stock updates (FULL and DELTA) a timestamp field is included.

MC has a filter for stock messages, when a new stockUpdateMessage is consumed:

  • Gets the productId and timestamp from the message
  • Retrieves the corresponding product entry from cataloginventory_stock_item_update
  • If message.timestamp < entry.timestamp the message is discarded or the entry is updated with the message.timestamp and stockUpdate process continues.

The solution is to calculate the timestamp for the full import when it is started and use it for all the full messages (like a transaction ID). In this case, the DELTA will have a higher timestamp than the FULL, so when the SKU in the FULL tries to be updated the message will be discarded because its timestamp is lower than the last update (DELTA).