Export (0) Print
Expand All

Working with Search Alerts in SharePoint 2010

SharePoint 2010

Learn how to use search notification services, known as search alerts, in SharePoint Server 2010.

Windows SharePoint Services 3.0 alerts represent a significant improvement over the alert framework of the earlier version. In Windows SharePoint Services 2.0, alerts could be used to notify a user about additions, changes, and deletions to content within lists and libraries. In Windows SharePoint Services 3.0, Microsoft extended and improved the alert framework through new classes that enable the manipulation of alerts. This includes the ability to notify collections of users about changes to a search result set, and the ability for users to create alerts on behalf of other users.

Microsoft SharePoint Foundation 2010 and Microsoft SharePoint Server 2010 offer more improvements. The SharePoint Foundation Alert object model is the foundation for all alerts within SharePoint 2010 products and technologies. The Alert object model in SharePoint Foundation enables you to create the following alert types:

  • List-level or list item-level

  • Custom (search)

  • Customized report

  • Documents

  • Form templates

  • Site specific list information

  • Images

  • Webpages

  • Site collection documents

  • Site collection images

  • Style library components

  • Content and structure reports

  • Reusable content

  • Workflow tasks

These alert types are also supported by the SharePoint Server search Alert object model. The SharePoint Server search Alert object model encapsulates and extends the SharePoint Foundation model. Table 1 describes the search services and components used by search alerts.

Table 1. Search services and components used by SharePoint search alerts

Component

Description

Crawler

Indexes the content, changing the metadata in the property store when a file is changed, and adds the metadata when a new file is crawled.

Search service application proxy

After the user sends a query, the Search service application proxy takes the query and modifies it so that the query processor can handle it.

Query processor

Handles the query to obtain the results and sends the results back to the alert handler.

Security trimmer

Based on the user's ID and permissions, controls the files and sites that the user can view.

Custom security trimmer

Enables customers to add their own authentication system. Both the default security trimmer and custom security work with the data sent by the alert handler.

Timer job

Executes in a configured timeframe, for example, every n minutes, to extract the alert information and send it to the search alert handler.

Enabling the Search Alerts Feature in SharePoint Server 2010

An administrator must enable the search alerts feature within SharePoint Server 2010 through the Central Administration Search Service Application Administration webpage, as shown in Figure 1.

Figure 1. Search alerts enabled in Search Administration

Search alerts enabled in Search Administration

For more information, see Enable Search Alerts (SharePoint Server 2010).

After the search alerts feature is enabled, the administrator must configure the outgoing mail service, as shown in Figure 2.

Figure 2. Outgoing email settings in Central Administration

Outgoing email settings in Central Administration

The service account that you use must have special privileges. The privilege is the delegate ("Send-As") permission to the mailbox listed in the from line. If this attribute permission is not configured, the email submission will fail. For more information, see Configure Outgoing E-Mail (SharePoint Server 2010). The administrator must also ensure that the Timer Job service is running.

To enable users to subscribe to alerts that are sent by using Short Message Service (SMS), the administrator must configure a mobile account that will be used to send the SMS alerts. For more information, see Configure a Mobile Account (SharePoint Server 2010).

When a SharePoint user wants to be notified about new or changed content within the content source, he or she creates an alert.

The enterprise alert user experience has two possible views: a Search Center site or a custom, vertical search solution. The pages have transactional Web Parts that enable the user to define, execute, and refine the search criteria while viewing corresponding results.

The default search alert creation process starts when a user executes a search query in a search center, and then clicks the Alert Me icon. See Receive Alerts and RSS Feeds of Search Results for the steps a user must take to set up an alert to receive future notifications of changes for results of that search.

The search Alert object model integrates with the SharePoint Foundation alert framework by leveraging and extending the SharePoint Foundation model as shown in Figure 3.

Figure 3. SharePoint alert and search Alert object model diagram

SharePoint Alert and search Alert object model

