Configuration integration

The Integration Plugin provides interfaces to display and store configuration options. You can use the \Mautic\PluginBundle\Entity\Integration object for that.

Register the Integration for Configuration

To tell the IntegrationsBundle that this Integration has configuration options, tag the Integration or support class with mautic.config_integration in the Plugin’s app/config.php.

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

The ConfigSupport class must implement \Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormInterface.

\Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormInterface

public function getDisplayName(): string;

Returns:: Return the Integration’s display name.
Return type:: string

public function getConfigFormName(): ?string;

Returns:: The name/class of the Form type to override the default or just return NULL to use the default.
Return type:: ?string

public function getConfigFormContentTemplate(): ?string;

Returns:: The template to use from the controller. Return null to use the default.
Return type:: ?string

Find the code snippet as follows,

<?php
namespace MauticPlugin\HelloBundle\Integration\Support;

use MauticPlugin\HelloWorldBundle\Form\Type\ConfigAuthType;
use Mautic\IntegrationsBundle\Integration\DefaultConfigFormTrait;
use Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormInterface;
use Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormAuthInterface;

class ConfigSupport implements ConfigFormInterface, ConfigFormAuthInterface
{
    use DefaultConfigFormTrait;

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

    /**
     * Return a custom Symfony form field type class that will be used on the Enabled/Auth tab.
     * This should include things like API credentials, URLs, etc. All values from this form fields
     * will be encrypted before being persisted.
     *
     * @link https://symfony.com/doc/4.4/form/create_custom_field_type.html#defining-the-form-type
     *
     * @return string
     */
    public function getAuthConfigFormName(): string
    {
        return ConfigAuthType::class;
    }
}

Interfaces

There are multiple interfaces that you can use to add Form Fields options to the provided configuration tabs.

Enabled/auth tab

These interfaces provide the configuration options for authenticating with the third party service. Read more about how to use IntegrationsBundle’s auth providers here.

ConfigFormAuthInterface

The \Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormAuthInterface interface provides the Symfony Form type class that defines the fields to get stored as the API keys.

\Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormAuthInterface

public function getAuthConfigFormName(): string;

Returns:: The name of the Form type service for the authorization tab which should include all the fields required for the API to work.
Return type:: string

Find the following code snippet which helps you to fetch the API keys,

<?php
$apiKeys  = $integrationHelper->get(HelloWorldIntegration::NAME)->getIntegrationConfiguration()->getApiKeys();
$username = $apiKeys['username'];

ConfigFormCallbackInterface

If the Integration leverages an auth provider that requires a callback URL or something similar, this interface, \Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormCallbackInterface, provides a means to return a translation string to display in the UI. For example, OAuth2 requires a redirect URI. If the administrator has to configure the OAuth credentials in the third party service and needs to know what URL to use in Mautic as the return URI, or callback URL, use the getCallbackHelpMessageTranslationKey() method.

\Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormCallbackInterface

public function getCallbackHelpMessageTranslationKey(): string;

Returns:: Message ID used in Form as description what for is used callback URL.
Return type:: string

Feature interfaces

ConfigFormFeatureSettingsInterface

The interface \Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormFeatureSettingsInterface provides the Symfony Form type class. It determines what fields to display on the Features tab. These values aren’t encrypted.

\Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormFeatureSettingsInterface

public function getFeatureSettingsConfigFormName(): string;

Returns:: The name of the Form type service for the feature settings.
Return type:: string

<?php
$featureSettings  = $integrationHelper->get(HelloWorldIntegration::NAME)->getIntegrationConfiguration()->getFeatureSettings();
$doSomething      = $featureSettings['do_Something'];

ConfigFormFeaturesInterface

Currently the IntegrationsBundle provides default features. To use these features, implement this, \Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormFeaturesInterface, interface. getSupportedFeatures returns an array of supported features. For example, if the Integration syncs with Mautic Contacts, getSupportedFeatures() could return [ConfigFormFeaturesInterface::FEATURE_SYNC];.

\Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormFeaturesInterface

public const FEATURE_SYNC = 'sync';

public const FEATURE_PUSH_ACTIVITY = 'push_activity';

public function getSupportedFeatures(): array;

Returns:: An array of value => label pairs for the features this Integration supports.
Return type:: array[]

Contact/Company syncing interfaces

The IntegrationsBundle provides a sync framework for third party services to sync with Mautic’s Contacts and Companies. The \Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormSyncInterface determines the configuration options for this sync feature. Refer to the method DocBlocks in the interface for more details.

Read more about how to leverage the sync framework.