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.

If you do not know your OMS Connector repository credentials, contact Support to renew them. See the Submitting a support request topic for more information.

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

You can find useful information about the installed Connectors, including module version, in the Magento Commerce Admin. See the System Reports user guide topic for more info.

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

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

Processing incoming messages via synchronous mode is a deprecated practice. Synchronous mode is completely removed from our system. Asynchronous mode is now the expected mode for incoming communications.

Asynchronous mode config in Magento Commerce

Configure transport layer

Navigate to Stores > Configuration > MCOM Connector > Configuration > Transport to enable asynchronous order processing (toggle option to No).

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—like pending. This is especially helpful with orders that still need to be validated in Magento Commerce, as these orders are not exported immediately.

The Connector exports order statuses as defined by asynchronous mode configuration.

If the Process order synchronously configuration is enabled (config shown in the screenshot above), but the order in question is not in one of the selected statuses, then it is not sent until its status is changed to one of the selected statuses. When the status changes it is sent by cron.

If the Process order synchronously configuration is enabled, and an order is one of the selected statuses but it fails to send, it will retried again by cron as long as the status remains as one of the selected statuses to be exported.

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. To export the full catalog via the Magento Commerce Admin, see the Export Full Catalog user guide topic.

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

You can append your commands with -s (short form) or --schedule-only (long form), as mentioned above, to:

  • Schedule an export (instead of exporting immediately)
  • Export the full catalog

Since both commands accomplish the same thing, use either the long form or short form, but not both.

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.

See the View Connector logs topic for more information on finding and reading logs.

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;
    }

}