Customizing Alert Notifications and Alert Templates in Windows SharePoint Services 3.0

[アーティクル]
12/07/2007

Hello. My name is Albert Meerscheidt and I’m one of the Programming Writers on the Windows SharePoint Services SDK team.

In the coming months I will be posting about the content that’s on the publishing horizon. The first topic that I'd like to discuss is how to customize alert notifications and alert templates in Windows SharePoint Services 3.0. The following is a somewhat abridged version of what you will see in the upcoming SDK update.

Overview

Alerts are an e-mail subscription notification service in Windows SharePoint Services 3.0. Users can create alerts to be notified of changes to list items (item level alert), documents, lists (list level alert), or document libraries. Alerts in Windows SharePoint Services 3.0 are quite flexible; when you create an alert you have options such as when to be notified and what kind of changes will trigger the alert. Alerts can be managed by users and administrators and customized by developers.

After an alert has been created, changes that fit the criteria specified in the alert are recorded in an event log. Alerts are generated by a timer job that reads the event log, formats the alert email using an alert template, and then sends that email out to the user.

Alert templates are stored in Alerttemplates.xml. Alerttemplates.xml defines the format, contents, and properties used to create alert messages from each list type in Windows SharePoint Services 3.0 . Developers can customize alerts by modifying a copy of Alerttemplates.xml and then loading the customized alert templates using the stsadm -o updatealerttemplates command.

Note Do not modify Alerttemplates.xml itself. Doing so may result in loss of functionality when upgrading or installing service packs.

The <filters> element in each template allows you to create custom triggers for events by using Collaborative Application Markup Language (CAML) queries.

The default timer interval can be changed to adjust the latency of 'immediate' alerts.

Default Timer Interval

Alert emails can be sent immediately or in a daily or weekly summary. Immediate alerts are not actually immediate; they are sent out after a delay determined by the timer interval. This is done for performance reasons.

The default timer interval is 5 minutes. Thus, if this interval has not been changed you could notice a delay of up to 5 minutes (the default timer interval) before an alert message is generated. Changes are recorded as they occur in an event log (discussed later in this article) and then alert messages are rendered from that log when the next timer job runs.

The default timer interval can be determined using the stsadm command.

stsadm -o getproperty -pn job-immediate-alerts -url<url> command.

The timer interval property can be set using stsadm. In this example I set the interval to 3 minutes.

stsadm -o setproperty -pn job-immediate-alerts -url<url> -pv "every 3 minutes"

For more information about STSADM, see https://technet2.microsoft.com/Office/en-us/library/188f006d-aa66-4784-a65b-a31822aa13f71033.mspx?mfr=true.

Alert templates

Alert templates are stored in the configuration database and are available at the web application level. Alert templates are defined in Alerttemplates.xml.

Windows SharePoint Services 3.0 ships with the following templates:

Table 1. Predefined alert templates

Alert Template Name	Description
SPAlertTemplateType.GenericList	The first alert template in Alerttemplates.xml. GenericList is used unless there is a match to one of other event types.
SPAlertTemplateType.DocumentLibrary	Notification of changes in document libraries
SPAlertTemplateType.Survey	Notification of changes in surveys
SPAlertTemplateType.Links	Notification of changes in links
SPAlertTemplateType.Announcements	Notification of changes in announcements
SPAlertTemplateType.Contacts	Notification of changes in contacts
SPAlertTemplateType.Events	Notification of changes in events
SPAlertTemplateType.Tasks	Notification of changes in tasks
SPAlertTemplateType.DiscussionBoard	Notification of changes in discussion boards
SPAlertTemplateType.PictureLibrary	Notification of changes in picture libraries
SPAlertTemplateType.XMLForm	Notification of changes in XML form
SPAlertTemplateType.DataConnectionLibrary	Notification of changes in data connection libraries
SPAlertTemplateType.AssignedtoNotification	Assigned to task / issue list notifications

Alerttemplates.xml is located at: Local_Drive\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Template\XML directory.

