Configure the Connector
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 thecomposer.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
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.
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.
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.
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 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.
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;
}
}