Configure the Connector

This page describes how to install and configure the Magento Order Management System (OMS) for Magento Commerce using the Connector.

Prerequisites

To use OMS and the Connector with Magento v2.3, you must disable Multi-source Inventory (MSI).

Requirements

  • Obtain OMS Connector repository access credentials.
  • Get access to the Magento 2 server via SSH.
  • Install Composer on your Magento 2 server.

Prepare your environment

After satisfying the prerequisites for setting up the Connector, proceed with preparing your environment for further configuration.

Add Magento OMS repo to Composer

To add your Magento OMS repository to Composer:

  1. Connect to your Magento installation and navigate to your Magento root directory.

  2. Add the composer.json file:

    {
        "repositories": [
            {
                "type": "composer",
                "url": "https://mcom-connector.bcn.magento.com"
            }
        ]
    }

Add auth.json file

If you do not currently have an auth.json file, you can easily add one.

Create an auth.json file in your Magento root directory:

    {
       "http-basic": {
          "mcom-connector.bcn.magento.com": {
              "username": "<public-key>",
              "password": "<private-key>"
        }
      }
    }

And replace the public-key and private-key with your OMS authentication credentials.

Update the Magento installation

After the installation, run the following in the Magento folder:

composer require magento/mcom-connector

bin/magento setup:upgrade

The setup:upgrade command is not needed if you are using a Magento Cloud installation.

Or, you can select only specific modules to update:

composer config repositories.mcom composer https://mcom-connector.bcn.magento.com

 composer require --ignore-platform-reqs \
  magento/module-inventory-message-bus ~0.1 \
 magento/module-sales-message-bus ~0.1 \
  magento/module-catalog-message-bus ~0.1 \

 bin/magento setup:upgrade

See the changelog to check the latest available version of the Connector.

Check module version

In the Magento Commerce Admin there is a report that displays useful information about the installed Connectors.

To view the versions for each installed module:

  1. Navigate to Admin > System > System Report > New Report > Modules.
  2. After the report generates, click View to see all module versions.

    System report of installed modules

See what changes were released in each version of the Connector in the changelog in MCOM > Change log.

See the System Reports user guide topic for more info.

Configure OMS Connector

To configure the OMS Connector, setup the sales channel ID, configure the communication method, and configure the HTTP integration.

Setup sales channel ID

Magento will prepare and send all authorized orders to the OMS. The OMS notifies Magento Commerce about order status changes with the magento.sales.order_management.updated message.

To export a new order from Magento Commerce to your OMS, you must configure the sales channel ID (external ID of the defined sales channel in your OMS) in the Commerce Admin in Stores > Configuration > MCOM CONNECTOR > General > Sales Channel ID.

Configure asynchronous communication

Magento Commerce is connected to the OMS via a HTTP protocol. You can configure:

  • The incoming messages in Magento Commerce to be processed in asynchronous mode.
  • The orders to be exported to the OMS in asynchronous (which is recommended) mode.

The asynchronous mode of processing messages helps to avoid application timeouts (1 minute), such as stock updates, are received in Magento Commerce. The messages are temporarily stored in the database and then later processed by Cron. This also helps with concurrency issues since the messages are processed sequentially.

Synchronous mode is deprecated. Asynchronous is now the default mode for communications.

Configure transport layer

Configure order statuses to be exported

If the order export is configured in an asynchronous mode, you can define which orders have specific order statuses that should be exported to the OMS. This is especially helpful with orders that still need to be validated in Magento Commerce, as these orders are not exported immediately.

By default all orders with a Pending status are set to be exported. You can find the definition by navigating to Stores > Configuration > MCOM Connector > Configuration > Orders in your Commerce Admin.

Order status export

Define custom attributes for products

You can define the custom attributes for each product that should be exported to the OMS with catalog synchronization. You can find the definition in Stores > Configuration > MCOM Connector > Configuration > Catalog in the Commerce Admin.

Order custom attributes

Configuration for the HTTP integration

To allow the OMS Connector to connect to the OMS API, configure the env.php file using these example values. Ensure you enter correct values, specific to your installation, for this configuration.

