Working with SharePoint Email Alerts

Author by Mark Rentmeester

Overview

It's a rare request to change the way the emails look when an alert is sent out from SharePoint (such as when a document get's changed in a library), but when you have to customize the alerts, it can be frustrating and time-consuming if you don't know how it all works under the covers. In this post, I'm going to boil down SharePoint Email Alerts to how they work to it's most important parts, and what you need to know to get them customized. I'll point out some "gotchas" that I found are not well-documented (or, at all).

How They Work

SharePoint 2010's email alerts seem simple enough on the surface, but deep down they rely on a structure of files, jobs/timers, and events. Let's go over some of the main components you will need to know about:

The Timer

Yes, there's one timer that takes care of all the alerts. Now, I know what you may be thinking: "Isn't there options to choose between immediate alerts, and daily/weekly (digest) alerts (when setting up a specific alert on a list)? And, isn't there a job called "job-immediate-alerts"? I would expect that the immediate job would take care of the immediate alerts, and another to take care of the daily/weekly (digest) alerts. Isn't that what job-daily-alerts does?" Well, this is the first "gotcha". First, the "job-daily-alerts" is actually deprecated, it doesn't do a thing. And so, the reality is that there's only one timer job, and it's called "job-immediate-alerts" and it does in fact take care of all the alerts; whether they're immediate or digest alerts. Out of the box, this timer runs every 5 minutes and checks to see if any alerts need to be sent out. So if it detects an alert that's marked "immediate," it send it. If it finds daily or weekly alerts, and the current date/time is past the alerts scheduled time, it sends those. Otherwise, the alerts are skipped and it goes back to sleep for another 5 minutes. You can change the timer's interval for how often it checks for alerts like this: stsadm -o setproperty -pn job-immediate-alerts -url -pv "every 3 minutes"

The Template

Before an email alert is sent out, it gets formatted based on an "AlertTemplate." There are 16 different alert templates that SharePoint can choose from and it bases its choice off of what type resource (list) is doing the alerting. For example, if you have an alert that's being triggered from a Document Library, SharePoint will use the "SPAlertTemplateType.DocumentLibrary" alert template. If just a generic list that's doing the triggering, the email will be formatted using the "SPAlertTemplateType.GenericList" alert template. Here's a list of all 16:
  • SPAlertTemplateType.GenericList
  • SPAlertTemplateType.DocumentLibrary
  • SPAlertTemplateType.WebPageLibrary
  • SPAlertTemplateType.Survey
  • SPAlertTemplateType.Links
  • SPAlertTemplateType.Announcements
  • SPAlertTemplateType.Contacts
  • SPAlertTemplateType.Events
  • SPAlertTemplateType.Tasks
  • SPAlertTemplateType.DiscussionBoard
  • SPAlertTemplateType.PictureLibrary
  • SPAlertTemplateType.XMLForm
  • SPAlertTemplateType.DataConnectionLibrary
  • SPAlertTemplateType.AssignedToNotification
  • SPAlertTemplateType.CallTrack
  • SPAlertTemplateType.Circulation
Each of these templates is XML based has a Format, Properties and Filters section. Within each of these sections are further sections that can be customized. (Customizing each particular nuance of alert template is out of scope of this post, check out my reference links at the end of the article for more information.) All of these templates are located here: C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATEXMLalerttemplates.xml note: Don't edit this file! Keep reading to find out how to customize your alert templates.

Customizing the Template

The Alert

The Flow of Events

Resources

A lot of research went into this post. I couldn't have done it without reading through some blogs; I think they deserve some credit: http://www.rightpoint.com/community/blogs/viewpoint/archive/2010/08/26/the-truth-about-how-daily-sharepoint-alerts-actually-work.aspx http://blogs.msdn.com/b/sharepointdeveloperdocs/archive/2007/12/07/customizing-alert-notifications-and-alert-templates-in-windows-sharepoint-services-3-0.aspx This article was originally written by Jordan Laik. It is moderated currently by Mark Rentmeester.
Author

Mark Rentmeester

Director of Application Development Services