This composition-based architecture allows the search alerts runtime to use the existing SharePoint Foundation components. To better understand how alerts work, you have to look at what takes place behind the scenes of the search alerts default user experience.

The search alerts process starts with the user subscribing to an alert for search results.

To subscribe to an alert for search results

  1. Execute a query in the search center or custom user experience view.

  2. Examine the returned results.

  3. Click Alert Me on the search results page.

  4. Subscribe for alert notification.

Table 2 shows the subscription information that the alert framework stores.

Table 2. Subscription information stored by SharePoint Foundation alert framework

Subscription Information

Description

Alert Title

The title of the alert provided by the user.

Send Alerts To

Contact information for the notification recipient. This is automatically populated at run time. Users can also add recipients to the list.

Delivery Method

Selected by the user, either email message or SMS.

Change Type

The changes to send notifications for, such as new items, updated items only, or all changes. Set by the user.

Frequency

When to send notifications: immediately, daily, or weekly. Set by the user.

Query

Automatically populated with the search query built from the search the user performed.

User

Automatically populated with the SPUserId of the user for which the alert is being created.

Alert Time

The time the alert was created, set automatically based on the system time of the server.

After the user clicks Save, the alert framework stores the subscription data in one of the following content database tables for the site:

  • ImmediateSubscriptions  Stores the metadata for subscriptions that require immediate execution.

  • SchedSubscriptions  Specifies the repository for alerts based on a daily, weekly, or other incremental time frequency.

The SharePoint Foundation and search alert framework architecture is modular in definition and function. The combined architecture has UI components that live within front-end web servers as search components within SharePoint sites, Search Center sites, or Alert Management webpages. Figure 4 shows the various components as a block diagram.

Figure 4. Search alert framework architecture

Search alert framework architecture

An administrator or developer must understand the work processes involved in the alert definition, subscription, and notification. The following steps describe the alert framework components and how they interact with each other and with the content sources:

  1. The protocol handler implements the protocol to access the content source and notifies the filters and word breakers about the type of file that is about to be crawled.

  2. Filters and word breakers send document properties, including the time discovered (FirstIndexed) and the last time modified and indexed (LastIndexed), to the property store database; send all word-broken terms to the Crawl database and the Search Administration database; and set up the inverted index in the query server.

  3. User searches for some content.

  4. The keywords are sent to query server to look up each word in the inverted index. Properties are sent to the property store database to search for documents that match those properties.

  5. Common content IDs returned from query server and property store database are joined. Access control lists (ACLs) from the property store database are matched with the security descriptor (SD) from the profile store that matches the user. Security trimming removes the documents that do not match the user's SD, so the user sees only documents he or she has access to.

  6. Those joined documents are returned to the Search Center and the search results are displayed to the user.

  7. The user can then create an alert based on the search that was just performed. Alert information is sent to the SchedSubscriptions table in the content database.

  8. The timer job process executes every n minutes (by default, every five minutes) to read alerts information from the SchedSubscriptions content database table to identify alerts that must be processed.

  9. The alert handler uses information from the alert to build the alert query, which is the same query entered by the user earlier.

  10. The alert query is sent to the query processor with the properties that the user specified when the alert was created (existing items that have changed within the last alert time or the query results that have changed within the last alert time, or both.) Steps 4 and 5 are repeated.

  11. Those joined and trimmed query results (that also satisfy the properties mentioned in step 10) are returned to the alert handler.

  12. The alert handler creates and sends an email showing any documents or sites that were returned. If the query processor does not return any results, then no email is created or sent.

The following is the procedure for processing the alerts:

  1. The timer job calls the SharePoint Foundation alert handler every five minutes.

  2. The SharePoint Foundation alert handler scans the SchedSubscriptions table to identify which alerts to process.

  3. The SharePoint Foundation alert handler calls the search alert handler with the alerts to process.

  4. The search alert handler creates a query object from the information and calls the Execute() method on the SharePoint Server search Query object model.

  5. The search alerts handler returns the results from the query to the SharePoint Foundation alert handler, which sends an alert with the results to the user.

