Introduction
SharePoint facilitate users to opt alerts through email/SMS to get notified when changes occur in list/library such as item added, modified or deleted. These alerts are being sent on 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 alert handler and modify the alert template using a custom class.
Implementation
To create an alert handler we need to create a global assembly which contains a class that implements IAlertNotifyHandler interface in Microsoft.SharePoint assembly. The IAlertNotifyHandler interface contains only one method namely OnNotification through which we can intercept the e-mail alert and modify it.
Steps Involved are:
- 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 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 Empty SharePoint Project template and name it as “SampleAlertHandler” and click OK
Step 2: In the next window (SharePoint Customization Wizard) give your website Url and select Deploy as a farm solution option and click Finish button.
Step 3: Add a new class file to the SampleAlertHandler project with the name “CustomAlertHandler”. Now open the “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 above code we are modifying the alert template inside “OnNotification” method, which is being called prior to send the alert. The SPAlertHandlerParams (ahp) contains all the information about the alert. The ahp.headers includes email properties such as from, to, Subject etc. 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 subject. To construct the email body we are using ahp.eventData[0].eventType (SPEventType) property which indicates the type of alert event occurred. Finally we are sending email using SendEmail method of “SPUtility” class.
Step 4: Now our alert handler assembly is ready to deploy. Go to Build menu and click Deploy Solution. If successfully deployed verify the presence of our SampleAlertHandler assembly in GAC (C:\Windows\assembly).
Note: Take note of the Version and Public Key Token since we require these while creating alert template.
Create an Alert Template
Alert templates are XML files which defines content and appearance of both e-mail (alerttemplates.xml) and SMS (alerttemplates_sms.xml) alerts. Alert templates are located in “C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\XML” folder.
In this example we only deal with e-mail alert template (alerttemplates.xml). If you open the “alerttemplates.xml” you can see that there are 16(v.2010) different AlertTemplate elements defined in it for different types of list. 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 14 hive “TEMPLATE\XML” folder and make a copy of alerttemplates.xml and name it as “custom_alerttemplates.xml”.
Note: It is recommended to keep the original templates intact because any future SharePoint update will overwrite your changes.
Step 2: Open the “custom_alerttemplates.xml” in Visual Studio or any other XML editor and locate
AlertTemplate element which is defined for
DocumentLibrary template type (since we are using 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: PublicKeyToken must be same as earlier we noted in the GAC
Step 4: Now we can change the default template of our website, open a command window in 14 hive “TEMPLATE\XML” folder and run the following command.
sadm -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 iisreset command in a command window.
Step 6: As a final step we need to restart SharePoint 2010 Timer service (as it performs the tasks such as sending alerts). To do this run services.msc command in the command window which will open the Services Window where locate the “SharePoint 2010 Timer Service” and restart.
Now the custom alert handler configuration is completed.
References
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.
Note: To debug notification handler, you need to attach the debugger to the OWSTIMER process
