Connector Integration Architecture

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

MC to OMS connection

Modules

The following modules exist in the Connector to assist with integrating MC 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 OMS
• Post Sales module—Manages returns and refunds

Integration points

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

Catalog integration point

Magento or a Product Information System (PIM), as a catalog provider, should send this generic product information to the OMS:

• SKU
• Name
• 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 magento.catalog.product_management.updated message is sent to your OMS. Catalogs that are imported via CSV file will be exported to the OMS in batches of 5,000 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 Catalog > Products 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 > Products in the MC Admin

Product custom attributes

In the Magento Commerce Admin you can define which are the product custom attributes to be exported to the OMS.

Define custom attributes in MC Admin

Inventory integration point

Magento should support multiple stocks for use in different stock aggregates on different websites. One Magento website can be assigned to only 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.

Aggregating and calculating stock info

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

Manage Stock Aggregate view in MC Admin

Every time a new stock update is sent from the OMS to MC the quantity for each SKU will be replaced with the values provided in the message (if a SKU was not present in the message it will be automatically set to 0 and out of stock).

The Connector will also update the Stock Status field:

• 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 message reception, MC will update the Manage Stock field to No. If the unlimited stock is not provided for a SKU that is set the Manage Stock flag will remain set to No.
• For enabled backorders, for the entire catalog or for a specific product, the stock status will be set to 1 for the product.

Order integration point

Magento prepares and sends all orders with a PENDING status (which is the default status) to the OMS asynchronously.

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

Advanced Inventory configuration

The OMS will notify Magento about order status changes via the Order Status Update message. To correctly export a new order from MC to OMS, 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 to display information about order status and is configurable in the Admin (new statuses can be added).

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

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 can see the refund status in MC and the OMS.

Returns

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 the OMS API.

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.

Credit memos

Refund/credit memo in order total

Disabled or modified functionalities

Out-of-the box, MC provides an implementation for order management and inventory management tools, which may conflict with implementations existing in the OMS.

Disabled functionalities

To avoid conflict between implementations, and in an effort to stick to a single data storage concept, some of the MC features are disabled or switched to read-only mode.

These functionalities are disabled or read-only:

• Order management—After an order is sent to the OMS, no order status changes are processed by MC. All changes come from the OMS.
• Inventory management—You cannot change product quantity and stock status in the OMS Admin. Stock status and product quantities are fully controlled by the OMS. For development and testing environments, you cannot manually edit stock in the MC Admin when the developer mode is enabled.

See Inventory for information about making these changes in the OMS Admin.

If your catalog contains virtual products that do not require stock management, you can configure the product to have Stock Management disabled in the MC 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. See Synchronize shipping methods for more information.
• Return management—The MC Return Merchandise Authorizations (RMAs) are currently not compatible with the OMS return flow. It is only recommended to activate it if you are extending the MC behavior to create the returns with OMS specifications. See Return flows for more information about the return flow.
• Manual invoice/credit memo creation—The manual creation of invoices and credit memos in the MC Admin is disabled once the Connector is installed. The MC and Connector automatically generate the invoice, with the magento.logistics.fulfillment_management.customer_shipment_done message, and credit memos, with the magento.postsales.refund_management.updated message.

Modified functionalities

These functionalities are modified:

• Default stock values are ignored. All stock information is taken from the newly created stock aggregates (MCOM > Manage Stock Aggregates). To see the correct stock information in the product view, select the correct store view.
• The quantity information displayed in the product grid is taken from the first aggregated stock that is found. Upon filtering the store view, the quantity will reflect the values from the associated aggregate to the store.
• The order will first request that the OMS validate whether the order is cancellable, and will then cancel it in the OMS and will update the newly canceled status in MC to ensure the status of the order is consistent across systems.
• There is a new Export full catalog option visible in the product grid view, which exports the entire catalog to the OMS.