These scheduled subscriptions will fire and execute the next time the SharePoint Foundation Timer service (owstime.exe) processes the default and custom timer jobs.

This Timer service executes at a predetermined time interval. Timer jobs are the SharePoint-specific way to perform a specific task on a scheduled basis.

The Timer service examines the two tables and executes individual search queries for immediate, daily, or weekly alerts based on the frequencies established by calculating time spans. The daily alerts will have a 24-hour day, date, and time span calculated and stored in the respective database table. A weekly alert will have a seven-day day, date, and time span calculated and stored as part of the individual alert record.

In Windows SharePoint Services 3.0, alerts were expanded to support notifying a group of recipients about changes to a list item in a list, to changes in the list itself, or to changes to search results. Windows SharePoint Services 3.0 enables support for users to create alerts for other users. The user with these privileges can customize the trigger for an alert, and customize the alert notification. This functionality is exposed in the SharePoint Foundation object model, enabling programmatic manipulation of alerts.

The SharePoint Foundation alert framework has multiple tables for storing information. The alert framework manipulates the follow key database tables:

  • EventCache

  • EventLog

  • ImmedSubscriptions

  • SchedSubscriptions

  • EventsSubsMatches

A main design consideration for alerts is that the rendering of the email happens long after the change has actually taken place. So, it is not assumed that the item or list or one of the other thirteen alert types still exists and is in the same form at the time the email is sent. As a result, only the data in the EventCache table and EventLog table is used for rendering.

The event log uses the EventCache table to record Microsoft SQL Server-level events as they occur. Each row in the table corresponds to a single event. The events can be read by using the SharePoint Foundation object model. In general, the number of rows written to the table is the minimum that are needed 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 the 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 subfolders that are contained in the folder. The reader of the folder delete event must understand that it implies the deletion of the entire contents of the folder.

By default, the change log retains 15 days of data. You can configure this value by using the individual settings page for web applications. There is a timer job that runs daily to delete all expired change log entries. With search alerts, the query is stored within the properties field of the SchedSubscriptions table. The alert handler constructs a query and calls the query processor to execute the query and return the results.

Tables 3describes the relevant columns in the EventCache table.

Table 3. Events information stored in EventCache table or EventLog table

Name

Description

Id

The event ID.

EventTime

The event time.

EventType

Whether the event is visible to alerts, and what event type it is: add, modify, delete, or restore.

ItemId, ListId, SiteId

The identifier for the list item or document (ItemId), the list (ListId), or site (SiteId) to which the alert applies to.

ItemName, URL

Item name (list or document item, or name of site or list) accompanied by list, document library, or site URL.

EventData

The binary large object (BLOB) containing all of the field changes with the old and new values for an item.

Acl

The ACL for the item at the time it is edited.

Table 4 describes the relevant columns in the ImmedSubscriptions table or SchedSubscriptions table.

Table 4. Alerts subscription information stored in ImmedSubscriptions table or SchedSubscriptions table

Name

Description

Id

The subscription ID.

ItemId, ListId, WebId, SiteId

The identifier for the item that the alert applies to.

AlertTitle

The name given to the alert.

ListUrl, WebUrl, SiteUrl

Contextual URLs.

Filter, BinaryFilter

The filter defined on the field changes.

Properties

A property bag containing query properties that are used to build and execute search alert queries.

AlertType

The type of alert—regular, system, always notify.

Userid

The alert owner.

In addition, the SchedSubscriptions table has NotifyTime and NotifyTimeUtc columns, which indicate the next day, date, or time to fire the alert. These two columns are used to trigger an individual alert. The values can be updated to the current day and the timer job can be set to be triggered manually from the Central Administration Timer Job Monitoring UI.

Table 5 describes the relevant columns in the EventsSubMatches table.

Table 5. Events information stored in EventsSubMatches table

Name

Description

EventId

Event ID in EventCache table.

Sub ID

Subscription ID of the matching subscription.

Lookupfieldpermissionresults

