Install or upgrade the Connector | Magento Order Management Documentation

Installing or upgrading the Connector requires a few steps, but is fairly straightforward. See the install and upgrade sections in this topic for both Cloud and non-cloud environments for detailed instructions on how to get started.

For information about configuring the Connector after you complete initial setup, see the Configure the Connector topic.

Intended audience

The audience for this topic is anyone who wishes to install or upgrade the Connector for their Magento installation. You should be fairly technical, understand Composer and Git commands, and be able to upgrade the Magento system software using those commands.

Prerequisites

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

Requirements

To get started installing or upgrading the Connector you must:

Obtain OMS Connector repository access 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.
Get access to the Magento 2 server via SSH.

Install a development instance

This section explains how to install a development instance of the Connector, either on a Cloud environment or on your local environment.

Connector modules for development instances reside within the app/code/Magento folder.

On local environment

To install the Connector on a development instance for your local environment:

Clone the Connector GitHub repository.

Refer to GitHub’s documentation for instructions on cloning a repository.
Checkout a new branch:
```
git checkout -b branch_name
```
Generate public and private keys for the Magento repository. To authenticate, you must generate Magento authentication keys and a GitHub personal access token.

In your Magento root directory, create an auth.json file based on the auth.json.sample file:

   {
   "http-basic": {
      "repo.magento.com": {
         "username": "<public-key>",
         "password": "<private-key>"
      }
   }
}

Replace the <public-key> and <private-key> placeholders with your credentials.
Install Composer and all necessary dependencies:
```
composer install
```
For development purposes we recommend you remove the composer.lock file and install dependencies from composer.json.
Create a new virtual host. You must have a public host to process incoming messages from the OMS. For development purposes you can use ngrok to create a public URL.
Complete a Magento installation using the web interface or the CLI command method (similar to an out-of-the-box Magento installation).

On Cloud environment

To install the Connector on a development instance for your Cloud environment:

Create a new branch in the Magento Cloud Project Web UI, remote_branch_name.
Create a new remote on your local machine: remote_name. Find the URL for this remote in the git clone command from the Magento Cloud Project Web UI.
Push your changes:
```
git push remote_name local_branch_name:remote_branch_name
```
The local_branch_name is the name of your active local Git branch.
View the installation process status in the Magento Cloud Admin panel.

Install a production instance

This section explains how to install a production instance of the Connector, either on a Cloud environment or on your local environment.

Connector modules for production instances reside within the vendor/Magento folder.

On non-Cloud environment

To install the Connector on a production instance for a non-Cloud environment:

Add the Connector modules repository to the Magento composer.json file.
Install Composer and all necessary dependencies:
```
composer install
```
Create a new virtual host. You must have a public host to process incoming messages from the OMS. For development purposes you can use ngrok to create a public URL.
Complete a Magento installation using the web interface or the CLI command method (similar to an out-of-the-box Magento installation).

On Cloud environment

To install the Connector on a production instance for your Cloud environment:

Add magento/mcom-connector as a requirement to your root Composer package:
```
composer require "magento/mcom-connector:*"
```
Ensure MSI modules are disabled.
Push your changes to your Magento Cloud environment.
After deployment, SSH to your Cloud environment.
Add Service Bus to your app/etc/env.php file.
And add it to your environment:
```
bin/magento oms:service-bus:register
```

Complete initial setup

Now that you have installed the Connector for your particular environment and situation, it’s time to complete the initial setup of the Connector and Magento.

After installation, an MCOM menu item will appear in the Magento Admin.

MCOM icon in Magento Admin

MCOM icon in Magento Admin

To complete an initial setup of your Connector integration to Magento Commerce:

Open the app/etc/env.php file and add this configuration code:

