My Fist Developer Feature: The BlancoWorld Notification Framework

A Call for Beta Testers . . .

Have you ever had a list with a date/time column (e.g. a column called "Review Date") and you wanted some custom notification functionality to execute 'x' days prior to the date, on the actual date, or 'y' days after the date for each list item in the list?

Are you sick of developing SPJobDefinition classes that simply trawl lists within site collections and implement some custom functionality when a date on that list has expired?

Welcome to the BlancoWorld Notification Framework . . . .

Installing / Deploying the BlancoWorld Notification Framework

The BlancoWorld Notification Framework is installed as a SharePoint Solution (BlancoWorld.NotificationFramework.wsp) and once installed and deployed it presents itself as an additional link in the Central Administration site accessed via the "Application Management" tab:

Configuring the BlancoWorld Notification Framework

Clicking on the "Manage BlancoWorld notification framework" link displays a management page allowing you to specify the web applications and site collections for which the BlancoWorld Notification Framework is enabled and how often the functionality executes:

Using this form, select the appropriate Web Application, and select whether to enable or disable the functionality for each Site Collection in the selected Web Application. Finally specify how often the functionality should run for the selected Web Application (e.g. every 10 minutes) – the BlancoWorld Notification Framework runs as a timer job and hence can be scheduled to run every 'x' minutes for each Web Application.

Once the functionality has been enabled for a particular site collection then the link shown below will be displayed on the list settings page for each list within that site collection:

Clicking on the "Item notification settings" link from the list settings page for a particular list allows you to specify the notification settings for items in that list:

Tick the "Item Notification Functionality Enabled" checkbox to enable the BlancoWorld Notification Framework functionality on the list. You must then specify the following information:

• The column on which to calculate whether or not to raise notifications – the "Column to Interrogate" drop-down list details all of the Date/Time columns defined on the list. Select the desired column on which to calculate whether or not to raise notifications.
• The full assembly name and class name of the type implementing the BlancoWorld Notification Framework Event Handler (see below for details).
• The Desired Notification Settings – a list can be configured for Pre-Notifications (i.e. notifications raised 'x' days before the date/time specified in the selected column); Notifications (i.e. notifications raised when the actual date/time specified in the selected column is exceeded); and Post-Notifications (i.e. notifications raised 'y' days after the date/time specified in the selected column). Post notifications can also be specified to be recurring i.e. raised EVERY 'y' days after the date/time specified in the selected column.

BlancoWorld Notification Framework Event Handler
What happens when a notification (a pre-notification, a notification, or a post-notification) is raised by the BlancoWorld Notification Framework? This totally depends on the assembly name and class name defined in the list settings above i.e. whatever you implement will happen! To define the functionality that is executed when a notification is raised, you need to develop a class that implements the BlancoWorld.NotificationFramework.INotificationFrameworkEventReceiver interface:
public interface INotificationFrameworkEventReceiver
{
    void ItemPreNotification(
        NotificationEventProperties properties);
    void ItemNotification(
        NotificationEventProperties properties);
    void ItemPostNotification(
        NotificationEventProperties properties);
}

This interface defines three methods: ItemPreNotification; ItemNotification; and ItemPostNotification. Define a class that inherits from this interface (by adding a reference to the "BlancoWorld.NotificationFramework.dll" in your project, and adding a using directive for the BlancoWorld.NotiticationFramework namespace). In each method, define your desired functionality – note that a useful parameter called properties is passed into each method containing information such as the web URL, site ID, SPListItem, List Item ID etc.). An example implementation can be seen below:

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using BlancoWorld.NotificationFramework;
using Microsoft.SharePoint;

namespace BlancoWorld.TestNotificationFramework
{
    public class TestEventHandler :
        INotificationFramworkEventReceiver
    {
        private const String TEST_OUTPUT_FILE =
            @"C:\Temp\TEST_NOTIFICATION_FRAMEWORK.txt";

        public void ItemPreNotification(
            NotificationEventProperties properties)
        {
            WriteToTestFile(String.Format(
            "ItemPreNotification - {0}",
            GeneratePropertyString(properties)));
        }

        public void ItemNotification(
            NotificationEventProperties properties)
        {
            WriteToTestFile(String.Format(
            "ItemNotification - {0}",
            GeneratePropertyString(properties)));
        }

        public void ItemPostNotification(
            NotificationEventProperties properties)
        {
            WriteToTestFile(String.Format(
            "ItemPostNotification - {0}",
            GeneratePropertyString(properties)));
        }

        private String GeneratePropertyString(
            NotificationEventProperties properties)
        {
            return String.Format(
            "WebUrl={0}, ListName={1}, ListItem={2}",
            properties.WebUrl,
            properties.ListTitle,
            properties.ListItem.Title);
        }

        private void WriteToTestFile(string message)
        {
            if (message.Length > 0)
            {
                StreamWriter sw = null;
                try
                {
                    sw = File.AppendText
                        (TEST_OUTPUT_FILE);
                    string traceLine =
                        String.Format("{0}{1}",
                        DateTime.Now.ToString(
                            "dd/MM/yyyy HH:mm:ss.ffff").PadRight(30),
                        message);
                        sw.WriteLine(traceLine);
                        sw.Flush();
                }
                catch (Exception)
                {
                }
                finally
                {
                    if (sw != null)
                        sw.Close();
                }
            }
        }
    }
}

The sample class defined above simply outputs information to a debugging file (C:\Temp\TEST_NOTIFICATION_FRAMEWORK.txt) whenever a notification is raised.

Build your class and then add your assembly to the GAC. When specifying the list settings (as detailed above) detail the full assembly name and class name e.g.

Class Name: BlancoWorld.TestNotificationFramework.TestEventHandler

Assembly Name: BlancoWorld.TestNotificationFramework, Version=1.0.0.0, Culture=neutral, PublicKeyToken=58a25bc3a52786ea

Conclusion
The BlancoWorld Notification Framework is a framework allowing you, the SharePoint developer, to worry about what happens regarding dates defined on list items in SharePoint lists without having to worry about implementing custom SPJobDefinitions. Simply follow the steps define below:

1. Install the BlancoWorld Notification Framework.
   
2. Configure the BlancoWorld Notification Framework via Central Administration for the desired Web Application and Site Collection.
   
3. Define a class that implements the BlancoWorld.NotificationFramework.INotificationFrameworkEventReceiver interface and define the custom functionality YOU want to execute 'x' days before a date, when that date expires, or 'y' days after a date by implementing the ItemPreNotification; ItemNotification; and ItemPostNotification methods.
   
4. Build your assembly, and add your assembly to the GAC.
   
5. Configure the BlancoWorld Notification Framework for the desired list by configuring the list settings for that list and specifying the column, full assembly name, full class name, and the desired notification settings.
   
6. Sit back and let the BlancoWorld Notification Framework do the rest.

I've tested this add-on to some extent, but would welcome the opportunity to open this up to the wider SharePoint audience. Eventually I'll add this to my CodePlex project (where the Event Receiver Manager lives) but for the time being I'd like a few beta-testers to try this out and let me have their feedback. If you're interested in beta testing, email me at chris at blancoworld dot co dot uk and I'll email you the SharePoint Solution for you to try out . . . I'll create another blog posting when this is released via CodePlex.