Note Do not modify Alerttemplates.xml itself. Make changes to a working copy.

Alert Template Format

Alert templates have the following format:

</AlertTemplate>

</Format>

</FilterDefinition>

</Filters>

</AlertTemplate>

</AlertTemplates>

Table 2. Alert Template Attributes

Attribute	Description
Name	The name of the template. Searching on the template names provides an easy way to locate a particular template.
Type	The type attribute can be set to List, Item, or Custom.
Default	Default="True" sets the default alert template.
Filters	If IsVisible = "True", then the filter fields are displayed when creating the alert.
Filter Definitions	Define a filter (query).
Format	Formatting of the email is defined in the <Format> element.
Fields	Specify which fields to render in the alert email.

Filters and Filter Definitions Elements

Filters enable you to create new triggers for an event such as 'the priority of a task has changed'. To modify existing filters or create additional filters modify the <FilterDefinition> element of the appropriate template. Define the query element using inside the filter using Collaborative Application Markup Language (CAML). This query will create an alert event if the event date, end date, or location changes.

<FriendlyName>$Resources:Alerts_4_filter;</FriendlyName>

<ShortName>$Resources:Alerts_4_filter_shortname;</ShortName>

<Query>

<Or>

</Neq>

<Neq>

</Neq>

</Or>

<Neq>

</Neq>

</Or>

</Query>

</FilterDefinition>

Resource variables listed in AlertTemplates.xml, such as $Resources:Alerts_anything_filter_shortname, can be found in core.resx; located in the Local_Drive\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Resources directory.

Note The Query element in the Alerts schema contains no Where element.

For more information about CAML query schema, see https://msdn2.microsoft.com/en-us/library/ms467521.aspx.

Format Element

Use the format element of an alert template to modify the look of the alert email. You can also customize the formatting of the alert email by using embedded styles.

<Digest> - digest format

</Subject>

</Header>

</HeaderFieldsHeader>

</HeaderFields>

</HeaderFieldsFooter>

<RowHeader> - each row’s header (row refers to each item level change in the digest notification)

</RowHeader>

<RowFields> - each row’s fields

</RowFields>

<RowFooter> - each row’s footer

</RowFooter>

</Footer>

</Digest>

<Immediate> - immediate notification format

<Subject> - email subject

</Subject>

</Header>

<Fields> - the html for the fields. CAML will go over all the fields and render this part of the template. The field itself should be referenced using <GetVar Name=”OldValue#{Field}” /> or <GetVar Name=”NewValue#{Field}” />

</Fields>

</Footer>

</Immediate>

</Format>

Fields Element

Specify the fields to be rendered in the email.

For example you can specify <GetVar Name="NewValue#{Field}"> inside the <Fields> section. More examples can be seen in AlertTemplates.xml.

To exclude some fields from being rendered in the email, you should include them in the <DigestNotificationExcludedFields> and <ImmediateNotificationExcludedFields> section. DigestNotificationExcludedFields and ImmediateNotificationExcludedFields give you the flexibilty to render different fields for immediate alerts and summary (digest) alerts.

In addition to these, CAML is supported. For example you can specify <GetVar Name="NewValue#{Field}"> inside the <Fields> section. More examples can be seen in AlertTemplates.xml.

To exclude some fields from being rendered in the email, you should include them in the <DigestNotificationExcludedFields> and <ImmediateNotificationExcludedFields> section.

Properties Element

The properties element allows you to include or exclude fields from the list that would be shown in the email notification. The example below demonstrates how to exclude fields for both the immediate and summary (digest) alerts.

<ImmediateNotificationExcludedFields>ID;Author;Editor;Modified_x0020_By;Created_x0020_By;_UIVersionString;ContentType;TaskGroup;IsCurrent;Attachments;NumComments;</ImmediateNotificationExcludedFields>

<DigestNotificationExcludedFields>ID;Author;Editor;Modified_x0020_By;Created_x0020_By;_UIVersionString;ContentType;TaskGroup;IsCurrent;Attachments;NumComments;</DigestNotificationExcludedFields>

