MCOM Connector Setup Tutorial

Introduction

This document describes how to install and configure the Magento OMS extension in MC.

Installation

Requirements

  • MCOM connector repository access credentials
  • Access to the Magento 2 server via ssh
  • Composer installed on Magento 2 server

Installation

1. Add Magento OMS repository to composer

First connect to your Magento installation and go to your Magento root directory.

Add below to composer.json

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

2. Update Magento

In Magento folder, after installation run the following commands. In order the check the latest available version of the connector you can check the changelog here

$ composer require --ignore-platform-reqs \
    magento/mcom-connector XX
  
$ 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

How to check in MC which version of the module is installed

In MC Admin there is a report that will display useful information about the installed connectors. In Admin under System > System Report you need to select the New Report and choose Modules. Once the report is generated under the action link click on view and you will be able to see the version of the modules.

System report of installed modules

In order to see what changes have been released in each version of the connector a changelog is available here: https://magento-mcom.github.io/mcom-connector-sr/CHANGELOG.html (can be accessed from the menu MCOM > Change log)

Configure MCOM Connector

Comunication protocol to

Once the connector have been installed you have to configure the protocol to be used for the comunication with OM. The recommended protocol is http. In Admin under Stores > Configuration > MCOM Connector > Configuration > Transport Configure transport layer

Stores Setup

Magento will prepare and send all authorized orders to the 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

Store Configuration:

Alt Text

Integration Configuration for http integration

To allow the MCOM connector to connect to the OM API, the below configurations need to be added to env.php. Configuration values provided below are just an example, please, make sure to enter correct values for every option. Please 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 api-stg.mcom.magento.com 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

Message consumption by Magento Digital

Note that 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 header to with value or * to get to their destination.

Test installation

You can check if the modules were properly by validating if in the Admin menu a new section is displayed called MCOM

Menu

Useful commands

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. Then you need to verify the stock consumer is running, a reindex and clear cache, and the products will be displayed in the frontend.

IMPORTANT: 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 MC 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

In case 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 (Version Connector 1.1.1+, Sales 1.4.1+)

The command will send to OMS orders that are not in a OMS Status.

Usage:

To sync all orders:

bin/magento oms:orders:sync

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 MDC instance will automatically re-register in MCOM. If the instance is not availble 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): click on the register button.

Re-register MDC in OMS API layer

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. [] []

How to add custom attributes to the order lines

As of today MC doesn’t 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 OM. 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;
    }

}

Configure integration to use cron Job

In the integration all messages are processed synchronously.

Sometimes, when using HTTP protocol and the catalog increases in size, we will receive huge stock updates that will cause the integration to time out (by default after 30 seconds).

In order to avoid this we recommend to process incoming messages asynchronously.

This way, messages will be temporaly stored in database and processed later by cron. This also helps with concurrency issues since the messages are processed sequentialy.

In the connector this can be done easily by enabling the configuration Stores > Configuration > MCOM Connector > Transport > Process all messages synchronous to No.

Also, you will need to run the cron group oms_process_messages

Messages configured as synchronous will be always processed synchronously.