Capturing and Modifying Sharepoint Alerts Through Alert Handlers

Introduction

SharePoint assists users by providing optional alerts by email/SMS to get notification of changes in a list/library such as when an item is added, modified or deleted. These alerts are sent using a pre-defined template. Alert handlers allow developers to do some custom action when an alert is triggered.

Note: Alert handlers are triggered only for email alerts.

Scope

In this article we will explore how to capture email alerts with an alert handler and modify the Alert Template using a custom class.

Implementation

To create an alert handler we need to create a global assembly that contains a class that implements the "IAlertNotifyHandler" interface in the Microsoft.SharePoint assembly. The IAlertNotifyHandler interface contains only one method, "OnNotification" for intercepting the e-mail alert and to modify it.

Procedure

The procedure to do that is:

• Create and Deploy an Alert Notification Handler Assembly
• Create an Alert Template

Create and Deploy an Alert Notification Handler Assembly

To create an alert notification handler we need to create a public/shared assembly. Either you can use a Visual Studio Class Library project template or SharePoint Project template. In this example I am using the SharePoint Project Template to avoid signing and deployment overhead. Let us start.

Step 1: Open Visual Studio 2010 and create a new project. From the New Project window select the "Empty SharePoint Project" template and name it "SampleAlertHandler" and click "OK".

Step 2: In the next window (SharePoint Customization Wizard) give your website URL and select "Deploy as a farm solution" then click the "Finish" button.

Step 3: Add a new class file to the SampleAlertHandler project with the name "CustomAlertHandler". Now open CustomAlertHandler.cs and replace the code with the following snippet:

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;
namespace SampleAlertHandler
{
    public class CustomAlertHandler : IAlertNotifyHandler
    {
        public bool OnNotification(SPAlertHandlerParams ahp)
        {
            try
            {
                using (SPSite site = new SPSite(ahp.siteUrl + ahp.webUrl))
                {
                    using (SPWeb web = site.OpenWeb())
                    {
                        SPList list = web.Lists[ahp.a.ListID]; 
                        string to = ahp.headers["to"].ToString();
                        string subject = list.Title.ToString();
                        string body = string.Empty; 
                        var eventType = (SPEventType)ahp.eventData[0].eventType; 
                        if (eventType == SPEventType.Add)
                        {
                            body = "An item is added";
                        }
                        else if (eventType == SPEventType.Modify)
                        {
                            body = "An item is modified";
                        }
                        else if (eventType == SPEventType.Delete)
                        {
                            body = "An item is deleted";
                        }
                        SPUtility.SendEmail(web, true, false, to, subject, body);
                    }
                } 
                return true;
            }
            catch (Exception ex)
            {
                return false;
            }
        }
    }
}

In the code above we are modifying the Alert Template inside the OnNotification method, that is being called prior to sending the alert. The SPAlertHandlerParams (ahp) contains all the information about the alert. The ahp.headers includes email properties such as from, to, Subject etcetera from which we are fetching the recipient address (to). In this example, we are using title of the list (from which the alert is triggered) as the subject. To construct the email body we are using ahp.eventData[0].eventType (SPEventType) property that indicates the type of alert event occurred. Finally we are sending an email using the SendEmail method of the "SPUtility" class.

Step 4: Now our alert handler assembly is ready to deploy. Go to the Build menu and click "Deploy Solution". Assuming that the deloyment was successful, verify the presence of the SampleAlertHandler assembly in the GAC (C:\Windows\assembly).



Note: Take note of the Version and Public Key Token since we require these when creating the Alert Template.

Create an Alert Template

Alert Templates are XML files that define the content and appearance of both e-mail (alerttemplates.xml) and SMS (alerttemplates_sms.xml) alerts. Alert Templates are located in the "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\XML" folder.

In this example we only deal with an e-mail Alert Template (alerttemplates.xml). If you open the alerttemplates.xml you will see that there are 16 different AlertTemplate elements defined in it for various types of lists. The "Name" attribute of the AlertTemplate specifies the Template type.

Now we can create an Alert Template for our alert handler.

Step 1: Move to the 14 hive "TEMPLATE\XML" folder and make a copy of alerttemplates.xml and name it "custom_alerttemplates.xml".

Note: It is recommended to keep the original templates intact because any future SharePoint updates will overwrite your changes.

Step 2: Open the "custom_alerttemplates.xml" in Visual Studio or any other XML editor and locate the AlertTemplate element that is defined for the DocumentLibrary template type (since we are using the document library to test our notification handler in this example).

<AlertTemplate Type="List" Name="SPAlertTemplateType.DocumentLibrary">

Step 3: Locate the Properties element inside the AlertTemplate tag and add the following two elements to it.

<Properties>
<NotificationHandlerAssembly>SampleAlertHandler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=a3902394782e8e4e</NotificationHandlerAssembly>
<NotificationHandlerClassName>SampleAlertHandler.CustomAlertHandler</NotificationHandlerClassName>
......
......
</Properties>

Note: The PublicKeyToken must be the same as the one we noted earlier in the GAC

Step 4: Now we can change the default template of our website. Open a command window in the 14 hive "TEMPLATE\XML" folder and run the following command:

stsadm -o updatealerttemplates -filename "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\XML\custom_alerttemplates.xml" -url "your site url"

Step 5: Restart IIS, to do this run the iisreset command in a command window.

Step 6: As a final step we need to restart the SharePoint 2010 Timer service (since it is what sends the alerts). To do this, run the services.msc command in the command window; that will open the Services Window where the "SharePoint 2010 Timer Service" is located and restart it.

Now the custom alert handler configuration is completed.

References

MSDN - IAlertNotifyHandler interface
MSDN - IAlertNotifyHandler.OnNotification method

Summary

In this article we explored how to create and configure a custom email alert handler for document libraries. To test the notification handler you need to turn on the alerts in a document library as shown in the image below.



Note: To debug the notification handler, you need to attach the debugger to the OWSTIMER process