Contact your Magento implementation team to receive your integration configuration information.

  'serviceBus' =>
    array (
      'url' => 'https://api.mcom.magento.com/LUMA',           // OMS Production API URL, change to https://api-stg.mcom.magento.com/clientid for Staging
      'oauth_server_url' => 'https://auth.bcn.magento.com/',  // OMS Production URL for the oauth server, change to https://auth-stg.bcn.magento.com for Staging
      'oauth_client_id' => 'luma',                            // Client as defined in the OMS auth server
      'oauth_client_secret' => '$43A8[3338',                  // Secret as defined in the OMS auth server
      'application_id' => 'mdc',                              // Unique integration ID, default to "mdc"
      'application_base_url' => 'https://mymcstore.com/',     // URL for receiving requests from OM (this is an optional field and if not configured will use the one configured in MC),
      'secret' => 'tCn5Y4XppSuKjriGr8n2gr76dgKIZ9Oa',         // Secret provided to OMS API to calculate signature. Can be any string, recommended length at least 32 symbols.
      'labels' => array(           // Additional labels used for integration registration
            'key' => 'value',
      ),
    )

The service bus URL must contain the host region.

Execute a Magento upgrade to ingest the changes:

$ bin/magento setup:upgrade

Test your installation

Check to see that your modules were properly installed by validating that the MCOM section is displayed in your Commerce Admin.

Commerce Admin MCOM view

Useful commands to manage your installation

Use the following helpful commands to manage your installation.

Reset stock items

The following command can be used to initialize the inventory after completing correctly the setup:

  $  bin/magento oms:stock:reset

This command will clean both _cataloginventory_stock_item_ and _cataloginventory_stock_status_ tables and publish a stock update message for all the existing products in the catalog for all created aggregates with a fake value of 100.

After that, reindex (which also clears the cache). The products will be displayed on the front-end.

The command can only be run when Magento is in DEVELOPER mode.

Export full catalog

The following commands can be used to manage the Export Full Catalog tasks from the command line.

This command will show the status of current running or pending export task:

$  bin/magento oms:catalog-export:status

You could schedule a new export task to be executed later by the Magento Commerce scheduler in background:

$  bin/magento oms:catalog-export:run --schedule-only

Or execute an export directly, either an existing scheduled one (in pending status) or a new one:

$  bin/magento oms:catalog-export:run

If you want to cancel an export task (pending or running) use:

$  bin/magento oms:catalog-export:run --cancel

Sync orders not exported

The command will send invalid orders to the OMS.

To sync all orders:

$  bin/magento oms:orders:sync

To sync only 10 orders:

$  bin/magento oms:orders:sync 10

Prune of message queue table

The Connector automatically stores all incoming and outgoing messages for backup and retry mechanisms in a table called mcom_logged_messages_queue.

Out-of-the-box, the Connector enables you to automatically prune old messages after X days. We recommend that this functionality is properly configured and enabled in your production installation to avoid performance issues caused by large amounts of data in the table.

To run the prune process:

$  bin/magento oms:queue:prune

This feature is configurable in the Commerce Admin, in Stores > Configuration > MCOM Connector > Configuration > Message Log.

Re-register MDC in OMS API layer

Re-register the application to subscribe to new topics

While running setup:upgrade the Magento Commerce instance will automatically re-register in your OMS. If the instance is not available while running the setup:upgrade the re-registration will fail, and there is a manual workaround to update the registration to the OMS API layer.

After the deploy is completed and the application is available again run:

$  bin/magento oms:service-bus:register

Click the Register button in the Commerce Admin > MCOM > MCOM Integration to trigger this.

Re-register MDC in OMS API layer

Logging

You can track the Connector work in the var/log/mcom-connector.log log file.

In this log file all the internal Connector messages will be logged in this format:

[YYYY-MM-DD HH:MM:SS] mcom.<LEVEL>: <OMS-MODULE>: <MESSAGE>

