Enabling the sample integration connector

The default installation of Kentico CMS contains a sample integration connector. Two subscriptions for outgoing tasks are implemented in this connector — one for synchronization of all user objects, the second one for synchronization of all documents on all websites in the system. The connector's purpose is purely demonstrational — it only logs an event in Site Manger -> Administration -> Event log for each creation, modification or deletion of a user or document.

To add this sample to your web project:

1. Open your Kentico CMS installation directory (by default C:\Program Files\KenticoCMS\<version>).

2. Expand the CodeSamples\App_Code Samples\ sub-directory.

3. Copy the Samples folder into the App_Code folder of your web project.

InfoBox_Exclamation

Web application installations

If your Kentico CMS project was installed in the web application format, 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.

The following points summarize what needs to be done to enable the connector. Most of the steps have already been performed and are only described so that you can follow them when registering your own integration connectors.

1. Open your web project in Visual Studio, expand the ~/App_Code/Samples/Classes folder and edit the SampleIntegrationConnector.cs class, which implements the sample connector. To make the connector functional, you need to ensure that the ConnectorName property initialized in the Init() method has the same value as the code name of the connector registered in the system. For the purposes of this example, change the value of the property to SampleIntegrationConnector.

public class SampleIntegrationConnector : BaseIntegrationConnector

{

#region "Initialization (subscribing)"

/// <summary>

/// Initialize connector name and register subscriptions.

/// </summary>

public override void Init()

{

ConnectorName = "SampleIntegrationConnector";

// Create subscription for all user objects

ObjectIntegrationSubscription objSubscription = new ObjectIntegrationSubscription(ConnectorName, TaskProcessTypeEnum.AsyncSnapshot, TaskTypeEnum.All, null, PredefinedObjectType.USER, null);

// Create subscription for all documents (on all sites)

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

// Register earlier created subscriptions for current connector

SubscribeTo(objSubscription);

SubscribeTo(docSubscription);

// Please see implementation of ProcessInternalTaskAsync overloads (and eventually comments for the rest of the methods)

}

...

2. Expand the ~/App_Code/Samples/Modules folder and view the code of the SampleIntegrationModule.cs class.

A connector class can either be implemented in a standard assembly, or in App_Code (like the sample connector). For connectors added to the App_Code folder, you need to ensure that the system loads the appropriate class when working with the connector. The SampleIntegrationModule.cs class demonstrates how you can do this. For additional information related to this topic, see Registering custom classes in App_Code in the Kentico CMS Developer's Guide.

using CMS.SettingsProvider;

[SampleIntegrationConnectorLoader]
public partial class CMSModuleLoader
{
    public class SampleIntegrationConnectorLoaderAttribute : CMSLoaderAttribute
    {
        /// <summary>
        /// Called automatically when the application starts.
        /// </summary>
        public override void Init()
        {
            // Assigns a handler for the OnGetCustomClass event.
            ClassHelper.OnGetCustomClass += GetCustomClass;
        }

        /// <summary>
        /// Gets a custom class object based on the given class name.
        /// </summary>
        private static void GetCustomClass(object sender, ClassEventArgs e)
        {
            if (e.Object == null)
            {
                // Checks the name of the requested class.
                switch (e.ClassName)
                {
                    // Gets an instance of the SampleIntegrationConnector class.
                    case "SampleIntegrationConnector":
                        e.Object = new SampleIntegrationConnector();
                        break;
                }
            }
        }
    }
}

In the case of integration connectors, the value of the ClassName property of the ClassHelper_OnGetCustomClass handler's ClassEventArgs parameter matches the Class name specified for the given connector object in the system.

3. Open the Kentico CMS interface, go to Site Manager -> Administration -> Integration bus and select the Connectors tab. Click New connector.

integrationguide_clip0005

4. Fill in the following properties:

Display name	Name of the connector used in the system's administration interface.
Code name	Sets a unique name that serves as an identifier for the connector. This name must match the value of the ConnectorName property declared in the connector class (see step 1 above), so type in SampleIntegrationConnector.
Assembly name	Specifies the name of the assembly where the connector class is implemented. Enter App_Code for connectors implemented in the App_Code folder.
Class name	Specifies the exact class (including any namespaces) that defines the functionality of the connector. Enter SampleIntegrationConnector to load the sample connector class.
Enabled	Indicates if logging and processing of tasks by this connector is enabled. Logging and processing of tasks also needs to be enabled in Site Manger -> Settings -> Integration -> Integration bus in order for the connector to be functional.

integrationguide_clip0006

Click Save.

5. Go to Site Manger -> Settings -> Integration -> Integration bus and adjust the settings of the module as follows:

•Enable system integration bus: enabled

•Enable logging of incoming tasks: disabled

•Enable processing on incoming tasks: disabled

•Enable logging of outgoing tasks: enabled

•Enable processing of outgoing tasks: disabled

The sample connector only handles outgoing tasks, so all incoming task settings may stay disabled. The reason why you should also leave processing of outgoing tasks disabled is only demonstrational — it will allow you to see the logged tasks in the UI in the following step. If you enabled them, the tasks would be processed right off and you would only see the logged events in the event log.

6. With the settings adjusted, try creating and modifying some documents and users. After doing so, go to Site Manager -> Administration -> Integration bus. You should see tasks for the respective actions logged on the Outgoing tasks tab. As processing of the tasks is disabled by settings, the Synchronize () action is grayed out and can not be performed at the moment.

integrationguide_clip0008

7. Go back to Site Manger -> Settings -> Integration -> Integration bus and enable the Enable processing of outgoing tasks setting. Then, go back to Site Manager -> Administration -> Integration bus -> Outgoing tasks. The Synchronize () action should now be enabled. Instead of clicking the icon for each logged task, you can simply choose All tasks from the first drop-down list below the grid, choose Synchronize from the second one and click OK.

integrationguide_clip0003

8. Once all tasks are performed, you can go to Site Manger -> Administration -> Event log and see the events logged by the tasks.

integrationguide_clip0007

Help URL: http://devnet.kentico.com/docs/7_0/integrationguide/index.html?enabling_the_sample_integration_connector.htm