Creating integration connectors

The process of creating an integration connector consists of two general steps:

  1. Add a class containing the required connector code to your project
  2. Register the connector in the Xperience administration interface

Adding connector classes

Develop the connector class within a separate assembly according to the following steps:

  1. Create a Class Library project in Visual Studio (for example name it CustomIntegrationConnectors).

  2. Add references to the Xperience API libraries:

    • If the connector project is standalone, install the Kentico.Xperience.Libraries NuGet package (see Using the Xperience API externally for details).
    • If you are adding the connector project to your Xperience administration solution, reference the DLL files directly:
      1. Right-click the project and select Add reference…
      2. Click Browse…
      3. Add references to at least the following libraries from the project’s Lib directory:
        • CMS.Base.dll
        • CMS.Core.dll
        • CMS.DataEngine.dll
        • CMS.DocumentEngine.dll
        • CMS.Synchronizationd.dll
        • CMS.SynchronizationEngine.dll
  3. Reference the custom class library project from the Xperience project. When implementing outgoing synchronization, you need to reference the custom class library from both the live site (MVC) and Xperience administration projects. This ensures that the synchronization works for objects created or modified by the live site application (for example users, form data, customers and their orders).

  4. Create a class in the project and make it inherit from BaseIntegrationConnector.

  5. Override the Init() method and set the ConnectorName property within this method.

    • The value of the ConnectorName property must match the code name of the connector object registered in the administration interface.

      
      
      
        using CMS.Synchronization;
        using CMS.SynchronizationEngine;
      
        public class CustomIntegrationConnector : BaseIntegrationConnector
        {
            /// <summary>
            /// Initializes the connector name.
            /// </summary>
            public override void Init()
            {
                // Initializes the connector name
                // Must match the code name of the connector object registered in the system
                // GetType().Name uses the name of the class as the ConnectorName
                ConnectorName = GetType().Name;
            }
        }
      
      
        
  6. Save all changes and Rebuild the solution.

With the basic structure of the connector class prepared, you now need to implement outgoing and/or incoming synchronization.

You can find a simple example of a connector class on the Example - Integration connector page.

Registering connectors in the system

Once the connector’s class is ready, you need to register the connector as an object in the system:

  1. In the Xperience administration interface, open the Integration bus application.

  2. Select the Connectors tab.

  3. Click New connector.

  4. Fill in the Display name, Assembly name and Class and select the Enabled check box.

    Property

    Description

    Display name

    The name of the connector displayed in the interface.

    Code name

    Sets a unique identifier for the connector. Must match the value of the ConnectorName property declared in the connector’s class.

    Provider class

    Selects the class where the connector is implemented:

    • Assembly name – the assembly (project) containing the connector class.
    • Class – the exact class (including any namespaces) that defines the functionality of the connector.

    Enabled

    Indicates if the connector logs and processes integration tasks. Logging and processing of tasks must also be enabled in Settings -> Integration -> Integration bus.

  5. Click Save.

Note: When you add, edit or delete a connector, the system re-initializes all defined connectors.

The system displays a warning icon () next to connectors that are not registered correctly. The most common causes of problems are:

  • The value of the ConnectorName property in the connector class’s Init method does not match the Code name.
  • Incorrect assembly or class name.