Information in the log messages include:

  • LEVEL—Message severity (ERROR, INFO, DEBUG, WARNING, etc.)
  • OMS-MODULE—Name of Connector module which logged the message (such as CatalogMessageBus)
  • MESSAGE—Log text

Example of log messages

[2017-03-01 07:56:12] mcom.DEBUG: AmqpMessageBus: Finish consuming message {"consumer":"stockConsumer","queue":"stock-consumer","topic":"magento.inventory.aggregate_stock_management.updated","message_id":"344764782367297","status":"FAILED","result":"Message code 1e1e30153de28bfa562e17d876d70070 already processed"} []
[2017-03-01 07:56:43] mcom.INFO: CatalogMessageBus: Event for product #1 sent to message bus [] []
[2017-03-01 08:04:35] mcom.ERROR: InventoryMessageBus: Inventory Stock Update : 'Requested stock Aggregate doesn't exist' [] []
[2017-03-01 08:38:22] mcom.DEBUG: CatalogMessageBus: Export Catalog Task Started. [] []
[2017-03-01 08:38:23] mcom.DEBUG: CatalogMessageBus: Start export requested at 2017-03-01 08:38:00 [] []
[2017-03-01 08:38:38] mcom.DEBUG: CatalogMessageBus: ERROR : Export cancelled by user [] []
[2017-03-01 08:38:38] mcom.DEBUG: CatalogMessageBus: 50 products exported [] []
[2017-03-01 08:38:38] mcom.DEBUG: CatalogMessageBus: Export Catalog Task Finished. [] []

View message performance

You can see performance measurements of each message as they are processed. Access information about which messages may be causing performance problems, either via New Relic or inside the var/log/mcom-connector.log log file, so that you can quickly diagnose and fix issues.

Navigate to STORES > Configuration > MCOM Connector > Configuration > Performance Monitor in the Commerce Admin to enable this functionality.

Metrics available out-of-the box for each transaction include:

  • Memory usage before the message is processed
  • Memory usage after the message is processed
  • Difference between memory usage before and after the message is processed
  • Peak memory usage before the message is processed
  • Peak memory usage after the message is processed
  • Difference between peak memory usage before and after the message is processed
  • Time elapsed

Example log file of message performance measurements

[2020-03-06 19:24:06] mcom.DEBUG: ServiceBusPerformanceMonitor: "Profile information for ServiceBus SingleMessageProcessor": {
        "messageId":    "905",
        "messageLogId": "1218",
        "messageMethod":        "magento.inventory.aggregate_stock_management.updated",
        "messageDeliveryId":    "ace3d531-a0dd-4296-86e6-45f233cbd135",
        "messageSize":  "243071 B",
        "memoryUsageBefore":    "188060576 B",
        "memoryUsageAfter":     "189762752 B",
        "memoryUsageDelta":     "1702176 B",
        "peakMemoryUsageBefore":        "213910864 B",
        "peakMemoryUsageAfter": "213910864 B",
        "peakMemoryUsageDelta": "0 B",
        "wallTimeBefore":       "2020-03-06T19:24:05.304600",
        "wallTimeAfter":        "2020-03-06T19:24:06.840300",
        "wallTimeElapsed":      "1.5356369018555 s",
        "userTimeBefore":       "1.420413 s",
        "userTimeAfter":        "2.871296 s",
        "userTimeElapsed":      "1.450883 s",
        "systemTimeBefore":     "0.241047 s",
        "systemTimeAfter":      "0.24654 s",
        "systemTimeElapsed":    "0.005493 s"
}

Add custom attributes to order lines

Magento Commerce does not support native custom attributes at the order line level. A plugin should be created for the \Magento\SalesMessageBus\Order\Mapper\LineMapper class to provide this information to the OMS.

class LineMapperCustomAttributesPlugin
{
    /**
     * @param LineMapper $subject
     * @param OrderLine $result
     * @return OrderLine
     */
    public function afterToSpecification(LineMapper $subject, OrderLine $result)
    {

        $result->setCustomAttribute('customAttribute','ValueOfCustomAttribute');
        return $result;
    }

}