Permission check results on the lookup fields for this item change event so that it does not have to be performed again.

Recording Changes to a SharePoint Alert

Alerts and the change log share a common architecture for entering events into the EventCache table.

For alerts, whenever an item change occurs and if there is at least one subscription on the search query, event data (a BLOB, stored in the EventData column in EventCache table) is built for the event. The event is recorded in the EventCache table with an EventType that is visible to alerts (EventType & 0xFFF != 0).

The EventData column is filled with detailed information (old and new values for most of the fields, content type, lookup values, and some hidden values) regarding the change, and the ACL column is filled according to the permissions at the time of the change. Because these columns contain much data, they are filled only if the list has at least one active subscription. The EventType column determines if an entry in EventCache is visible only to alerts or to the change log, or is visible to both. This keeps the number of entries in EventCache to a minimum. This entry is made in the same SQL round trip as the item update round trip.

A timer job inappropriately named Job-immediate-alerts runs (because it processes both immediate and scheduled subscriptions) at intervals of every five minutes (the default). All events that occurred after the last run are picked up (in batches of 10,000 events), and both immediate and scheduled subscriptions are picked up.

Each event is compared with each subscription to find a match (same siteID, same listID and, if itemID is specified, same itemID). If there is a match, the subscription filter is run on the event data to find a match if there are any filters specified on the fields such as "tasks assigned to me filter". If there is a match, security trimming is done for the user who is the owner of the alert. For example, if the user did not have permissions to read the list items, he will not get the alert. If the match between event and subscription passes security trimming, what happens next depends on whether it matched to an immediate subscription or to a scheduled subscription.

If the event matched an immediate subscription, the event and subscription are added to an in-memory junction list consisting of subID-eventID, which is processed later to build the alert email or message and send it out. Otherwise, if the event matched a scheduled subscription, the event and subscription it matched is added to EventsSubMatches table to be picked up again when that subscription is actually due.

After all the events are processed, the matches between events and immediate subscriptions are built into alert messages and sent. The matches between events and scheduled subscriptions are added to the EventsSubMatches table. Then, the scheduled subscriptions that are due are picked up with event-subscription junction entries for each subscription that is due. All the events for each subscription are rolled up and sent as an alert.

Three Steps of SharePoint Alert Subscription Processing

The processing of changes to send out alerts occurs mainly in three steps:

  1. Perform filtering and security trimming.

  2. Process immediate subscriptions.

  3. Process scheduled subscriptions.

Filtering and Security Trimming for SharePoint Alerts

The proc_GetEventDataAndSubscriptionFilters procedure is first called to get the latest top 10,000 events that have not been processed yet, that are visible to alerts (EventType & 0x0FFF != 0), and that have at least one subscription with the same siteId and listId in the subscription tables. This is an event batch.

The proc_GetEventDataAndSubscriptionFilters procedure also selects all the subscriptions from both the Immedsubscriptions and Scheduledsubscriptions tables that have at least one event with the same SiteId and ListId. Both the event batch and the list of subscriptions are sorted by SiteId and ListId. The procedure also marks the ID and event time of the last event so that it can start from there the next time(EventBatch table). Finally, it moves all the events that were picked up in this batch to the EventLog table and sets the EventData and Acl columns of the events that were picked up to NULL in the EventCache table. This is done for performance reasons because the EventCache table is highly used. The entries in the EventLog table will be used in the processing of scheduled subscriptions.

For each subscription in the subscriptions list, all the matching events are found. Matching implies having the same site ID and list ID. Because the list of subscriptions and the list of events are sorted by site ID, list ID, the matching consists of just walking over the ordered lists.

When there is a match, further checking is performed to determine whether itemID is the same (if itemID is not NULL in the subscription, that is, it is an item-level alert). If it is, the filter as specified in the binaryfilter column (which is a binary form of filter column) is run on the event data. If the event passes the filter, security trimming is performed on the user of that alert.

Note Note

