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
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. 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 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 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. 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 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 the sync engine<components/integrations_sync:Sync engine>.

Integration Builders

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

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