'serviceBus' => [
 'url' => 'https://api-eu.mcom.magento.com/bomb',
 'secure_endpoint' => true,
 'oauth_server_url' => 'https://auth.bcn.magento.com',
 'oauth_client_id' => 'bomb',
 'oauth_client_secret' => 'U3crPcqAyZwjVs',
 'secret' => 'secret_key',
 'application_id' => 'your_application_id (unique name for your integration)',
 'application_base_url' => 'http://your_host.ngrok.io/'
]

Run the oms:service-bus:register command from your project’s root folder:
```
php bin/magento oms:service-bus:register
```
If you notice errors after this action, check the Magento exceptions log files.

If integration via this command was successful, you will see a success message in your console and your integration will appear in the OMS system with your application_id and other integrations.
Log into the Magento Admin and navigate to Stores > Settings > All Stores.
Create a new website, store, and store views. You can always create more than one if you desire!
Navigate to MCOM > Manage Stock Aggregates.
Click Add New Stock Aggregate to create a new stock aggregate with the code that matches the stock aggregate code in the OMS.
Assign a new website, maybe one you just created, to the stock aggregate.
Navigate to Stores > MCOM Connector > Configuration and complete the following:
- General—In the Sales Channel ID section, set the Sales Channel ID to the same Sales Channel ID as specified in the OMS Admin.
- Message Log—Modify the Message Log global settings if your needs differ from the default settings.
- Transport—We recommend you set the Process orders synchronously option to No (effectively setting it to process orders asynchronously.)
  
  With synchronous processing, orders will be sent to the OMS right after order placement. With asynchronous processing, orders will be sent by cron, console command (php bin/magento oms:orders:sync), or from the Order details view in the Admin.
- Catalog—In the Custom attributes to export and Cron schedule sections, configure the attributes to be observed during a product update. If an attribute is updated, a product update task is created for the OMS and will be sent by cron or console command (php bin/magento oms:catalog-export:run).
  
  In the Cron schedule section, set the timeframe for which the cron will run product updates.
- Orders—In the Statuses to be exported section, define the order status that will trigger export to the OMS after order placement.
- Memory Limit—In the Mode and Memory Limit in Percent sections, configure the memory limit that triggers a stop to the message processing loop. Message processing will start again the next that its cron job runs. This limit ensures you are not using too much memory during this process.
- Payments— In the Commerce-driven payments section, enable or disable Magento Commerce to handle payment operations to allow processes of multiple payment types, such as gift cards or store credit, for a single order.

Upgrade your development instance

To upgrade the development instance of your Connector:

Pull the latest changes from GitHub for your target branch.
Run the setup:upgrade command to apply the schema and data changes:
```
php bin/magento setup:upgrade
```
This step can be omitted if you are certain the update does not have schema changes, data changes, new modules, or other updates that should be applied.
Clear your Magento cache.

Upgrade your production instance

This section explains how to upgrade a production instance of the Connector, either on a non-Cloud or Cloud environment.

On non-Cloud environment

To upgrade the production instance of your Connector on a non-Cloud environment:

Ensure that the requirements for the Connector package version in your composer.json file is not strict (limiting you to an exact version of the Connector). If your composer.json does lists a previous version of the Connector, revise to the most recent version so you can upgrade.

For instance, the below example shows 3.2.0 as the Connector version. This will not allow you to upgrade to the most recent version of the Connector, as 3.2.0 is a previous version.
```
"magento/mcom-connector": "3.2.0"
```
If you configure your composer.json to have more flexible versioning, it allows you to upgrade with ease.
```
"magento/mcom-connector": "3.*"
```
Update Composer:
```
composer update
```
Run the setup:upgrade command to apply the schema and data changes:
```
php bin/magento setup:upgrade
```
Clear your Magento cache.
Run the setup:di:compile command to compile the code:
```
php bin/magento setup:di:compile
```

On Cloud environment

To upgrade the production instance of your Connector on a non-Cloud environment:

Update Composer and all necessary dependencies:
```
composer install
```
Push your composer.lock and composer.json file changes to the Cloud environment.