If it is a dynamic alert, the user to whom the alert will be sent will be picked up from the field specified by DynamicRecipient property in the alerts property bag. If the alert is assigned to a SharePoint group, the group is expanded for the individual users and security trimming is performed for each user.

After security trimming is performed, all the matches between events and scheduled subscription are entered in the EventsSubMatches table as junction entries by using the proc_InsertEventSubscriptionJunctionEntries procedure. Each junction entry consists of an eventid, a subscription ID and lookupfieldpermissionresults, which are the results of security trimming on lookup fields for the event.

Processing SharePoint Alerts That Are Scheduled for Immediate Execution

The proc_GetEventDataAndSubscriptionFilters procedure does not get all the columns in the subscriptions tables. As a result, now proc_GetMatchingSubscriptionsData is called in batches of 256 subscriptions for all subscriptions in the memory junction of event-subscription. This gets all the data for each subscription. Then, for each subscription, the alert email or message is built by using the template that is specified by the AlertTemplateName column. See the Alert Templates Provided in SharePoint Foundation 2010 section for more information about alert templates.

Processing Scheduled SharePoint Alert Subscriptions

Scheduled subscriptions can be either daily or weekly regular alerts or daily or weekly always-notify alerts. Always notify alerts are alerts that fire without any matching event.

Each of the following steps happen serially for each type of scheduled subscription. Processing of scheduled subscriptions starts by getting a list of site collections that have at least one daily or weekly alert.

Scheduled SharePoint Alert Subscription Process

  1. The proc_EnumSubscribedSites procedure is called to get a list of all site collections that have at least one daily regular alert in the schedsubscriptions table; actually, all site collections that have at least one daily regular alert and at least one event in the event log table, to eliminate sites that have a very low volume of events.

  2. The proc_MatchSchedSubscriptions procedure is called for each SiteId in the list of site collections. It gets the list of daily alerts for that site collection, all the events-subscriptions junction entries for that site collection, and all the events from the EventLog table. It also checks the NotifyTime and gets only those subscriptions that are due, meaning that NotifyTime is earlier than the current time.

  3. For each subscription, all the events are rolled up into one digest and the alert is sent out. The lookup permissions results are useful in building the alert because those lookup fields that the user is not authorized to see should not be rendered in the alert.

  4. The proc_DeleteEventLog procedure is called to delete all the entries in EventLog that are older than one week because they will not be used in any subscription.

The previous steps are performed for each type of scheduled subscription: daily or weekly regular alerts and daily or weekly always notify alerts. Most of the time, always notify alerts do not have to have an email built and sent. Next, the proc_DeleteSubscriptionJunctionEntries procedure is called to delete all the junction entries for each subscription that was processed. This is done in batches of 256 subscriptions so that the database server is not overloaded. The proc_UpdateSchedSubscriptionTimes procedure is then called to update all the subscriptions whose NotifyTimeUtc is earlier than the current time. It adds a day to all the daily subscriptions and a week to all the scheduled subscriptions.

SharePoint Foundation provides AlertTemplate.xml, which can be modified to create new notification templates for various alert types. AlertTemplate.xml enables the developer or administrator to apply different styles to each template. The template styling enables the alert runtime to use XSLT script to reformat the alert format to meet various visual layout requirements.

The XSLT script is combined with a cascading style sheet (CSS) to meet the business requirements. This extensibility point can be used to meet corporate or retails branding requirements. Again, this level of customization can be applied to each alert type described previously in this article.

The AlertsTemplate.xml file is found in the path %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\\TEMPLATE\XML. The following table lists the alert templates that are provided with SharePoint Foundation.

Table 6. Built-in SharePoint Foundation alert templates

Name

Description

SPAlertTemplateType.GenericList

The first alert template in Alerttemplate.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.

SharePoint Foundation 2010 alert template syntax

The following is the alert template syntax for the alert templates in SharePoint Foundation.

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

The alert template attributes are described in Table 7.

Table 7. SharePoint Foundation 2010 alert template attributes

Name

Description

Name

