MCOM Connector Integration Architecture

Integration Diagram

MC to OMS connection diagram

Modules

Catalog Module

Keeps product updates in sync with the Magento OMS

Inventory Module

Keeps inventory stock updates in sync with the Magento OMS

Sales Module

Send new orders, order updates and shipment updates to the Magento OMS

Post Sales Module

Manages returns and refunds

Standard MC functionalities disabled/modified by the MCOM connector

Disabled functionalities

The out of the box Magento provides an implementation of order management and inventory management tools, which may conflict with implementations of the Magento OMS. To avoid it, and stick to “single data storage” concept, some of Magento features are disabled or switched to Read-Only mode.

  • Order management – after an order was sent to OMS, no changes to the order status will be processed by MC. All changes will be initiated from the OMS.
  • Inventory management – you should not be able to change product quantity and stock status through the back office. Stock status and product quantities are fully controlled by the OMS. For development and testing environment, it will be possible to edit the stock manually in the admin panel in case the developer mode is switched on. In case your catalog contains virtual products that don’t require stock management you can configure the product to have Stock Management disabled in MC Admin.
  • Shipping and Payments methods – there are only certain shipping and payment methods supported, so you can’t use any extra methods. The methods ship, hold, invoice order are disabled by the connector. Those actions are not available to be performed in MC. Actions create returns, refunds are disabled by the connector. Those need to be initiated through the OMS.

Modified functionalities

  • The default stock values are ignored. All stock information is taken from the newly created stock aggregates (stores > Stock Aggregates). In the product page to see the correct stock information, you will have to select the correct store view.
  • The quantity information displayed in the product grid is taken from the first stock aggregated found. Upon filtering the store view, the quantity will reflect the values from the associated aggregate to the store.
  • The order cancellation will first request the OMS to validate if the order is cancellable, cancel it in the OME and update the new canceled status in MC to ensure the status of the order is consistent across both systems.
  • There is a new button visible in the product grid page “export full catalog” 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 need to validate information for the imported orders. Therefore 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 a new product message or product update to the OMS. Every time there is a product update for any of the fields existing in the magento.catalog.product_management.updated http://omsdocs.magento.com/en/specifications/#magento.catalog.product_management a new message is exported to OMS. IMPORTANT: in order to trigger the export message the update needs to be done via the API (ProductRepository->save) and not directly in the database.

In MC admin panel is also possible to trigger a full catalog export from the Products > Catalog that might be useful to initiate a first synchronization after the full catalog import (this process is not ment to be used for regular updates).

Catalog

Inventory integration point

Magento should support multiple stocks, to be able to use 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 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 MC Admin to configure the stock aggregates under MCOM > Manage Stock Aggregate

Stock aggregates interfaces

Every time a new stock update is sent from OM to MC the quantity for each SKU will be, first reset to zero and then updated with the values provided in the message (therefore if an SKU was not present in the message 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” (therefore the product will be visible in the frontend), if quantity <= 0 the status will be set to Out of Stock (therefore the product will disappear from the website). In case any of the products have been configured in OM to have “unlimited” stock, then upon the message reception, MC will update the Manage Stock field to No. Note that in case the “unlimited” stock is not provided for an SKU that already have been set before 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 OMS. The OMS will notify Magento about order status changes via Order Status Update message. In order to export correctly a new order from MC to OMS the MC needs to configure the following in each website:

  • Stores > Configuration > MCOM CONNECTOR > General > Store ID: Store External Id in OMS
  • Stores > Configuration > MCOM CONNECTOR > General > Vat Country: Vat country required in OMS

Stock aggregates interfaces

Order status update integration point

By default, the MCOM connector will create and map new order statuses in MC as described in the table below. The OMS will notify Magento about order status order orderLine status changes via Order Status Update message. All the standard MC statuses have been disabled by the connector. Magento orders have two attributes which indicate the status of the order:

  • state - is used to determine “order phase”, one state may have few statuses. The state is not configurable.
  • status - is used for display information about order status and is it configurable in Admin (new statuses can be added).

Every time that Order or OrderLine changes status a message of Order Updated 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. So basically any status that the OMS will send, it will be accepted in Magento 2. Standard interface for order update is here. This is the list of statuses currently existing by the OMS:

MC and OMS Status OMS Label
COMPLETE Complete
ERROR Error
LOGISTICS Logistics
LOGISTICSCOMPLETE Logistics Complete
ONHOLD On Hold
RECEIVED Received
REJECTED Rejected

Return integration point

Customer Service can create return request through the Admin interface 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 agent will be able to see the refund status both in MC and OMS.

Return Integration

IMPORTANT: In MC there is a configuration that will display the return link in the menu of each order so you can see directly the returns associated with each order. The configuration is the following:

Stores > Configuration > SALES > Sales > RMA Settings > Enable RMA on Storefront and set it to Yes

The usage of this MC return flow is not compatible with the MOM return flow. Please Activate it only in the case that you will extend the MC behaviour to create the returns with MOM specification. In 2018 Q3 this will added in the MOM connector as out of the box feature.

Refund integration point

Refunds are created/managed by the OMS. A message will inform MC of the refund amount and status of the actual refund (Credit Memo). In MC the total on the order summary page 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, it is needed to ensure that the messages are consumed in the correct order to avoid having values been overwritten inconsistently. CASE: OMS sends a FULL snapshot and a few minutes afterward generated a DELTA update. It is needed to ensure MC is not processing the DELTA update before the FULL is completed so that quantities are not overwritten

  • In the messages sent to M2 for stock updates (Full/Delta) it is included a ‘timestamp’ field.
  • MC have a filter for stock messages as follows:

When a new stockUpdateMessage is consumed:

  • Get the productId and timestamp from message
  • Retrieve corresponding product entry from cataloginventory_stock_item_update
  • If message.timestamp < entry.timestamp then discard message
  • Else, update entry with the message.timestamp and continue stockUpdate process

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), then the delta will have a higher timestamp than the full, so when the SKU x in the full tries to be updated the message will be discarded because its timestamp is lower than the last update (delta).