Edit in GitHubLog an issue

Create an integration

An integration enables third-party services to call the Adobe Commerce and Magento Open Source web APIs. The APIs currently support external software, such as Accounting, Enterprise Resource Planning (ERP), Customer Relationship Management (CRM), Product Information Management (PIM), and marketing automation systems out of the box.

Implementing a simple integration requires little knowledge of PHP or Commerce internal processes. However, you will need a working knowledge of

Before you begin creating a module, make sure that you have a working installation that meets the System Requirements.

To create an integration, follow these general steps:

Create a skeletal module#

To develop a module, you must:

  1. Create the module file structure. The module for an integration, like any other of your custom modules, should be placed under <base_dir>/app/code/app/code/<vendor_name>/<module_name>. E.g. <base_dir>/app/code/Vendor1/Module1

    Also create etc, etc/integration, and Setup subdirectories under <base_dir>/app/code/<vendor_name>/<module_name>, as shown in the following example:

    Copied to your clipboard
    cd <base_dir>
    Copied to your clipboard
    mkdir -p app/code/<vendor_name>/<module_name>/etc/integration
    Copied to your clipboard
    mkdir -p app/code/<vendor_name>/<module_name>/Setup

    For more detailed information, see Create your component file structure.

  2. Define your module configuration file. The etc/module.xml file provides basic information about the module. Change directories to the etc directory and create the module.xml file. You must specify values for the following attributes:

    AttributeDescription
    nameA string that uniquely identifies the [module](https://glossary.magento.com/module).
    setup_versionThe version of Commerce the component uses
    The following example shows an example `etc/module.xml` file.
    Copied to your clipboard
    1<?xml version="1.0"?>
    2 <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    3 <module name="Vendor1_Module1" setup_version="2.0.0">
    4 <sequence>
    5 <module name="Magento_Integration"/>
    6 </sequence>
    7 </module>
    8 </config>

    Module Magento_Integration is added to "sequence" to be loaded first. It helps to avoid the issue, when a module with integration config loaded, that leads to a malfunction.

  3. Add your module's composer.json file. Composer is a dependency manager for PHP. You must create a composer.json file for your module so that Composer can install and update the libraries your module relies on. Place the composer.json file in the module-<module_name> directory.

    The following example demonstrates a minimal composer.json file.

    Copied to your clipboard
    1 {
    2 "name": "Vendor1_Module1",
    3 "description": "create integration from config",
    4 "require": {
    5 "php": "~7.2.0|~7.3.0",
    6 "magento/framework": "2.0.0",
    7 "magento/module-integration": "2.0.0"
    8 },
    9 "type": "magento2-module",
    10 "version": "1.0",
    11 "autoload": {
    12 "files": [ "registration.php" ],
    13 "psr-4": {
    14 "Vendor1\\Module1\\": ""
    15 }
    16 }
    17 }
    18

    For more information, see Create a component.

  4. Create a registration.php file The registration.php registers the module with the system. It must be placed in the module's root directory.

    Copied to your clipboard
    1<?php
    2\Magento\Framework\Component\ComponentRegistrar::register(
    3\Magento\Framework\Component\ComponentRegistrar::MODULE,
    4'Vendor1_Module1',
    5__DIR__
    6);
  5. Create an install class. Change directories to your Setup directory. Create a InstallData.php file that installs the integration configuration data into the Commerce integration table.

    The following sample is boilerplate and requires minor changes to make your integration work.

    Copied to your clipboard
    1<?php
    2namespace Vendor1\Module1\Setup;
    3
    4use Magento\Framework\Setup\ModuleContextInterface;
    5use Magento\Framework\Setup\ModuleDataSetupInterface;
    6use Magento\Integration\Model\ConfigBasedIntegrationManager;
    7use Magento\Framework\Setup\InstallDataInterface;
    8
    9class InstallData implements InstallDataInterface
    10{
    11 /**
    12 * @var ConfigBasedIntegrationManager
    13 */
    14
    15 private $integrationManager;
    16
    17 /**
    18 * @param ConfigBasedIntegrationManager $integrationManager
    19 */
    20
    21 public function __construct(ConfigBasedIntegrationManager $integrationManager)
    22 {
    23 $this->integrationManager = $integrationManager;
    24 }
    25
    26 /**
    27 * {@inheritdoc}
    28 */
    29
    30 public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
    31 {
    32 $this->integrationManager->processIntegrationConfig(['TestIntegration']);
    33 }
    34}

    In the following line

    $this->integrationManager->processIntegrationConfig(['testIntegration']);

    testIntegration must refer to your etc/integration/config.xml file, and the integration name value must be the same.

    The following example demonstrates a minimal config.xml file.

    Copied to your clipboard
    1<integrations>
    2 <integration name="TestIntegration">
    3 <email>someone@example.com</email>
    4 <endpoint_url>https://example.com</endpoint_url>
    5 <identity_link_url>https://example.com/identity_link_url</identity_link_url>
    6 </integration>
    7</integrations>

    Also, be sure to change the path after namespace for your vendor and module names.

Create integration files#

The Integration module simplifies the process of defining your integration. This module automatically performs functions such as:

  • Managing the third-party account that connects to Commerce.
  • Maintaining OAuth authorizations and user data.
  • Managing security tokens and requests.

To customize your module, you must create multiple XML files and read through other files to determine what resources existing modules have access to.

The process for customizing your module includes

Define the required resources#

The etc/integration/api.xml file defines which API resources the integration has access to.

To determine which resources an integration needs access to, review the permissions defined in each module's etc/acl.xml file.

In the following example, the test integration requires access to the following resources in the Sales module:

Copied to your clipboard
1<integrations>
2 <integration name="TestIntegration">
3 <resources>
4 <!-- To grant permission to Magento_Log::online, its parent Magento_Customer::customer needs to be declared as well-->
5 <resource name="Magento_Customer::customer" />
6 <resource name="Magento_Log::online" />
7 <!-- To grant permission to Magento_Sales::reorder, all its parent resources need to be declared-->
8 <resource name="Magento_Sales::sales" />
9 <resource name="Magento_Sales::sales_operation" />
10 <resource name="Magento_Sales::sales_order" />
11 <resource name="Magento_Sales::actions" />
12 <resource name="Magento_Sales::reorder" />
13 </resources>
14 </integration>
15</integrations>

Pre-configure the integration#

Your module can optionally provide values in configuration file config.xml, so that the integration can be automatically pre-configured with default values. To enable this feature, update the config.xml file in the etc/integration directory.

The file defines which API resources the integration has access to.

Copied to your clipboard
1<integrations>
2 <integration name="TestIntegration">
3 <email></email>
4 <endpoint_url></endpoint_url>
5 <identity_link_url></identity_link_url>
6 </integration>
7</integrations>
ElementDescription
integrationsContains one or more integration definitions.
integration name=""Defines an integration. The name must be specified.
emailAn email to associate with this integration.
endpoint_url

Optional. The [URL](https://glossary.magento.com/url) where OAuth credentials can be sent when using OAuth for token exchange. We strongly recommend using https://.

See OAuth-based authentication for details.

identity_link_urlOptional. The URL that redirects the user to link their 3rd party account with the Commerce integration.

Install your module#

Use the following steps to install your module:

  1. Run the following command to update the database schema and data.

    Copied to your clipboard
    bin/magento setup:upgrade
  2. Run the following command to generate the new code.

    Note: In Production mode, you may receive a message to 'Please rerun Magento compile command'. Enter the command below. You are not prompted to run the compile command in Developer mode.

    Copied to your clipboard
    bin/magento setup:di:compile
  3. Run the following command to clean the cache.

    Copied to your clipboard
    bin/magento cache:clean

Check your integration#

Log in to the Admin and navigate to System > Extensions > Integrations. The integration should be displayed in the grid.

Integrate with your application#

Before you can activate your integration, you must create two pages on your application to handle OAuth communications.

  • The location specified in the identity_link_url parameter must point to a page that can handle login requests.

  • The location specified in the endpoint_url parameter (Callback URL in Admin) must be able to process OAuth token exchanges.

Login page#

When a merchant clicks the Activate button in Admin, a pop-up login page for the third-party application displays. Commerce sends values for oauth_consumer_key and success_call_back parameters. The application must store the value for oauth_consumer_key to tie it to the login ID. Use the success_call_back parameter to return control back to Commerce.

Callback page#

The callback page must be able to perform the following tasks:

  • Receive an initial HTTPS POST that Commerce sends when the merchant activates integration. This post contains the Commerce store URL, an oauth_verifier, the OAuth consumer key, and the OAuth consumer secret. The consumer key and secret are generated when the integration is created.

  • Ask for a request token. A request token is a temporary token that the user exchanges for an access token. Use the following API to get a request token:

    POST /oauth/token/request

    See Get a request token for more details about this call.

  • Parse the request token response. The response contains an oauth_token and oauth_token_secret.

  • Ask for an access token. The request token must be exchanged for an access token. Use the following API to get a request token:

    POST /oauth/token/access

    See Get an access token for more details about this call.

  • Parse the access token response. The response contains an oauth_token and oauth_token_secret. These values will be different than those provided in the request token response.

  • Save the access token and other OAuth parameters. The access token and OAuth parameters must be specified in the Authorization header in each call to Commerce.

Related Topics#

  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.