The name of the template. Searching on the template names provides an easy way to locate a particular template.

Type

The type of the template. 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

Defines a filter (query).

Format

Formatting of the email is defined in the Format element.

Fields

The fields to render in the alert email.

The alerts feature in SharePoint Foundation is combined with the search services and UI to create a search alert. The email message that is the alert is provided by the Search Alert Handler search component, which is a .NET Framework assembly deployed to the global assembly cache. This assembly implements a specific class, which implements both the required IAlertNotifyHandler interface and the IAlertUpdateHandler interface. The IAlertUpdateHandler interface provides synchronous methods for handling alert updates made through the UI.

The alert infrastructure also provides a timer job to alert the user if the search results for that query have changed. The timer job can be set up to alert the user whenever the new results are added to the results list, when any of the existing results have changed, or both. The timer job does not alert the user immediately; however, it can be set up to alert the user once per day or once per week. The user is sent an alert containing the search query results that are returned for the query that the user set up for the alert, the files that were modified, or the new content items that were added to the content source. Links are also supplied to the sites and content items.

Note Note

Search alerts are disabled if the underlying web application for a site is configured to use claims authentication. If this is the case, alerts will not be triggered.

SharePoint Alert Notification Handler Interface

The alert framework includes the default class implementation of the IAlertHandlerNotify interface with the mandatory OnNotification(SPAlertHandlerParams) method. The SharePoint Foundation alert handler implements a default version of this interface. It specifically implements the OnNotification method called by the SharePoint Foundation Timer service.

Loading AlertTemplate.xml Using the SharePoint Foundation Timer Service

The Timer service loads the search AlertTemplate.xml file. The Timer service performs a look operation to find the correct .NET assembly to call with the NotificationHandler element within the definition of each specific search alert type. The Timer service leverages a set of internal runtime class object methods to load the correct assembly.

Once the assembly has been loaded, the runtime objects call the alert handler with an object named SPAlertHandlerParams. The SPAlertHandlerParams object contains the individual alert information retrieved from the SchedSubscriptions table in the content database.

Synchronous Pre-Alert Processing and Asynchronous Post-Alert Processing

The alert handler sometimes implements the PreUpdate(SPAlert, SPWeb, Boolean, String) and PostUpdate(SPAlert, SPWeb, Boolean, String) methods. As the names indicate, the methods provide a synchronous access to alert Before event that occurs when the alert is created and an asynchronous opportunity to manipulate alert processing in the After event that occurs after and alert has been modified in the user interface. The PostUpdate method is called each time an alert is updated from the user interface within the Update() method implementation. This method updates the SchedSubscriptions table with changes made to the alert. The method has two overloads. The first overload, Update() provides the default update behavior and the second overload, Update(Boolean) optionally sends a confirmation email message. The method is also called after the Timer service triggers an alert, which can be used to modify the structure of the alert confirmation email message.

In cases where the default confirmation message format isn't appropriate, the Update method can be called with a false parameter, which updates the database but does not send the default confirmation. A developer can provide a custom implementation of the PostUpdate method to modify the HTML confirmation email message format and send your custom subscription confirmation email message.

This allows you to intercept the outgoing alert emails and modify the format. We can access the properties for the alert and with some XML parsing and code, we can extract all the information that we need to build up the email. Use this information to construct the HTML to display the email based on your requirements and send the email out by using the SendEmail() method.

The SharePoint Foundation and SharePoint Server search alerts user experience provides basic alert services and a corresponding user experience. When you have requirements that require an enriched alert user experiences, the three distinct options are as follows:

  • Use the default user experience with minimal modification, combined with the existing alerts infrastructure.

  • Edit the default user experience by modifying existing default pages or replacing the default pages with custom ASPX pages.

  • Design, build, and deliver a completely custom search alert user experience to replace the existing experience while using the existing SharePoint Foundation alert infrastructure.

For more information about how to work with search alerts in SharePoint 2010, see the following resources:

Show:
© 2015 Microsoft