Example - Integration connector

The default installation of Kentico provides a sample integration connector. The connector implements two subscriptions for outgoing tasks:

  • Synchronization of user objects
  • Synchronization of all documents on all websites in the system

The connector’s purpose is purely demonstrative — it only logs events in the Event log application for each creation, modification or deletion of a user or document.

Adding the sample connector to your web project

  1. Open your Kentico installation directory (by default C:\Program Files\Kentico\<version>).
  2. Expand the CodeSamples\App_Code Samples\ sub-directory.
  3. Copy the Samples folder into the CMS\App_Code folder of your web project.

Information for web application projects

If your Kentico project was installed as a web application, copy the samples into the Old_App_Code folder instead.

You must also manually include the sample class files into the project:

  1. Open your application in Visual Studio.
  2. Click Show all files at the top of the Solution Explorer.
  3. Expand the Old_App_Code folder, right-click the new Samples sub-folder and select Include in Project.

Viewing the connector code

To see how the sample connector is implemented:

  1. Open your web project in Visual Studio.
  2. Expand the ~/App_Code/Samples/Classes folder and edit the SampleIntegrationConnector.cs class.



public class SampleIntegrationConnector : BaseIntegrationConnector
{
    #region "Initialization (subscribing)"

    /// <summary>
    /// Initializes the connector name and registers subscriptions.
    /// </summary>
    public override void Init()
    {
        // Initializes the connector name (must match the code name of the connector object in the system)
        ConnectorName = GetType().Name;

        // Creates subscription for all user objects (predefined method)
        SubscribeToObjects(TaskProcessTypeEnum.AsyncSnapshot, UserInfo.OBJECT_TYPE);

        // Create subscription for all documents on all sites (predefined method)
        SubscribeToAllDocuments(TaskProcessTypeEnum.AsyncSimpleSnapshot, TaskTypeEnum.All);

        // Demonstrates how to create subscriptions manually
        // ObjectIntegrationSubscription objSubscription = new ObjectIntegrationSubscription(ConnectorName, TaskProcessTypeEnum.AsyncSnapshot, TaskTypeEnum.All, null, PredefinedObjectType.USER, null);
        // SubscribeTo(objSubscription);

        // DocumentIntegrationSubscription docSubscription = new DocumentIntegrationSubscription(ConnectorName, TaskProcessTypeEnum.AsyncSimpleSnapshot, TaskTypeEnum.All, null, null, null, null);
        // SubscribeTo(docSubscription);
    }

...


To be functional, every connector must have the ConnectorName property initialized in the Init() method. The value must match the code name of the connector object registered in the system. The sample connector uses the name of the ConnectorName – SampleIntegrationConnector.

The sample connector is defined in the App_Code folder, so the file contains code that allows the system to load the class when working with the connector — the RegisterCustomClass assembly attribute declared above the SampleIntegrationConnector class. See Loading custom classes from App_Code for more information.




[assembly: RegisterCustomClass("SampleIntegrationConnector", typeof(SampleIntegrationConnector))]


The RegisterCustomClass attribute accepts two parameters:

  • The first parameter is a string identifier representing the name of the connector class. The name must match the value of the Class name field specified for the given connector object in the system (SampleIntegrationConnector in this example).
  • The second parameter specifies the type of the class as a System.Type object.

Registering the connector

  1. Log in to the Kentico administration interface.

  2. Open the Integration bus application.

  3. Select the Connectors tab.

  4. Click New connector.

  5. Fill in the following properties:

    • Display name: Sample integration connector
    • Provider class - Assembly name: (custom classes)
    • Provider class - Class: SampleIntegrationConnector
    • Enabled: Yes (checked)
  6. Click Save.

Testing the connector

  1. Open the Settings application.

  2. Select the Integration -> Integration bus category.

  3. Adjust the settings as follows:

    • Enable system integration bus: yes (checked)
    • Enable logging of incoming tasks: no (unchecked)
    • Enable processing of incoming tasks: no
    • Enable logging of outgoing tasks: yes
    • Enable processing of outgoing tasks: no

The sample connector only generates outgoing tasks, so you can leave handling of incoming tasks disabled. Disabling processing of outgoing tasks allows you to see the integration tasks in the user interface. If you enable processing, the system executes the tasks immediately and you only see the results in the event log.

  1. Click Save.

  2. Try creating and modifying some documents and user accounts.

  3. Open the Integration bus application. On the Outgoing tasks tab, you can see a list of tasks logged for your actions. The Synchronize () action is grayed out, since processing of tasks is disabled in the system settings.

    Viewing outgoing integration tasks

  4. Go back to Settings -> Integration -> Integration bus, check Enable processing of outgoing tasks and click Save.

  5. Return to Integration bus -> Outgoing tasks. The Synchronize () action is now enabled.

  6. To execute all tasks:

    1. Select All tasks in the first selector below the list.
    2. Choose the Synchronize action.
    3. Click OK.

You can see the events logged by the integration tasks in the Event log application.

Events logged by the sample integration connector