</Properties>

Customizing the Alert Email

Alert UI elements

In addition to the formatting styles defined in the <format> element, alert templates include formatting instructions for user interface elements, such as the Modify my alert settings, Mobile View, and View <list> buttons, which can be modified or removed.

Modify my alert settings button

The following code displays the Modify my alert settings button:

<HTML><![CDATA[">$Resources:Alerts_link_modify;</a></td>

View list URL button

The following code displays the List URL button:

<HTML><![CDATA[">$Resources:Alerts_link_view; ]]></HTML><GetVar Name="ListName" HTMLEncode="TRUE" />

Mobile View button

The following code displays the Mobile View button:

<HTML><![CDATA[

<HTML><![CDATA[">$Resources:Alerts_mobile_view;</a></td>]]></HTML>

</Default>

</Switch>

Steps to Modify Alerts

You can use any XML editing tool to edit the templates.

1. Create a working copy of AlertTemplates.xml.

Note Remember to always modify a copy of Alerttemplates.xml, not Alerttemplates.xml itself.

2. Edit the working copy that you just created.

3. Use the stsadm command to read the changed templates into the database.
STSADM -o updatealerttemplates -url <https://urlname> -filename <your working copy filename>.

4. Restart IIS.

Note It may be necessary to restart SharePoint Timer Services.

Creating your own alert template

If you want, you can create your own template, and then use the stsadm command to load that template. Pattern your template after one of the templates in Alerttemplates.xml.

A particular instance of a list can use a specific alert template by setting the SPList.AlertTemplate property with the desired template. Any new alert created for this list through the subnew.aspx or through the object model using SPAlerts.Add(SPList / SPItem, SPEventType, SPAletFrequency) will pick up the alert template defined for the list.

To assign a custom alert template to a specific list

1. Create a new custom template with a unique Name attribute in your working copy of AlertTemplates.xml (You can copy paste the entire section with Name SPAlertTemplateType.GenericList, change the name and modify the sections you want to). Modify the template as necessary. After restarting IIS, write object model code to set the list alert template

SPAlertTemplateCollection ats = new SPAlertTemplateCollection((SPWebService)(WebApplication.Parent)); //give appropriate values for WebApplication

list.AlertTemplate = ats[“name from above”];

list.Update();

Event Logs

Rendering of alert emails occurs some time after the change that generated the alert. Data in the EventCache and EventLog tables is used for rendering the alert since the changed item may no longer exist, or exist in the same form, at the time the email is sent.

The event log uses a SQL table called the EventCache to record SQL level events as they occur. Each row in the table corresponds to an event. The events can be read using the WSS object model. In general, the number of rows written to the table is the minimum necessary to capture the semantics of the event. The assumption is that the reader of the event knows how to use the event row to calculate all the implications of a given event. For example, when a folder is deleted, the folder delete event is the only event written to the change log. No events are written for the files and sub-folders that are contained in the folder. The reader of the folder delete event needs to understand that it implies the deletion of the entire contents of the folder.

By default, the change log retains 15 days worth of data. You can configure this using the “web application general settings” page. There is a timer job that runs daily to delete all expired change log entries.

Change Events

Change events are returned as objects in an SPChangeCollection. Each change object is a subclass of the SPChange object. Depending on the type of SPChange object, different properties are available. The change collection is created by calling SPSite.GetChanges(), SPWeb.GetChanges(), SPList.GetChanges(), or SPContentDatabase.GetChanges(). An SPChangeToken object is passed into GetChanges() to specify where in the log to begin reading. An SPChangeToken can be serialized to a string format by calling the ToString() method.

Use the SPList.CurrentChangeToken property to get the current change token for that list object. There is a similar property on the SPSite, SPWeb, and SPContentDatabase objects. In general, the SPChangeToken from one object cannot be used in the GetChanges() method of another object. The only exception is that the SPChangeToken from an SPContentDatabase can be used in any object contained in that content database. There is also an object called an SPChangeTokenCollection which can be used to store multiple change tokens together, that can then be serialized to one single string.

Change Log Event Types

The following is a description of the event types recorded in the change log.

Table 3. Event Types

Event Type	Description
Add	An object was added. For items, files and folders, the TimeLastModified in the log should be the same as the Created datetime of the object.
Modify	An object was modified. For items, files and folders, the TimeLastModified in the log should be the same as the modified date time of the object.
Delete	An object was deleted.
Rename	An object was renamed. This means that the file name portion of the URL was changed.
MoveInto/MoveAway	An object was renamed. This means that the path portion of the URL was changed. The leaf portion may or may not have been changed also.
Restore	An object was restored from the recycle bin or from a backup. This event signals to a sync client change log reader that it needs to re-sync the object and all its children.
Role Add	A role was added at the scope of the object.
Assignment Add	A role assignment was added at the scope of the object.
System Modify	An object was modified without its Modified date time or Modified By property changing. The TimeLastModified in the log should be the time that the update took place, not the Modified date time property.
Member Add	A member is added to a SharePoint group.
Member Delete	A member is deleted from a SharePoint group.
Role Delete	A role was deleted at the scope of the object.
Role Update	A role was updated at the scope of the object.
Assignment Delete	A role assignment was deleted at the scope of the object.
Navigation	The navigation nodes were updated at the scope of the object.

Object Types

The following is a list of the object types that may have changes recorded in the change log. Not all event types are possible on all object types.

Table 4. Object Types

Object Type	Description
Item	This object type applies to all objects that exist in a list: list items, files and folders
List	List object type
Web	Web object type
Site	Site object type
File	This object type applies to files that exist outside of a list and don’t have a corresponding item.
Folder	This object type applies to folders that exist outside of a list and don’t have a corresponding item.
Alert	Alert object type
User	User object type
Group	Group object type
ContentType	Content object type
Field	Field object type
SecurityPolicy	A security policy change has been made at the web application level that affects the entire content database. This event was added late in the development cycle, so it and the content database level restore event are logged as a site level event with a SITEID of “00000000-0000-0000-000000000000”

Conclusion

Alerts are quite flexible; when you create an alert you have options such as when to be notified and what kind of changes will trigger the alert. Alerts can be managed by users and administrators and customized by developers.

Alerts are generated by a timer job that reads the event log, formats the alert email using an alert template, and then sends that email out to the user.Developers can customize these alert emails by modifying alert templates. Alert templates are stored in Alerttemplates.xml. Alerttemplates.xml defines the format, contents, and properties used to create alert messages from each list type in wssversion3. The <filters> element in each template allows you to create custom triggers for events by using Collaborative Application Markup Language (CAML) queries. Developers can customize alerts by modifying a copy of Alerttemplates.xml and then loading the customized alert templates using the stsadm -o updatealerttemplates command.

In my next post I'll talk about how to use the IAlertNotifyHandler interface to customize alerts.

Comments

Anonymous
December 11, 2007
OT: Dateiverzeichnisse synchronisieren mit SyncToy Microsoft SyncToy 2.0 Beta Artikel zu den Dokument-Konvertern
Anonymous
December 14, 2007
In my post last week I talked about customizing alert notifications and alert templates . Sometimes you
Anonymous
January 06, 2008
Last month a customer asked me if they could modify SharePoint alert notifications? Of course you can
Anonymous
January 06, 2008
Last month a customer asked me if they could modify SharePoint alert notifications? Of course you can
Anonymous
January 13, 2008
Hi, Very helpfull post, My question is that whether we can modify the text of those emails those who fired when we attache the alert. Using Alerttemplates.xml we can modify only those mails which is fired after modification made in Doc library etc. May be I am wrong but need clearification on that. Thanks for help.
Anonymous
July 24, 2008
WssAlter http://blogs.msdn.com/sharepointdeveloperdocs/archive/2007/12/07/customizing-alert-notifi...
Anonymous
August 04, 2008
项目需要，研究了一下WSS的Alert定制。定制有两种方法: (方法1)修改模板文件默认模板是12
Anonymous
August 11, 2008
项目需要，研究了一下WSS的Alert定制。定制有两种方法: (方法1)修改模板文件默认模板是12
Anonymous
September 07, 2008
I've got a problem with GetVar and DateTime type. Please visit URL: http://forums.asp.net/t/1315852.aspx. Can you help me? Thanks!
Anonymous
September 11, 2008
Is there a way to specify the fromfield of alerts based on the site, list, document?
Anonymous
October 22, 2008
We have customized alerts on our server. The first problem is that the changes apply only for some users. Two different users may receive distinct content in their alert for the same event (like modifying a document). The second problem we have is that two different document libraries do not use the same email template to send alerts. It seems that the new Alerttemplates.xml we created is not applied evenly to different subwebs or for different users. Has someone already had this problem?
Anonymous
October 31, 2008
We found our bug. We programmed our own form to allow users to subscribe to multiple alerts in one post and to avoid the email sent to confirm the alerts. The problem was that we didn't change the «AlertTemplate Type» according to the list to which the user wanted to subscribe. So everything works fine now. By the way, it would be nice if there was a place to add text that applied to all alert templates. We had to modify every template to add the text « Please do not reply to this message ».
Anonymous
February 05, 2009
Hi all, I have a question, please answer it for me, thanks. When I create an Alert for a list, after click OK button I will receive an e-mail such us belowing example Subject: You have successfully created an alert for 'Test2' Body: Alert 'Test2' has successfully been added on 'CitusDB'. You will receive alerts in e-mail. The timing and criteria for the alerts depend on the settings entered when the alert was added. You can change this alert or any of your other alerts on the My Alerts on this Site page. My Question: "How to customize that above e-mail?" Thank for response.
Anonymous
February 05, 2009
Hi all, I have a question, please answer it for me, thanks. When I create an Alert for a list, after click OK button I will receive an e-mail such us belowing example ===================================== Subject: You have successfully created an alert for 'Test2' Body: Alert 'Test2' has successfully been added on 'CitusDB'. You will receive alerts in e-mail. The timing and criteria for the alerts depend on the settings entered when the alert was added. You can change this alert or any of your other alerts on the My Alerts on this Site page. ===================================== My Question: "How to customize that above e-mail?" Thank for response.
Anonymous
March 17, 2009
Nice posting. Quick question, where can we find the all available variables for GetVar used in the alert template? Which variable should we use for displaying the links of attachments in the email body? Thanks Bill
Anonymous
May 06, 2009
SharePoint :: Alert Me Template Customization
Anonymous
June 04, 2009
Bizonyára többen próbálkoztak már azzal, hogyan lehet módosítani
Anonymous
December 11, 2009
If I am trying to change the template for a list with multiple columns, what Field would I use for the generic list. Obviously each list has different fields.
Anonymous
January 13, 2010
Hi Albert Meerscheidt Thank you very much for u r sharing knowledge. Now i can resolve my client issue with the reference of you.
Anonymous
January 13, 2010
Pls one question. how to customize the message when the user create new a alert at list or library.
Anonymous
January 28, 2010
How do we stop a specific alert notification? I am using collect data from user function. The function send 3 alerts:

Task assigned
Task changed
Task changed I need only the first alert as the Task changed alerts (2 and 3) are confusing users. Please advise

Anonymous
August 09, 2010
How can I modify this alert "Confirm SharePoint Web site in use" that goes out every 60 days or so. www.ekhichdi.com/.../INCREASE-THE-SAVE-AS-TEMPLATE-SIZE-9.html
Anonymous
September 22, 2010
When I receive an alert on my XP system I get details about the item (fields, lists, etc). When I receive an alert on my Vista system I only receive header information - just tells me an item has been changed. Any ideas why???
Anonymous
November 21, 2010
When I receive an alert on my XP system I get details about the item (fields, lists, etc). When I receive an alert on my Vista system I only receive header information - just tells me an item has been changed. Any ideas why??? >>>Have run into this before; I am sure the problem related to the way MS exchange encoded the email. jh
Anonymous
December 05, 2010
Do you recommend purchasing SharePointBoost software to be able to modify the emails?
Anonymous
December 05, 2010
Do you recommend purchasing SharePointBoost software to be able to modify the emails?
Anonymous
December 07, 2010
I desperately need the alert notification email to include the revision comments (i.e. the comments the author provides--if they choose--to describe their changes to the doc), so that folks can determine if they need to be concerned about the changes. Are the revision comments simply a FIELD that could be added to the email alert, or would that have to be done with a real customization?
Anonymous
January 12, 2011
I created a calculated column that checks to see if a date and time column have a date listed or not. In the view I do not have that calculated column as being shown. I have a Alert setup against that view. In the e-mail I receive from that Alert shows the calculated field. Why?
Anonymous
May 03, 2011
Thanks! Below you find another solution to SharePoint 2010 templates. How To Implement A Generic Template Engine For SharePoint 2010 Using DotLiquid jbaurle.wordpress.com/.../how-to-implement-a-generic-template-engine-for-sharepoint-2010-using-dotliquid
Anonymous
June 12, 2011
Can you talk about the disk quota warning timer job and the logic behind its notification behavior?
Anonymous
June 19, 2011
Excellent article. Thanks. It also seems to apply to Sharepoint Foundation 2010
Anonymous
July 28, 2011
is it possible to modify templates when one is running hosted sharepoint?
Anonymous
September 09, 2011
Hello! Thank you for the great post. Question: using SharePoint 2010 Foundation, is it possible to customize a list email alert without the changes being applied to the entire intranet? Example: I need the email alert to show limited amount of characters not the entire post with the option to click a link and be redirected to the intranet to read the entire article? But I need this to be applied only for one specific list – not the entire site. Thank you, Katerina
Anonymous
October 24, 2011
Katerina - Did you find any solution?
Anonymous
April 04, 2012
Hello, thank you for this great Tutorial. It helped me alot in customizing the alert mails. But I'm still have a question: is it possible to customize also the first mail, when adding an alert for an user? In this mail, it says like who have created this alert and for which library this alert is and so on. I want to change this mail also, because the information on this is not very suitable. greetings
Anonymous
July 19, 2012
Marco and I have the same issue. is it possible to customize also the first mail, when adding an alert for an user? In this mail, it says like who have created this alert and for which library this alert is and so on. I built my own handler, custom alert XML, and updated the properties. Alerts works great. ALMOST: There is NO BINDING for the first email! Seriously? Seriously? Oh Yeah, there is nothing in any resx file either. I'm dead in the water.
Anonymous
April 01, 2013
The best way to save a lot of time: www.harepoint.com/.../Default.aspx
Anonymous
April 03, 2013
Hi, here is a special product to customize and brand templates: www.harepoint.com/.../Default.aspx
Anonymous
October 29, 2013
Very useful tutorial. My issue is how as administrator to override an alert e.g. where you only want to notify certain types of changes. Any ideas?
Anonymous
June 20, 2014
Hi, i want to know about the $Resources:Alerts_link_modify; Where it will take the URL and if i want to change the old url path for this means,how to change that?
Anonymous
July 14, 2014
In team room have any option to notify team members that any message waiting for me? Please anyone help me to find out the answer ??
Anonymous
November 10, 2015
Hola estamos necesitando enviar las alertas a un grupo de usuarios definidos (dentro de la seguridad), es posible?

次の方法で共有

Customizing Alert Notifications and Alert Templates in Windows SharePoint Services 3.0

Overview

Default Timer Interval

Alert templates

Alert Template Format

Filters and Filter Definitions Elements

Format Element

Fields Element

Properties Element

Customizing the Alert Email

Alert UI elements

Modify my alert settings button

View list URL button

Mobile View button

Steps to Modify Alerts

To assign a custom alert template to a specific list

Event Logs

Change Events

Change Log Event Types

Object Types

Conclusion

Comments

その他のリソース