Custom Alerts

You can modify the SharePoint standard alerts by modifying an existing alert definition in the alerttemplates.xml. The following steps are useful:

  1. Create your copy template file in  \templates\xml.
  2. Register the new alerttemplates file using STSADM.
  3. Customize the alert template.
  4. Add the SPAlert objects in your application.

Step 1. Create your copy template file in  \templates\xml.
It is a good idea to leave the alerttemplates.xml untouched. To implement your own template simply take a copy of the file and remove all but one alert template. Remember to rename the alert template.

Step 2. Register the new alerttemplates file using STSADM.
Before you can use the new template you need to register the newly created template file with the following command:

STSADM -o updatealerttemplates -url [SITECOLLECTIONURL] -filename "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\XML\alerttemplates_custom.xml"

Step 3. Customize the alert template.
Refer to the following articles for an overview of the alert template.

These articles are not very specific. Therefore I will dive into the details here.

Basically there are three alert types in SharePoint: Immediate, Daily and Weekly. The alert template has only two elements: Immediate and Digest. Use the Digest section for both daily and weekly alert. You can use the following to implement daily or weekly functionality:

<Switch>
    <Expr>
        <GetVar Name="AlertFrequency"/>
    </Expr>
    <Case Value="1">
        <!– Daily –>
    </Case>
    <Case Value="2">
        <!– Weekly –>
    </Case>
</Switch>

In general, the fields or rowFields section are the core of the template. All content type fields that you did not explicitly exclude (ImmediateNotificationExcludedFields or DigestNotificationExcludedFields) will have the mark-up specified here applied. Think of it as a foreach loop that iterates over all content type fields. If you want to make the rendering dependent on the field name you can use the following xml:

            <!– Title –>
            <IfEqual>
                <Expr1>
                    <GetVar Name="DisplayName#{Field}"/>
                </Expr1>
                <Expr2>
                    <![CDATA[Title]]>
                </Expr2>
                <Then>
                    <!– Do something useful here. –>
                </Then>
            </IfEqual>

The above example renders only for the ‘Title’ field. I use this method to render a link to the created page for the title and normal text for the other fields.

Step 4. Add the SPAlert objects in your application.
To add an alert programmically you can use the following code:

guid = channelWeb.Alerts.Add(list, SPEventType.Modify | SPEventType.Add, SPAlertFrequency.Immediate);
SPAlertTemplate alertTemplate = new SPAlertTemplate();
alertTemplate.Name = SP_ALERT_TEMPLATE_NAME;
channelWeb.Alerts[guid].AlertTemplate = alertTemplate;
channelWeb.Alerts[guid].Title = "Title";
channelWeb.Alerts[guid].EventTypeBitmask = 3;
channelWeb.Alerts[guid].Filter = "… some CAML query …";
channelWeb.Alerts[guid].Update();

I figured that it is quite important to do exatly as the example shows. You do not have to update the SPWeb or SPList object. Set both the EventType and EventTypeBitmask. If you are not sure of the correct value for the EventTypeBitmask create some standard SharePoint alerts and check the values with SharePoint Manager.

If you want to read back the alerts that were created use the SPWeb.Alerts property. You will have to run your code with ElevatedPriviliges to avoid an UnauthorizedException when the AlertCollection has alerts from ohter users as well. Use the SPAlert.User.Id to filter the alerts for the current user.

If you want to delete alerts from SPWeb.Alerts collection you also need to use ElevetatedPriviliges and set SPWeb.AllowUnsafeUpdates to true.

Setting the SPAlert.Filter property to a valid CAML query that was produced with U2U CAML Builder resulted consequently in this error:

SPAlert.Query = "<Query><Where><Eq>…</Eq></Where></Query>";

Message:
Exception: Microsoft.SharePoint.SPException: Cannot complete this action.

Please try again. —> System.Runtime.InteropServices.COMException (0x80004005): Cannot complete this action.

This means in SharePoint language that you must not use the <Where> element in filter CAML queries. The following query works as expected:

SPAlert.Query = "<Query><Eq>…</Eq></Query>";

It is important to set the SPAlert.EventTypeBitmask according to the SPAlert.EventType.

Leave a Reply

Your email address will not be published. Required fields are marked *