integrations.rst

Integrations

Each Integration provides its unique name as registered with Mautic, an icon, and a display name. When an Integration registers, the Integration helper classes manage the \Mautic\PluginBundle\Entity\Integration object through \Mautic\IntegrationsBundle\Integration\Interfaces\IntegrationInterface. It handles decryption and encryption of the Integration's API keys, so the implementing code never has to.

---

Registering the integration

All Integrations, whether using the config, auth, or sync interfaces, must have a class that registers itself with Mautic. The Integration should list on the /s/plugins UI route.

In the Plugin's Config/config.php, register the Integration using the tag mautic.basic_integration.

<?php
return [
    // ...
    'services' => [
        // ...
        'integrations' => [
            'helloworld.integration' => [
                'class' => \MauticPlugin\HelloWorldBundle\Integration\HelloWorldIntegration::class,
                'tags'  => [
                    'mautic.basic_integration',
                ],
            ],
            // ...
        ],
        // ...
    ],
    // ...
];

The HelloWorldIntegration needs to implement \Mautic\IntegrationsBundle\Integration\Interfaces\IntegrationInterface and \Mautic\IntegrationsBundle\Integration\Interfaces\BasicInterface interfaces. Most use cases can simply extend the \Mautic\IntegrationsBundle\Integration\BasicIntegration abstract class.

.. php:class:: \Mautic\IntegrationsBundle\Integration\BasicIntegration

.. php:method:: public function getName(): string;

    :return: Return the Integration's name.
    :returntype: string

.. php:method:: public function getDisplayName(): string;

    :return: Return the Integration's display name.
    :returntype: string

.. php:method:: public function getIcon(): string;

    :return: Get the path to the Integration's icon.
    :returntype: string

<?php
namespace MauticPlugin\HelloWorldBundle\Integration;

use Mautic\IntegrationsBundle\Integration\BasicIntegration;
use Mautic\IntegrationsBundle\Integration\Interfaces\BasicInterface;
use Mautic\IntegrationsBundle\Integration\Interfaces\IntegrationInterface;

class HelloWorldIntegration extends BasicIntegration
{
    const NAME = 'HelloWorld';

    public function getName(): string
    {
        return self::NAME;
    }

    public function getDisplayName(): string
    {
        return 'Hello World';
    }

    public function getIcon(): string
    {
        return 'plugins/HelloWorldBundle/Assets/img/helloworld.png';
    }
}

Integration authentication

If the Integration requires authentication with the third party service:

1. :ref:`Register the Integration<components/integrations_authentication:Register the Integration for Authentication>` as an Integration that requires authentication options.
2. Create a custom Symfony Form type for the required credentials and return it as part of the :ref:`config interface<components/integrations_configuration:ConfigFormAuthInterface>`.
3. Create a custom service that builds and configures the Guzzle client required to authenticate and communicate with the third party service. Use an :ref:`existing supported factory or create a new one<components/integrations_authentication:Authentication Providers>`.

Integration configuration

If the Integration has extra configuration settings for features unique to it:

1. :ref:`Register the Integration<components/integrations_configuration:Register the Integration for configuration>` as an Integration that requires configuration options.
2. Create a custom Symfony Form type for the features and return it as part of the :ref:`Config Form feature setting interface<components/integrations_configuration:ConfigFormFeatureSettingsInterface>`.

Integration sync engine

If the Integration syncs with Mautic's Contacts and/or Companies:

1. Read about :ref:`the sync engine<components/integrations_sync:Sync engine>`.

Integration Builders

If the Integration includes a Builder, Email, or Landing Page:

1. :ref:`Register the Integration<components/integrations_builder:Register the Integration as a builder>` as an Integration that provides a custom builder.
2. Configure what featured builders the Integration supports (Mautic currently supports 'Email' and 'Landing Page' builders).

Config Form Notes Interface

The interface, \Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormNotesInterface, provides a way to add notes, either info or warning, to the Plugin configuration form.

Read more about to how-tos :ref:`Integration Configuration Form Notes<components/integrations_configuration_form_notes:Integration configuration form notes>`