Categories: Magento News

Magento 2 Tutorial: How to Create an Intergration

AnÂ integrationÂ enables third-party services to call the Magento web APIs. The Magento APIs currently supports Accounting, Enterprise Resource Planning (ERP), Customer Relationship Management (CRM), Product Information Management (PIM), and marketing automation systems out of the box.

In this tutorial, I will present you the way to create an intergration in magento 2.Â Before you begin creating a module, make sure that you have a working installation of Magento 2.0, and theÂ Magento System Requirements.

To create an integration, follow these general steps:

Create a module with the minimal structure and configuration
Add files specific to the integration
Install the module
Check the integration
Integrate with your application

Table of Contents

Toggle

A. Create a skeletal module

To develop a module, you have to:

1. Create the module file structure.

The module for an integration can be placed anywhere under the Magento root directory, but the recommended location isÂ <magento_base_dir>/vendor/<vendor_name>/module-<module_name>.

Also createÂ etc,Â etc/integration, andÂ SetupÂ subdirectories underÂ module-<module_name>, as shown in the following example:

 cd <magento_base_dir>
 mkdir -p vendor/<vendor_name>/module-<module_name>/etc/integration
 mkdir -p vendor/<vendor_name>/module-<module_name>/Setup

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:

Attribute	Description
name	A string that uniquely identifies theÂ module.
setup_version	The version of Magento the component uses

The following example shows an exampleÂ etc/module.xmlÂ file.

<?xml version="1.0"?>
<!--
   /**
   * Copyright Â© 2015 Magento. All rights reserved.
   * See COPYING.txt for license details.
   */   -->
   <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
       <module name="Vendor1_Module1" setup_version="2.0.0">
            <sequence>
                <module name="Magento_Integration"/>
            </sequence>
       </module>
     </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.

4. Create aÂ `registration.php`Â file

TheÂ registration.phpÂ registers the module with the Magento system. It must be placed in the moduleâ€™s root directory.

   <?php
     /**
     * Copyright Â© 2015 Magento. All rights reserved.
     * See COPYING.txt for license details.
     */
     \Magento\Framework\Component\ComponentRegistrar::register(
     \Magento\Framework\Component\ComponentRegistrar::MODULE,
     'Vendor1_Module1',
     __DIR__
     );

5. Create an install class

Change directories to yourÂ SetupÂ directory. Create aÂ InstallData.phpÂ file that installs the integration configuration data into the Magento integration table.

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

 <?php
 namespace Vendor1\Module1\Setup;

 use Magento\Framework\Setup\ModuleContextInterface;
 use Magento\Framework\Setup\ModuleDataSetupInterface;
 use Magento\Integration\Model\ConfigBasedIntegrationManager;
 use Magento\Framework\Setup\InstallDataInterface;

 class InstallData implements InstallDataInterface
 {
     /**
      * @var ConfigBasedIntegrationManager
      */

     private $integrationManager;

     /**
      * @param ConfigBasedIntegrationManager $integrationManager
      */
     public function __construct(ConfigBasedIntegrationManager $integrationManager)
     {
         $this->integrationManager = $integrationManager;
     }

     /**
      * {@inheritdoc}
      */
     public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
     {
         $this->integrationManager->processIntegrationConfig(['testIntegration']);
     }
 }

In the following line$this->integrationManager->processIntegrationConfig(['testIntegration']);

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

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

B. Create integration files

Magento provides the Integration module, which simplifies the process of defining your integration. This module automatically performs functions such as:

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

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

The process for customizing your module includes 2 steps:Â Define the required resources,Â Pre-configure the integration.

1. 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:

<integrations>
    <integration name="testIntegration">
        <resources>
            <!-- To grant permission to Magento_Log::online, its parent Magento_Customer::customer needs to be declared as well-->
            <resource name="Magento_Customer::customer" />
            <resource name="Magento_Log::online" />
            <!-- To grant permission to Magento_Sales::reorder, all its parent resources need to be declared-->
            <resource name="Magento_Sales::sales" />
            <resource name="Magento_Sales::sales_operation" />
            <resource name="Magento_Sales::sales_order" />
            <resource name="Magento_Sales::actions" />
            <resource name="Magento_Sales::reorder" />
        </resources>
    </integration>
</integrations>

2. Pre-configure the integration

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

If you pre-configure the integration, the values cannot be edited from theÂ adminÂ panel.

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

Element	Description
integrations	Contains one or more integration definitions.
integration name=””	Defines an integration. TheÂ `name`Â must be specified.
email	An email to associate with this integration.
endpoint_url	Optional. TheÂ URLÂ where OAuth credentials can be sent when using OAuth for token exchange. We strongly recommend usingÂ `https://`.
identity_link_url	Optional. The URL that redirects the user to link their 3rd party account with the Magento integration.

C. Install your module

Use the following steps to install your module:

Run the following command to update the MagentoÂ database schemaÂ and data.bin/magento setup:upgrade
Run the following command to generate the new code.bin/magento setup:di:compile

D. Check your integration

Log in to Magento 2 and navigate toÂ Settings > Extensions > Integrations. The integration should be displayed in the grid.

E. Integrate with your application

Before you can activate your integration in Magento 2, 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.

1. Login page

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

2. Callback page

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

Receive an initial HTTPS POST that Magento sends when the merchant activates integration. This post contains the Magento 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 from Magento:POST /oauth/token/request
Parse the request token response. The response contains anÂ oauth_tokenÂ andÂ oauth_token_secret.
Ask for a access token. The request token must be exchanged for an access token. Use the following API to get a request token from Magento:POST /oauth/token/access
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 Magento.