.png?width=667&height=667&ext=.png)
Bit.ly Metrics Module for Kentico CMS
My Latest Kentico CMS Module
Today I am pleased to announce my latest contribution to the Kentico developer community, the Bit.ly Metrics Module for Kentico CMS 7.0. The purpose of this module is to bring everything you need into Kentico CMS when it comes to using the Bit.ly URL Shortening service. The module gives you a way to see all of your Bit.ly metrics, aka user link history, as a custom Tool in the CMSDesk and at the page or document level. The data for each shortened link is stored in a custom table, and it is kept in sync using the Integration Bus component of Kentico CMS.
The Bit.ly Metrics module also gives content editors the ability to shorten any Document URL right from within the CMSDesk. Utilizing this module saves you or your content administrators the time of jumping out and logging into the backend of Bit.ly to see how often your links are being clicked. My favorite part about it is that with one click I can sort the data and compare how often one or more of my links are being clicked.
Background
Modules in Kentico CMS represent groups of functionality in Kentico. They can be a set of web parts, scheduled tasks, custom settings, and just about anything else in the platform. They are a great way to extend the system to allow for custom functionality. They are also easily exportable from one instance of Kentico to another. This module is a result of my presentation last fall at Kentico Connection 2012 about integrating with Kentico CMS. I demo’d the functionality to the audience during my session, but time flies fast, and I did not have a chance to finish it until a few days ago.
I really think that the Integration Bus functionality is under utilized component in Kentico. It can be a great way to synchronize data from CRM or ERP systems, or as data is created and updated in Kentico the bus can push information to external systems as needed. You can think of it as the heartbeat of the system.
How It Works
The main component to the module is a custom Integration Bus Connector. The Integration Bus function of Kentico CMS let’s developers re-act to different activities within the CMS and fire custom functionality as needed for whenever certain events happen like publishing a document or adding a custom table item. The Integration Bus also works in the reverse. That is, the system can also re-act to external system events, and creating objects or data inside of Kentico as needed.
For this module, every day on a scheduled basis, the process will run to hit the Bit.ly API service and return a specified user’s link history. In essence it responds to the external data at Bit.ly. The results of the API calls are saved into a custom table named BitlyMetrics. If the process sees a match between the shortened URL’s long URL, it also ties the link history to the matching Document in the content tree. From there the module uses a set of UI Elements to handle customizing the CMSDesk user interface.
The last benefit of using a module is that if you follow the correct convention and naming structure, all of the code files of a module will be exported with the database settings as well, creating one zip file that you can use to pick up and move or copy your entire feature from one Kentico instance to another. For the full details on creating custom Kentico CMS Modules check out the official documentation. Scroll way down to the bottom of that page to see the naming conventions.
The Result
The result is a new Tool inside of CMSDesk as well as a new Page tab for each individual Node in the Document Tree. If you have a short URL that represents the current Document in the Content Tree you can click the new Bitly sub tab to see that document’s metrics.
The module also gives CMSDesk users the ability to directly shorten any Document in the content tree. You should see this for any Document in the Content Tree that has not been shortened. One note here: you have to make sure that the Custom Settings are correctly filled in first before the integration will work. More on that later in this post.
The last feature revolves around the unigrid on the Tools page of the module. This page includes a filter to easily show you only internal Document results that match Bit.ly short URLs. In the screen shot below you can see that I have the Include Document Matches Only value set to Yes. This hides external links that you might have shortened at Bit.ly. For some users this may not be necessary, but if you are a heavy Bit.ly user you will probably enjoy this filter.
All of these new tabs are available through the great UI Personalization feature of Kentico CMS. UI Personalization lets me add in and secure all of these custom tabs without having to write one extra line of code. I love it.
Integration Bus Connector Details
The following section is about the technical details of the module. You can skip this part if you are looking to download and use the module directly.
Like I mention the key piece of functionality is the custom Integration Bus Connector. Below is the source code to the connector class itself in ~/App_Code/CMSModules/BitlyIntegration/BitlyIntegrationConnector.cs. This class handles the registration of the inbound connector. This code is about as simple as it gets. In the Init method you register your connector name to match the code name of the connector that is you setup in CMSSiteManager –> Administration –> Integration Bus –> Connectors. Once initialized the class’s connector name successfully ties the Integration Bus to your custom code. There are more advanced possibilities to respond to inbound events, like translating the unique key of the object to an existing object inside of Kentico, but for this scenario I wanted to keep it as simple as possible. To learn more about the other options I recommend watching this great webinar wrap-up on the Integration Bus by Miro Remias.
using CMS.EventLog; using CMS.SettingsProvider; using CMS.Synchronization; using CMS.SynchronizationEngine;
////// Integration connector demonstrating simplest functionality. /// public class BitlyIntegrationConnector : BaseIntegrationConnector { ////// Initialize connector name /// public override void Init() { // Initialize connector name (it has to match the code name of connector stored in DB) ConnectorName = "BitlyIntegrationConnector"; //This is an incoming Connector, no subscriptions needed. } public override void ProcessExternalTask(object obj, IntegrationProcessTypeEnum result, TaskTypeEnum taskType, TaskDataTypeEnum dataType, string siteName) { EventLogProvider eventLog = new EventLogProvider(); eventLog.LogEvent(EventLogProvider.EVENT_TYPE_INFORMATION, DateTime.Now, ConnectorName, "ProcessExternalTasks" + taskType.ToString(), 0, null, 0, null, null, "Starting to Process", 0, null); BitlyIntegrationWorker.LoadMetrics(); } public override void ProcessExternalTasks() { EventLogProvider eventLog = new EventLogProvider(); eventLog.LogEvent(EventLogProvider.EVENT_TYPE_INFORMATION, DateTime.Now, ConnectorName, "ProcessExternalTasks", 0, null, 0, null, null, "Starting to Process", 0, null); BitlyIntegrationWorker.LoadMetrics(); } }
Another aspect to remember is how the connector is triggered. Normally the external system would be creating the data you would want to push into Kentico. But in this situation the Bit.ly service does not have any webhooks, it only has the the Bit.ly API that your application has to initiate call itself. Kentico has already covered this situation though. There are two ways to actually trigger an inbound or external system event from within the CMS itself. Option 1 is to use a special hidden page in any normal Kentico installation at ~/CMSPages/IntegrationNotify.aspx. Running this page will trigger and run any enabled Integration Bus Connector that you have setup. Calling that page with a query string variable of ConnectorName will trigger just that single Connector to run, i.e. ~/CMSPages/IntegrationNotify.aspx?ConnectorName=BitlyIntegrationConnector would cause just my connector to run.
ProTip: If you are not using the Integration Bus service in your Kentico CMS 7 installation you should delete or disable this page
The second option you have to trigger an inbound event in Kentico CMS is a predefined scheduled task named, Process external integration tasks. This is the method I am using inside of this module. This allows you to schedule when your Integration Bus Connector should run. The default for the Bitly Metric Module is every 1 day. This global schedule task just needs to have the ConnectorName in the Task Data attribute of the scheduled task itself. The default import package will replace this scheduled task with one configured to pass BitlyIntegrationConnector in for you.
That is all you need to know about creating an inbound or external Integration Bus Connector for Kentico CMS.
Custom Settings Details
The Bit.ly Metrics Module also installs a few new Custom Settings into the Kentico instance. These settings handle storing the API URL to Bit.ly incase it ever changes and the required keys for things like your ClientID, ClientSecretID, and AccessToken. All of this is covered in the installation instructions that is included with the download, however it is a bit tricky to get your OAuth access token. I recommend also reading the Bit.ly developer centers guide at: http://dev.bitly.com/oauth_access_token.html.
ProTip: Using Custom Settings in Kentico is a great alternative to storing custom configuration settings in the web.config’s applicationSettings nodes. Changing a setting will not restart your site if you use the Settings in Kentico like it would if you re-saved your web.config file.
Download
You can download a copy of the Bit.ly Metric Module for Kentico CMS here, as well as at the Kentico Marketplace. I have tested this Module in version 7.0.18+ of Kentico CMS and Kentico EMS. Installation instructions are included in the download as a PDF.
One thing to remember about the code, right now I have the installer setting up Bit.ly Metrics Tools top tab in the Web Analytics section of the site. This means Kentico CMS free and basic editions won’t see it by default because they don’t have the Web Analytics module available to them. If you are a free or basic edition user you can comment out lines 16 – 19 in the ~/CMSModules/BitlyIntegration/BitlyAnalytics.cs file. and move the Tab to another category via the UI Personalization tab. If I get enough feedback on it, I will create a second package for those users.
Conclusion
Leave me any feedback you may have about the Bit.ly Metric Module in the comments on this post, or as always, feel free to contact me at anytime.
