Configure the Connector | Magento Order Management Documentation

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

Prerequisites

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

Requirements

Obtain the Magento repository access credentials (for composer).
Get access to the Magento 2 server via SSH.
Install Composer on your Magento 2 server.
Access the Magento repository.

Prepare your environment

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

Configure Magento repo in Composer

Previous releases of the OMS connector used the mcom-connector.bcn.magento.com repository and it will be decommissioned soon. Remove it from your repositories section of your composer.json file.

The OMS connector modules are now in the Magento repository. This is the same repository where the magento/product-enterprise-editi and the magento/product-community-edition repos are. Check that you already have access to this repository in your composer.json file.

To configure your Magento repository for Composer:

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

If exists, remove the mcom-connector.bcn.magento.com repository from the composer.json file:

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

Add the Adobe Commerce repository to the composer.json file if it’s not already there:

   {
       "repositories": [
           {
               "type": "composer",
               "url": "https://repo.magento.com"
           }
       ]
   }

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 require --ignore-platform-reqs \
  magento/mcom-connector ~4.2

 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.
      'labels' => array(           // Additional labels used for integration registration
            'key' => 'value',
      ),
    )

The secret provided can be any string. From releases 3.7.0 & 4.2.0 onward, the secret field must not be empty and its recommended length is at least 32 symbols.

Execute a Magento upgrade to ingest the changes:

$ bin/magento setup:upgrade

The service bus URL must contain the host region.

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

To manage your installation you can use several commands that return or help manage tasks like exporting a catalog, or prune old messages.

Information about OMS

The oms:support:info command shows information from different OMS sections, like:

oms:queue:retry
oms:messages:process
oms:orders:sync
oms:catalog-export:run
oms:queue:prune

When you run the oms:support:info command without any additional arguments, it will show all sections.

It is possible to show information only for one specific command by adding the command-line option --filter:

$ bin/magento oms:support:info --filter catalog-export

This is a useful command for System Integrators, Magento support, or other users when assisting customers who are having issues related to the OMS connector.

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.

You could schedule a new export task to be executed later by the Magento Commerce scheduler in the 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

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

Extended command-line options

A command-line option can modify the operation of a command. These command-line options are added to the command itself:

$ bin/magento oms:support:info --verbose

This example with the --verbose command-line option allows the oms:support:info to list each topic as they are processed, which is good for debugging performance issues.

Dry-run

The --dry-run command-line option shows how many messages are in the queue waiting to be processed.

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

When the --dry-run command-line option is combined with --verbose, shows a list of each topic in the queue and the counts for each of those topics.

Verbose

The --verbose command-line option lists each topic as they are processed. It shows a timestamp at the begining of each process. It can show the time elapsed after finishing processing a message.

$ bin/magento oms:support:info --verbose

Progress

The --progress command-line option shows the progress at the start of each item.

$  bin/magento oms:messages:process --progress

This example shows the progress of the processing messages.

Max-messages

The --max-messages command-line option shows a count of how many messages can be sent before running the command.

$  bin/magento oms:messages:process --max-messages

These command-line options can be used simultaneously to provide more detailed and specific results. For example, you could use $ bin/magento oms:orders:sync --progress --verbose.

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

}