Customizing Alert Notifications and Alert Templates in Windows SharePoint Services 3.0

  • Article

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:

<AlertTemplates>

 <AlertTemplate Type="List" Default="True" Name ="Default Template">

 </AlertTemplate>

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

  <EventTypes IsVisible="True"/>

  <Format>

  </Format>

  <Filters>

    <FilterDefinition>

    </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.

 

<FilterDefinition>

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

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

   <Query>

   <Or>

   <Or>

   <Neq><FieldRef name="EventDate/New"/>

   <FieldRef name="EventDate/Old"/>

   </Neq>

   <Neq>

  <FieldRef name="EndDate/New"/>

   <FieldRef name="EndDate/Old"/>

   </Neq>

   </Or>

   <Neq>

   <FieldRef name="Location/New"/>

   <FieldRef name="Location/Old"/>

  </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.

<Format>

<Digest> - digest format

    <Subject>

    </Subject>

    <Header>

    </Header>

    <HeaderFieldsHeader>

    </HeaderFieldsHeader>

    <HeaderFields>

    </HeaderFields>

    <HeaderFieldsFooter>

    </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>

    </Footer>

</Digest>

<Immediate> - immediate notification format

    <Subject> - email subject

    </Subject>

    <Header>

    </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>

  </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.

<Properties>

<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:

<GetVar Name="MySubsUrl" URLEncodeAsURL="TRUE"/>

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

        <td class="toolbarsep">|</td>]]></HTML>

View list URL button

The following code displays the List URL button:

<GetVar Name="ListUrl" URLEncodeAsURL="TRUE" />

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

Mobile View button

The following code displays the Mobile View button:

<Switch>

        <Expr><GetVar Name="MobileUrl"/></Expr>

          <Case Value = "NULL"/>

          <Default>

              <HTML><![CDATA[

        <td class="toolbarsep">|</td>

        <td class="toolbarbutton"><a href="]]></HTML><GetVar Name="MobileUrl" />

     <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&aacute;ra t&ouml;bben pr&oacute;b&aacute;lkoztak m&aacute;r azzal, hogyan lehet m&oacute;dos&iacute;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:

  1. Task assigned
  2. Task changed
  3. 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?