Customizing Alert Notifications and Alert Templates in Windows SharePoint Services 3.0


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 http://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 http://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 <http://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 (42)

  1. OT: Dateiverzeichnisse synchronisieren mit SyncToy Microsoft SyncToy 2.0 Beta Artikel zu den Dokument-Konvertern

  2. In my post last week I talked about customizing alert notifications and alert templates . Sometimes you

  3. Last month a customer asked me if they could modify SharePoint alert notifications? Of course you can

  4. Last month a customer asked me if they could modify SharePoint alert notifications? Of course you can

  5. subodh_pathak@hotmail.com says:

    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.

  6. 晃晃悠悠 says:

    项目需要,研究了一下WSS的Alert定制。 定制有两种方法:

    (方法1)修改模板文件

    默认模板是12

  7. hdbb30 says:

    项目需要,研究了一下WSS的Alert定制。 定制有两种方法:

    (方法1)修改模板文件

    默认模板是12

  8. nguyenvanbay1975 says:

    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!

  9. madzack says:

    Is there a way to specify the fromfield of alerts based on the site, list, document?

  10. saintijMRI says:

    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?

  11. saintijMRI says:

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

  12. luunt says:

    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.

  13. luunt says:

    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.

  14. bbwymz says:

    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

  15. SharePoint :: Alert Me Template Customization

  16. Bizony&aacute;ra t&ouml;bben pr&oacute;b&aacute;lkoztak m&aacute;r azzal, hogyan lehet m&oacute;dos&iacute;tani

  17. traceygardner says:

    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.

  18. toehan says:

    Hi Albert Meerscheidt

    Thank you very much for u r sharing knowledge. Now i can resolve my client issue with the reference of you.

  19. toehan says:

    Pls one question.

    how to customize the message when the user create new a alert at list or library.

  20. kimalim says:

    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

  21. Mejaw says:

    How can I modify this alert "Confirm SharePoint Web site in use" that goes out every 60 days or so.

    http://www.ekhichdi.com/…/INCREASE-THE-SAVE-AS-TEMPLATE-SIZE-9.html

  22. Alerts in XP versus Vista says:

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

  23. JH says:

    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

  24. Liz Simm says:

    Do you recommend purchasing SharePointBoost software to be able to modify the emails?

  25. Liz Simms says:

    Do you recommend purchasing SharePointBoost software to be able to modify the emails?

  26. Mary says:

    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?

  27. Tim says:

    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?

  28. JB says:

    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

  29. PHillip says:

    Can you talk about the disk quota warning timer job and the logic behind its notification behavior?

  30. Excellent article. Thanks. It also seems to apply to Sharepoint Foundation 2010

  31. marlene says:

    is it possible to modify templates when one is running hosted sharepoint?  

  32. Katerina says:

    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

  33. Ram says:

    Katerina – Did you find any solution?

  34. Marco says:

    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

  35. Chris J says:

    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.

  36. gorlach says:

    The best way to save a lot of time: http://www.harepoint.com/…/Default.aspx

  37. Custom Alerts for SharePoint 2010 and 2013 says:

    Hi,

    here is a special product to customize and brand templates:

    http://www.harepoint.com/…/Default.aspx

  38. Barry says:

    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?

  39. Pradi says:

    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?

  40. debnath says:

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

  41. Monica Godoy says:

    Hola estamos necesitando enviar las alertas a un grupo de usuarios definidos (dentro de la seguridad), es posible?

Skip to main content