OMS Connector Setup Tutorial

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

Prerequisites

Requirements

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

Add your Magento OMS repository to the 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 following composer.json

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

Add the auth.json file

If you do not currently have an auth.json file you can easily add one. To create a new auth.json file:

  1. Use the text editor of your choice to create a file named auth.json in your Magento root directory:

     {
        "http-basic": {
           "mcom-connector.bcn.magento.com": {
               "username": "<public-key>",
               "password": "<private-key>"
         }
       }
     }
    
  2. Replace public-key and private-key with your OMS authentication credentials.

Update the Magento installation

In the Magento folder, after the installation, run the following commands:

$ composer require magento/mcom-connector
  
$ bin/magento setup:upgrade

If you want to select specific modules:

composer config repositories.mcom composer

 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 \
  magento/module-amqp-message-bus ~0.1

 bin/magento setup:upgrade

In order the check the latest available version of the connector you can check the changelog.

Check modules installed version in Magento Commerce

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 via the changelog in MCOM > Change log.

Configure OMS Connector

Setup store ID and VAT country

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

To export a new order from Magento Commerce to your OMS, you need to configure the following in each website:

  • Store ID: The store external ID in your OMS. You can find it in Stores > Configuration > MCOM CONNECTOR > General > Store ID.
  • VAT Country: VAT Country required in your OMS. You can find it in Stores > Configuration > MCOM CONNECTOR > General > VAT Country.

Alt Text

Configure asynchronous or synchronous communication

Magento Commerce is connected to the OMS via a HTTP protocol. It is possible to configure that:

  • The incoming messages in Magento Commerce can be processed in a asynchronous (recommended) or synchronous mode.
  • The orders can be exported to the OMS in an asynchronous (recommended) or synchronous mode.

The asynchronous mode of processing messages is highly recommended to avoid application timeouts when big sized messages, such as stock updates, are received in Magento Commerce. The messages are temporarily stored in the database and then later processed by Cron. With a synchronous configuration, you need to run the cron group oms_process_messages. This also helps with concurrency issues since the messages are processed sequentially.

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 the Pending status are configured to be exported. You can find the definition by navigating to Stores > Configuration > MCOM Connector > Configuration > Orders:

Order status export

Define customer 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 by navigating to Stores > Configuration > MCOM Connector > Configuration > Catalog:

Order custom attributes

Configuration for the http integration

To allow the OMS connector to join with the OMS API, configure the env.php file using these example values. Make sure 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 http://api-stgeu.mcom.magento.com/clientid for Staging
        'oauth_server_url' => 'https://auth.bcn.magento.com/',  // OMS Production URL for the oauth server, change to 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(           // Aditional labels used for integration registation
             'key' => 'value',
        ),
      )

Execute Magento upgrade to ingest the changes


  $ bin/magento setup:upgrade

Configure message consumption

Magento can only consume one type of message per process. For each type of message you need to run the following command:


  $  bin/magento queue:consumers:start

All messages require the following header settings to reach their destination:

  • Includes a to with a value specific information.
  • Includes a * (no specific information provided).

Test your installation

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

Menu

Useful 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.

To verify the stock consumer is running, reindex and clear your cache. The products will be displayed on the front-end.

The command and 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 scheduler in background with:


  $  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 with:


  $  bin/magento oms:catalog-export:run

If you wanted to cancel an export task (pending or running) you can use the following command:


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

Sync Orders not exported

The command will send to the OMS orders that are not in a valid OMS status.

Usage:

  • To sync all orders

    
        $  bin/magento oms:orders:sync
    
    
  • To sync only 10 orders

    
        $  bin/magento oms:orders:sync 10
    
    

Re-register the application in MCOM so that new topics are subscribed

While running setup:upgrade the Magento Digital (or MDC) 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 the following command.


  $  bin/magento oms:service-bus:register

This same option can be triggered from the Magento admin panel MCOM > MCOM Integration by clicking the register button:

Re-register MDC in OMS API layer

Access the connector log file

It is possible to track the connector work in the following log file:

var/log/mcom-connector.log

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

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

Where

  • LEVEL is the message severity (ERROR, INFO, DEBUG …)
  • OMS-MODULE is the name of connector module which logged the message (like ‘CatalogMessageBus’)
  • MESSAGE the log text

This is an 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. [] []

Add custom attributes to order lines

As of today Magento does not support natively custom attributes at order line level. Therefore a plugin should be created for the \Magento\SalesMessageBus\Order\Mapper\LineMapper class to provide such information to OMS.

An example:

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

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

}