Which Trigger Type Should You Use?

Which Trigger Type Should You Use?

When configuring an alert, one of the most important considerations is the trigger type. The trigger type determines how the alert is triggered. The available options are shown in the screen shot below.

trigger types.png

While all trigger types are available when alerting on SharePoint Lists or Libraries, some are not available when alerting on the contents of the List Rollup. Refer to the table below for more information about each trigger type. The List Rollup column indicates whether the trigger is or is not available for List Rollups.

Type Description List Rollup?
A specific column in the list changes

Use this trigger type when alerting on a SharePoint List or Library when you want to watch the value of a specific column (or a few columns).

When an alert with this trigger is created, an event handler is added to the list and every change to items in the list are tracked in the Alert+ AlertchangeList list.

Icon-Tip See an example of how to create an alert using this trigger type here.

No
An item in the list is deleted

Use this trigger type when alerting on a SharePoint List or Library when you want to send an alert when an item is deleted.

When an alert with this trigger is created, an event handler is added to the list and every time an item is deleted, the action is tracked in the Alert+ AlertchangeList list.

No
An item in the list is created. Use this trigger type to send an alert when an item is added to a SharePoint List or Library or to the lists/libraries included in a Bamboo List Rollup. Yes
An item in the list is modified. Use this trigger type to send an alert when an existing item in a SharePoint List or Library or in any of the lists/libraries included in a Bamboo List Rollup is modified. Yes
An item in the list is created or modified

Rather than create a separate alerts of when items from the same source (SharePoint List/Library or Bamboo List Rollup) are created and modified, use this trigger type to create only one alert.

NOTE: Alerts with this trigger type can be configured with separate email messages for when items are created and when they are modified.

Yes
An item exists

Use this trigger to type to send reminder emails. This type of message isn’t triggered when data changes, but when an item exists under certain conditions. It is not currently possible to send these types of alerts from SharePoint out-of-the-box.

When this trigger type is selected, the number of Follow-up Wait Days must be entered. Because alerts with this type of trigger are often processed by the As Soon As Possible timer job, it is important to specify how long to wait between successive email messages. Enter the number of days to wait before alerting on the same item again.

NOTE: Fractional days are not supported for the Follow-up Wait Days value. Please enter a whole number.

followup wait days.jpg

Icon-Tip See an example of how to create an alert using this trigger type here.

Yes

What is an External Host Path

What is an External Host Path

options tab-external host path.pngConfigure an External Host Path on the Options page of the Mail Format tab.

You may consider configuring it if you have external SharePoint users who may access SharePoint using a different URL than internal users.

View Alert Status

View Alert Status

Overview of the Alert Plus Web Part

Alert Plus displays the list of configured alerts, including important information about the current status of each.

alert list status.png

Use this list to periodically check the status of the alerts.

Column What is it showing?
Alert Status This column shows you if the alert is enabled. If it is disabled, no alerts will be sent.
Last Run Date

This column shows you the date the timer job last processed this alert.

NOTE: This date isn’t necessarily the last time an email was sent. An email is not always sent every time an alert is processed. Sometimes no items match the alert criteria when an alert is processed and therefore no emails are sent.

Icon-Tip If you never see a value in the Last Run Status column even though the alert is enabled, the timer jobs aren’t running for some reason. Check to make sure they were installed. See The Last Run Date Column is Blank for more information.

Last Run Status

This column shows you the current status of the alert. It will report:

  • Running when the timer job is running.
  • Success when the timer job completes with no errors.
  • Failure or an Error Code when the timer job stops due to an error. Generally, the specific error will be listed here to help troubleshoot.

NOTE: Sometimes you may notice that an alert is reporting Running for an unusually long time. This may be an indication of an error with the timer job and no error was reported. This happens when the job times out – no error is reported, but the alert status is never updated to indicate that the job is stalled. As long as the status is running, the job will not run again. See My Alert Seems to be Stuck in a Running Status to address this issue.

Using Tokens in your Alert Plus Email Message

Using Tokens in your Alert Plus Email Message

One of the great features of the Alert Plus Web Part is that it allows you to specifically format the email message for each alert you create. This way the Email recipients know exactly why they are getting the message.

You are not limited to static text in the subject or message body. The use of special tokens allows you to include references to dynamic objects such as Alert List columns, the alert item, or the site where the Alert List resides. As part of that formatting, you can use special tokens in the subject or the body of the HTML-based template. These special tokens are replaced with Alert List column values and other constructs when the message is created and sent.

Available Tokens in Alert Plus are described in the table below.

Token Description Use in a Hyperlink tag?
{[Column Display Name]}

Add the value of any Alert List column name to the Email message. For example, the token {Due Date} will insert the value of the item’s Due Date column into the subject or message (wherever you have placed the token).

Icon-WarningIMPORTANT: These tokens are case-sensitive! If the column name is Title and you use the token {title}, no values will appear in the email message.

Icon-WarningIMPORTANT: In Alert Plus v4.x and higher, if you are alerting on a view of a list, each token must be included in the view. If its not in the view, it’s value wil not appear in the Email message.

Yes
{[Column Display Name]/Old}

Add the previous value of any Alert List column name to have the old item value for that column inserted. For example: The token {Title/Old} will insert the value of the Title column BEFORE the change.

Icon-WarningIMPORTANT: These tokens are available only if the alert Trigger Type is A specific column in the list changes.

No
{[Comment Column Display Name]/New}

This applies only to multiline text fields that allow appended data. The /New switch will show only the most recently appended content.

Icon-WarningIMPORTANT: These tokens are available only if the alert Trigger Type is A specific column in the list changes.

NOTE: This feature is only available in Alert Plus version 4.0 and later.

No
{ItemURL} Inserts a link to the item that generated the alert. Yes
{SiteURL} Inserts a link to the site where the item that generated the alert resides. Yes
{itemlink}

Inserts a link to the item that generated the alert.

Icon-Tip The link construction method is dictated by the contents of the External Host Path and Custom Item Link fields on the Mail Format – Options tab.

No
{sitelink}

Inserts a link to the site containing the Alert List.

Icon-Tip The link construction method is dictated by the contents of the External Host Path and Custom Item Link fields on the Mail Format – Options tab.

No
{FolderName} Inserts the name of the folder where the alert item resides. Yes
{FolderPathName}

Inserts the names of nested folders where the alert item resides. In other words, if the item resides in a folder that is in another folder, the {FolderPathName} includes the names of all the folders in the path to reach the alert item.

Icon-Tip Use this token when building a Custom Item Link on the Mail Format – Options tab.

Yes
Images

Images can also be inserted into the e-mail Message Templates through the use of the HTML IMG element. Type in the image element and the source path to the image file to insert.

NOTE: The image file to be shown must exist at a location that can be resolved with a relative or fully-qualified URL path. On subsequent edits of the message template you will not see the IMG element, but rather the picture itself. If you desire to change the linked image, then you will first need to delete the existing picture.

No

Using the Alert Plus Subscriber Web Part

Using the Alert Plus Subscriber Web Part

Alert Plus Subscriber Web Part displays a list of Bamboo Alerts the current user is subscribed to, either directly or through membership in a SharePoint Group.

NOTE: This web part doesn’t show SharePoint alerts the user subscribed to, it shows alerts that are sent from the Bamboo Alert Plus Web Part. If you are interested in seeing or managing the SharePoint Alerts you or your team is subscribed to, see the Bamboo Alerts Administrator Web Part.

To use Alert Plus Subscriber Web Part, first add the web part to a page. see Configuring the Alert Plus Subscriber Web Part for details.

The Alert Plus Subscriber Web Part automatically displays the Bamboo Alerts for the current user. The main group heading, You are subscribed to these alerts, includes the alerts the logged in user is specifically identified as a recipient.

HW05_2010_SubscriberWP.jpg

Alert Subscriber for Julie - cropped.pngSome users may see a grouped view, as shown here. The group called You may be subscribed to these alerts appears if alerts are configured for items like Tasks where the alert is sent to the task assignee. In other words, the recipient is not specifically defined.

By default, Alert Plus Subscriber Web Part displays alerts in groups of 10. You can change the number of items displayed per page by making a selection in the Page size drop-down list at the bottom of the web part. Scroll between pages using the page navigation controls in the lower left corner.

NOTE: The Page size control is not available when using the web part in SharePoint 2013 environments.

Use the ‘An Item Exists’ Trigger Type

Use the ‘An Item Exists’ Trigger Type

The following outlines how to quickly configure a reminder alert. This alert uses the trigger type An item exists and a Bamboo List Rollup Schema as the Data Source.

Go to the page in your Portal, where the Alert Plus Web Part exists. If it hasn’t been added to a page yet, see How to add a web part to a SharePoint wiki page.

Icon-Tip It is not necessary to add an Alert Plus Web Part to a page in each site. Because you specify the URL for the site where the alert items reside, you can consolidate your alerts in one web part on a single page in your site collection.

Step Action
1. click new item in alert plus.pngFrom the Alert Plus toolbar, click New Item.
2. alert title.pngGive the new alert a title. You won’t be able to save the alert without a title.
3.

Identify the site where the items that will trigger an alert reside. First choose whether they are in a SharePoint List or Library or a Bamboo List Rollup. For this example, we will choose Bamboo List Rollup Schema *

Next, enter the URL for the site where the List Rollup Schema was defined. After entering the URL, click the Load button to load the available schemas into the What List contains the items to alert on? box. For this example, we will choose the schema called All Tasks in Site Collection.

select lr schema as data source.jpg

Icon-Tip When possible, use relative URLs. For example, if the List Rollup Schema was defined on the current site, enter ./ in the Enter Bamboo List Rollup Schema Web Part Site URL box.

4. Choose a What triggers the alert? option. For an alert that is sent as a reminder what a Task is overdue, we choose An item exists.

lr - what triggers the alert.jpg

For the Follow-up Wait Days, enter the number of days to wait before sending another email about the same overdue item. In other words, this type of alert has an automatic escalation. Reminder emails will continue to be sent as long as the item continues to meet the alert criteria.
5.

Choose How often are e-mails sent? For this example, choose As Soon As Possible so the email recipient receives the message as soon as we realize the task is overdue. Since the As Soon As Possible emails are processed every two minutes, this means the reminder emails will be sent shortly after midnight.

Icon-Tip Processing emails shortly after midnight is a good time to process reminder emails since it is typically not a busy time for your SharePoint server(s).

For information about the other options, including Combining multiple alerts into summary notification, see How often should E-mails be Sent.

6. What column values should generate an alert? For this example, we will use the CAML Criteria Builder. Select the Some Items (Advanced) option and enter the criteria as shown in the screen below. The specific date chosen as the Value for Due Date is not important since we will be changing it to use the current date. Click Copy Criteria to CAML Query Field when ready. The CAML Query will appear in the CAML Query box.

LR CAML builder.jpg


LR CAML edit1.jpgHighlight the date value entered, as shown here:

LR CAML edit2.jpgEnter <Today /> where the date value was, as shown here:

This results in a query that will automatically find all overdue tasks.

7.

Click the Recipient(s) tab and choose the recipient of the email alert. For this example, we will send the reminder emails to the Task assignee by selecting the Lookup an E-mail Address in the Alert List option. The Assigned To column is in the Tasks list, but it includes the person’s name, not an email address. Select the in SharePoint User Profiles to tell Alert Plus where to find the email address associated with the person.

lr recipient.jpg

See Overview of Alert Plus Recipient Tab for more information.

8. Click the Mail Format tab and compose your message. To include columns values from or a link to the alert item, use tokens. For our example, we will compose a message like this:

lr mail format.jpg


To see how the hyperlink to the task was composed, see the HTML view below:

lr mail format html.jpg

For more information about using tokens in mail formats, see Using Tokens in your Alert Plus Email Message. The email below is how this message will look. Notice that a blank due date in SharePoint will appear blank in the email message also.

sample email.jpg
9. Click the Save and Close button on the toolbar to save the new alert.

*Bamboo’s List Rollup web part is sold separately.

Setting up a Tasks List with an escalation of reminder alerts to the Task assignee

Setting up a Tasks List with an escalation of reminder alerts to the Task assignee

This use case is another extension of Alert on a Tasks List, and send alerts for every task to the assigned person. You want to set up an escalation of notification process for a Tasks List. Rather than sending the normal notification e-mails when items change, you want to be able to send overdue alerts when items are overdue, and send reminder e-mails 5 days before the due date. This actually requires two alerts to be defined: one for the overdue alerts and one for the reminder e-mails. Let’s refer to these two alerts in our discussion that follows as the Overdue Alert and Reminder Alert. The general alert parameters are defined as follows:

Alert List – What list contains the items to alert on? Tasks List
Event Type – What triggers the alert? An item exists.
E-mail Frequency – How often are e-mails sent? As Soon As Possible
Item Criteria – What items in the list generate an alert? Some Items (Advanced)
CAML Query (see below)
Who should the alert e-mails be sent to? Lookup an E-Mail Address in the Alert List
Where is the e-mail address to lookup stored? In SharePoint User Profiles
Which user lookup column in the Alert List should be used to find the recipient? Assigned To

Overdue Alert – CAML Query

After setting the general alert parameters you will need to define the CAML Query that is used to filter for overdue items. The criteria for our query will be to get all Task items where the Due Date field is greater than today and the Status of the Task item is not complete. Let’s start by using the Alert Plus Web Part Criteria Builder to provide us with the base of our CAML query that we will modify later.
hw05084.jpg

To enable the Criteria Builder, click on the Show Criteria Builder Tool checkbox below the CAML Query field in the “What items in the list generate an alert?” section of the UI. Use the UI controls to build the base query as show in Figure 16. You can pick any date value for the Due Date. We will need to change that value later manually to make comparisons to the constantly changing today’s date.

Click the “Copy Criteria to CAML Query Field” button.

Find the text shown in Figure 17 that has been copied to the CAML Query field. The text in bold is the text you need to edit manually. Change the date time value in bold to ““. Figure 18 shows how the CAML Query should look after editing.

hw05085.gif
Figure 17: Overdue CAML Query Before

hw05086.gif

Figure 18: Overdue CAML Query After

Configuration of the Overdue Alert Event tab is then complete.

Reminder Alert – CAML Query

After setting the general alert parameters you will need to define the CAML Query that is used to filter for items that are approaching their due date. Our use case specified the requirement to notify users when their Tasks were within 5 days of their due date. The criteria for our query will be to get all Task items where the Due Date field is less than or equal to 5 days from today and the Status of the Task item is not complete. Let’s start by using the Alert Plus Web Part Criteria Builder to provide us with the base of our CAML query that we will modify later.
hw05088.jpg

Figure 19: Criteria Builder Reminder

  • To enable the Criteria Builder, click on the Show Criteria Builder Tool check box below the CAML Query field in the “What items in the list generate an alert?” section of the UI.

Use the UI controls to build the base query as show in Figure 19. You can pick any date value for the Due Date value. We will later need to change that value manually to make comparisons to the constantly changing today’s date.

Click the “Copy Criteria to CAML Query Field” button.

Find the text shown in Figure 20 that has been copied to the CAML Query field. The text in bold is the text you will need to edit manually. Change the date time value in bold to ““. The special addValue token next to the “Today” text will direct the Alert Plus system to add a number of days (or subtract in the case of negative numbers) to today’s date. Please see Figure 21 for how the CAML Query should look after editing.

hw05089.gif
Figure 20: Reminder CAML Query Before

hw05090.gif
Figure 21: Reminder CAML Query After

Configuration of the Reminder Alert Event tab is then complete.

Set up an alert for a Bamboo List Rollup Data View or Schema

Set up an alert for a Bamboo List Rollup Data View or Schema

NOTE: To setup alerts on Data Views created by the Bamboo List Rollup Web Part, you must have the Alert Plus Web Part version 2.2.0 and the List Rollup Web Part version 2.0.1 or higher. To set up alerts on Schemas created with the List Rollup Schema Designer Web Part, you must have Alert Plus 3.0 or higher and List Rollup 5.0 or higher.

Please note that Alert Plus Web Part versions prior to version 2.2.0 are not compatible with List Rollup Web Part version 3.0.0 or higher. All products are sold separately unless purchased as part of a suite or toolkit.

Step Action
1. From the Alert Plus Web Part, click New Item.HW05_UC8.jpg
2. Enter a Title for your alert.
3. On the Event Tab, select the check box labeled Bamboo List Rollup – Classic Edition or Bamboo List Rollup Schema depending on the version of List Rollup you used to create the rollup. Enter a page URL for List Rollup – Classic Edition or a site URL for the List Rollup Schema option. (Hint: The easiest way to get this entry is to navigate to the Data View or Schema location in another browser tab or window and copy the URL.)
4. Click Add to load the data views or schemas into the Which List contains the items to alert on? drop-down box for selection as the alert list.
5. In the Which list contains the items to alert on? drop-down box, select the Data View you want.
6. In the What triggers the alert? drop-down box, select whether the alert is sent when an item is created, modified, or exists.
7. In the How often are e-mails sent? drop-down box, select the frequency with which you would like to send the alerts: as soon as possible, every hour, every day, or every week. WARNING: Please keep in mind the number of lists that are included in the Data View you have selected. If you have rolled up more than 15 lists with a large amount of data in each list, you should consider setting your alerts to be sent every hour, day or week, rather than “as soon as possible”. See Alert Plus Performance Considerations for more information on performance tuning.
8. In the What Items in the list generate an alert? drop-down box, select All Items or Some Items (Advanced). See Event Tab for more information on these options.
9. Set up the Recipient(s) and Mail Format tabs as described in the respective sections above (see Recipient(s) Tab and Mail Format Tab for more information).
10. On the Admin tab, you can specify how often you want the alert to be sent for the same alert item in the E-mail Follow-up Wait Days box. The default is set to 1 day. If you want the alerts to be sent regardless of when the last one was sent, set this option to 0. See Admin Options Tab for more information.
11. In the Use Custom Schedule option, set the start time, end time, frequency value and unit. It is recommended that for rolled up data views with more than 15 lists with a large amount of data in each list that you set the service to check for updates to this list every 5, 8 or 10 minutes or more as needed to enhance maintain reasonable performance. See Alert Plus Performance Considerations for more information on performance tuning.
12. Click Save and Close. Your alerts will start processing according to your start time in the custom schedule.

Configure the Alert Plus Event Tab

Configure the Alert Plus Event Tab

Create a new alert

3Tabs.gifAlert Plus has three tabs where parameters for an alert need to be configured.
We will discuss the Event Tab here. For information on the other tabs, click the links below.

B – Recipients Tab
C – Mail Format Tab

Event Tab

AlertPlusSteps.gifAlert Plus is very flexible and has a variety of ways you can set up alerts. Configure the Alert Plus Event Tab following the steps below.

Step Action Result
1. Give your Alert a title and set its status (e.g., Enable or Disable).

The information you type into the Title box is saved into the web part. The default status is Enable. If you switch to Disable, the alert will not be triggered, but all configurations will be saved.

Icon-Tip You won’t be able to save your alert without a title.

2. Decide where the items that trigger the alert reside. Choose a SharePoint List or Library or a Bamboo List Rollup. Your selection dictates the source of the data for your alert.
3. Enter the URL of the site where your list/library resides or where your List Rollup is defined. Click the “Load” button to load the available lists/libraries or List Rollups.

Icon-Tip Whenever possible, enter a relative URL rather than an absolute path to a site.

4.

Pick the list that stores the items that you want to alert on.

NOTE: If you pick a Calendar list, you will specify how you want to handle recurring events.

CalendarSelections.gif

5. Select the alert trigger type.
EventTriggers.gif
Your selection dictates how the alert will be processed. See Which Trigger Type Should You Use for more information about trigger types and some examples.
6. Decide how frequently an email will be sent.

EmailFrequency.gif

In addition to the frequency of the alerts, you also have the option to combine multiple alerts into a summary notification. See How often should E-mails be Sent and Combine Alerts into a Summary Alert for more information.
7.

Pick which items in the list can generate the alert. Depending on your choice, the interface may change.

  1. All items: This generates an alert on all items in the list based on the trigger type selected in Step 5 above. For example, if the trigger type is An item in the list is created, and All Items is selected here, an email will be generated for all new items when they are created.
  2. Items in a List View opens a drop down selection containing available views for the list selected. If you choose this option with the An item in the list is created trigger type, an email will be generated whenever an item is created and appears in the selected view.
    ListView.png

  3. Some Items (Advanced) opens the Crtieria Builder to allow you to build filter criteria that determines which items generate an alert. See CAML Criteria Builder for more information.

Configure the Alert Plus Mail Format Tab

Configure the Alert Plus Mail Format Tab

Create a new alert

AlertPlus.pngThis is the third tab on the Alert Plus window. This is where you set up the email template that will be used to construct your alert messages.

3Tabs.gifUse the links to see information about the other tabs.

Tab A – Event

Tab B – Recipients

Depending on the trigger type for your alert, the tabs displayed on the Mail Format tab will vary. For example, if you are sending a notification based on an item that is created, you will use the first tab to build your template. However, if you are configuring your notification based on a modification to an item, click the next tab “On Item Modification” and so forth. And it is possible that you are using a combination of options so you can set one message for creation and a different message for modifications. The choice is up to you.

MailFormat.gif

To include information from the item that triggered the alert, use tokens in the email template.

To see how information from multiple alerts can be combined into a summary alert, see Combine Alerts into a Summary Alert

Use the {itemlink} token to include hyperlink to the item that triggered the alert. If you are alerting on the files in a document library, you can also Include a link to the file that triggered the alert.

If your email supports HTML, you can add HTML tags to your message.

Configure the Alert Plus Recipient(s) Tab

Configure the Alert Plus Recipient(s) Tab

Create a new alert

AlertPlus.pngOn the Recipient tab, define how the system determines to whom the alert messages will be sent. With the variety of options available to you in Alert Plus, you might be wondering which is the better one to use? The simplest option is to set an alert to send to yourself. This choice is often used when setting up a new alert. Send the message to yourself as you work through the configuration for the first time so that you see the results and can modify anything as needed. When you are ready to establish your notifications, you can define the alert recipients several different ways.

3Tabs.gifUse the links to see information about the other tabs.

Tab A – Event

Tab C – Mail Format

Use the table below to learn more about each recipient choice:

Option Description
Lookup an email in another list (Advanced)

The Advanced Lookup feature can be used to associate the Alert List with another List by mapping a common data column. A second column (other than the mapped common data column) in the linked List is then used to provide an e-mail address as the email message recipient.

recipient advanced.png

Specify the following parameters:

  1. What SharePoint Site stores the Alert List? Enter the URL path to the site where the Lookup List resides. The Lookup List contains a column that identifies the user or email address to receive the email message. After entering the URL, click Load to load the available lists in the Linked Lookup List selection list.

    Icon-Tip When possible, use relative URLs. For example, in the above configuration, ../ indicates the list we need to lookup to is in the parent site above the current site.

  2. Linked Lookup List Select the Lookup List, which is the list that contains the person or email address to receive the email message.

    As an example, consider that the alert list is a Task list. Another list in the same site stores information about Projects, including the Project Title and Project Manager. The Task list has a lookup column called Project that looks up to the Title column of the Projects list. To send an alert email to the Project Manager when a task is overdue, select the Projects list as the Linked Lookup list.

  3. Column to map to Alert List Indicate the column in the Lookup list to match to the column in the Alert List in order to find the item that contains the person or email value.

    Continuing the example started in Step 3 above, the column in the Linked Lookup list to map to the Alert List is the Title column.

  4. Alert List Column Indicate the column in the Alert List to match to the column in the Lookup List in order to find the item that contains the person or email value.

    Continuing the example started in Step 3 above, the column to map to the Alert List is the Project column.

  5. Set how the e-mail address is resolved from the Lookup List
    1. Linked List column that identifies the recipient This is the column in the Linked Lookup list that contains the Person or Email address.
    2. E-mail Address Source If the column in Step 5a above is a Person, choose SharePoint User Profile so the email address can be retrieved from the SharePoint User Profile. Otherwise, the column should contain the actual email address, so choose Column Value.
Lookup an email address in the alert list

This option allows you to select a column in the Alert List that contains either the alert recipient (a Person) or an email address.

recipient in alert list.png

Configure Where are the e-mail addresses to lookup stored? You have three options to choose from; each option is described below with the associated choices that display for each.

  1. In SharePoint User Profiles: When this option is selected, choose a Person or Group type column in the Alert List that contains the name of the person to receive the email message.
  2. The Column contains the E-mail Address When this option is selected, choose a Single Line Text type column in the Alert List that contains the email address to receive the email message.
  3. In a Contacts List This option is similar to that described in the (Advanced) recipient type earlier. To use it, there must be a lookup column in the Alerts List that looks up to the Contacts list. When it is selected, the interface changes slightly to that shown below.

    HW05_RecipientsTab_EmailAlertList_Contacts.jpg

    • What SharePoint Site stores the Alert List? Enter the URL to the site where the Contacts list resides. click Load to load the available Contacts lists from that site.
    • What Contacts List should be used? Choose the Contacts list.
    • Which user lookup column in the Alert List should be used to find the recipient?Choose the lookup column in the Alert List that looks up to the selected Contacts list.
Send to a fixed set of Users or Email addresses When you select a fixed set of users or email addresses, you are presented with two choices for type of recipients; depending on your choice, you can manually enter some emails, perform a search for SharePoint users, or pick from a list of users in your SharePoint site.
HW05_RecipientsTab_FixedUsers.jpg

NOTE: If you decide to type in the list of e-mail addresses to send the alerts to, you must separate each entry with a semicolon (;). If you get this warning message:

The following errors were found on the Recipient(s) Tab:
* You must enter a valid e-mail address.

Remove the space after the semicolon; SharePoint does not like the spaces between each name.

Send to a SharePoint list Using his option, you can send alerts to users or groups stored in a SharePoint list column. You will need to type in the full site path to the SharePoint List and click the Load button. From there you can select the list, the list view, the list column that contains the user, and whether that column contains an email address, or if the email address needs to be pulled from the SharePoint user profile.

HW05_RecipientsTab_ContactsList.jpg
Send to members of a SharePoint Group or AD Group When you pick this option, you can search for users, select from a list of SharePoint groups in your site, or select from a list AD groups. After selecting a group using any of these methods, click the Add Group button to populate the Recipient Group window below.

HW05_RecipientsTab_Group.jpg
Send to me This option does not open another window because there is nothing to pick; the web part will simply alert you. It finds your e-mail address in your SharePoint user profile.
Start a workflow

If you have active workflows associated with the list you are alerting on, they will appear in the Available Workflows window.

Icon-WarningIMPORTANT: Only workflows that can be started manually from the alert list are listed.

Highlight a workflow in the Available Workflows list and click the single arrow to move it to the Selected Workflows list.

HW05_RecipientsTab_StartWorkflow.jpg

Icon-Tip Starting a workflow using Alert Plus can help simplify your workflow and provide an alternative to using delays or waits in the workflow.

Include a link to the file that triggered the alert

Include a link to the file that triggered the alert

Issue

Have you created an alert on one of your document libraries to let your users know when a new document is added or when an existing document is modified? This works great, but the hyperlink associated with the {itemlink} token goes to the display form for your file, not the file itself. Some users expect that the hyperlink in the e-mail message will open the file for them.

doc file prop page1.pngIn other words, when your users click on the default link they see the meta data for the document in the document library and need to click on the link there to view the file. For some, this is one too many clicks.

Resolution

Here is how to customize the item link so it opens the file rather than the form for this specific alert.

NOTE: In the example here, we are using a Document Library that has folders. This is a more complex issue, since the URL to the file will include the folder name. If the file is buried in several levels of folders, its even more complex since the URL must include the list of nested folders.

Follow these simple steps:

Step Action
Configure the alert. In the Event tab, specify the list or library to alert on. In this example, we will send an email alert when existing files are modified.

alert event tab.png
Configure who will receive the email message in the Recipient tab. The configuration on this tab will not impact the mail format.
On the Mail Format tab, compose the message that the e-mail recipient will get. Use the regular {itemlink} token; we will configure it later in the Options page of the Mail Format tab.

Icon-Tip Note the token {FolderName} in the email subject. This token will tell the e-mail recipient the folder the modified file was in.

mail format tab1.png

Using the above mail format with the default {itemlink}, an email from this alert will look like that shown below.

example email with default itemlink.png

Icon-Warning IMPORTANT: Note the URL for the item. We will use it when configuring the custom URL.

Because we don’t want the default behavior of the {itemlink} token, we need to adjust it on the Options page of the Mail Format tab.

custom item link on options page.png

Add a Custom Item Link by entering a URL in the box provided. The default link from the email example above looks like this:

http://hvbs20134/sites/Bamboo/IT/IT20Contracts/Forms/DispForm.aspx?ID=10

In order to link to the file, we need to change the URL to include the folder name (if one exists) and the name of the file, which is stored in the Name column of the library.

The new link is:

http://hvbs20134/{FolderPathName}/{Name}

This Custom Item Link applies only to this alert. Notice that we used a token {FolderPathName}. This is different than the token {FolderName} we used in the subject line of the email. {FolderPathName} is usually the best choice to use unless you are sure that no subfolders will ever be created.

  • {FolderName} includes just the name of the specific folder where the file resides.
  • {FolderPathName} includes the site (or sites if the library is in a subsite; the server or web app name is NOT included in this token), library name, and list of nested folders with slashes appropriate for a path. For example, if my file is in a folder call Folder A1 which itself is in a folder called Folder A, I need to use the {FolderPathName} to get the name of the nested folders where the file resides.

Icon-WarningIMPORTANT: Token names are case sensitive! If you use a token {foldername}, you won’t see any data. You must use {FolderName}.

How to remove an employee from alert processing

How to remove an employee from alert processing

The best way to begin is to login as that user and use the Alert Plus Subscriber Web Part to get the list of alerts the employee is subscribed to. Check the recipient type options for these alerts and delete all alerts that the user created selecting “Send to Me”. If they are part of a “Send to a Fixed Set of Users or E-Mail Addresses”, then edit those alerts and remove them from the recipient list. Alerts that are based on a Contacts list, site group, or cross-site group can remain, but the departing employee should be removed from the source group. Alerts with a lookup recipient type will need to have the source column for the e-mail address reset to another user.

Use the ‘A specific column in the list changes’ Trigger Type

Use the ‘A specific column in the list changes’ Trigger Type

The following outlines how to quickly configure an alert when the status of a task changes. This alert uses the trigger type A specific column in the list changes.

Go to the page in your Portal, where the Alert Plus Web Part exists. If it hasn’t been added to a page yet, see How to add a web part to a SharePoint wiki page.

Icon-Tip It is not necessary to add an Alert Plus Web Part to a page in each site. Because you specify the URL for the site where the alert items reside, you can consolidate your alerts in one web part on a single page in your site collection.

Step Action
1. From the Alert Plus toolbar, click New Item.

click new item in alert plus.png
2. Give the new alert a title. You won’t be able to save the alert without a title.

alert title.png
3.

Identify the site where the items that will trigger an alert reside. First choose whether they are in a SharePoint List or Library or a Bamboo List Rollup. For our current example, we choose SharePoint List or Library.

Icon-WarningIMPORTANT: There are a few trigger types that are NOT available if you choose to alert on a Bamboo List Rollup. They are:

  • A specific column in the list changes
  • An item in the list is deleted.

Next, enter the URL for the site of the List/Library. After entering the URL, click the Load button to load the available lists/libraries into the What List contains the items to alert on? box.

tell us where alert items reside.png

Icon-Tip When possible, use relative URLs. For example, if the alert items reside in a list on the current site, enter ./ in the What SharePoint site stores the Alert List? box.

4. Select the list from the What List contains the items to alert on? box. For this example, we choose the Tasks list.
5. Choose a What triggers the alert? option. For an alert that is sent when the Task Status column changes to “Waiting on someone else”, we choose A specific column in the list changes.

what triggers the alert.png
6. Choose How often are e-mails sent? For this example, choose As Soon As Possible so the email recipient receives the message as soon after the change as possible.

how often are emails sent.png

For information about the other options, including Combining multiple alerts into summary notification, see How often should E-mails be Sent.
7.

What column values should generate an alert? For the A specific column in the list changes trigger type, you are required to enter some criteria to indicate which column you want to watch. Notice that the radio button options for Which items in the List generate an alert? change so the only option displayed is Build Criteria Below.

altered column list.pngWhen you choose this trigger type, the contents of the Field Name lists in the Criteria Builder change. Two entries appear for each column in the list or library. One entry is the normal column name and the other is the normal name with /Old at the end.

Use the Criteria Builder to build the query. For this example, we want to be sure that the old value of Task Status doesn’t equal the new value. We also want to be sure that the new value of Task Status is Waiting on someone else. Our query looks like this in the builder:

criteria builder cropped.png

NOTE: The Field Name drop down selection lists only field names; you need to enter in the text Waiting on someone else in order for it to appear. You can enter it in the Field Name or update it after copying the criteria to the CAML Query.

Click Copy Criteria to CAML Query Field to generate the CAML. The text that appears in the CAML Query box is:

<Query><Where>
<And>
<Neq><FieldRef Name="Status/Old" /><FieldRef Name="Status" /></Neq>
<Eq><FieldRef Name="Status" /><Value Type="Choice">Waiting on someone else</Value></Eq>
</And>
</Where></Query>
8. Click the Recipient(s) tab and choose the recipient of the email alert. See Overview of Alert Plus Recipient Tab for more information.
9.

Click the Mail Format tab and compose your message. To include columns values from or a link to the alert item, use tokens. For more information about tokens, see Using Tokens in your Alert Plus Email Message.

mail format tab2.png

Icon-Tip Tokens are case-sensitive! When using a token for a column from the list/library, be sure to use the exact display name for the column.

10. Click the Save and Close button on the toolbar to save the new alert.

What is a Custom Item Link

What is a Custom Item Link

options tab-custom item link.pngConfigure a Custom Item Link on the Options page of the Mail Format tab.

You may consider configuring it if the default {itemlink} token doesn’t fit your needs. See Using Tokens in your Alert Plus Email Message for more information about tokens in Email messages.

By default, the {itemlink} token provides a link to the display form for the item that triggered the alert message. This is the SharePoint standard item link.

However, when alerting on a document library, you may want the hyperlink to go to the file itself, rather than the display form. If so, see Include a link to the file that triggered the alert.

How Often Should E-mails be Sent?

How Often Should E-mails be Sent?

how often are emails sent with combine box.pngChoose how often emails are sent and whether to combine alerts for multiple items in a single message.

Alerts are processed with a SharePoint Timer Job. Timer jobs are monitored in SharePoint Central Administration. If desired, the schedules for the default jobs can be modified in Central Admin.

There are five available choices when configuring an alert. Four of them are associated with a default timer job that come with the Alert Plus Web Part out-of-the-box and the fifth choice causes a custom timer job to be created. Learn more about each choice in the table below.

Choice Why choose this? Timer Job Info
As Soon As Possible Choose this option if you want the email message to be sent as soon as possible after an item is found to meet the alert criteria.

The timer job that processes alerts with this setting is called Bamboo As Soon As Possible Timer Job.

By default, it is configured to run to run every two minutes.

Every Hour

Choose this option if you want to check for items that meet the alert criteria every hour. A message will be sent for each item that meets the criteria, unless the Combine multiple alerts into summary notification box is checked. If it is checked, a single message containing information for all items that meet the criteria will be sent to each recipient.

Icon-Tip Typically, when this frequency is picked, the Combine multiple alerts into summary notification box is checked to minimize the number of Email messages sent. See Combine Alerts into a Summary Alert for more information.

The timer job that processes alerts with this setting is called Bamboo Every Hour Timer Job.

By default, it is configured to run hourly, starting at 0 minutes past the hour.

Every Day

Choose this option if you want to check for items that meet the alert criteria once a day. A message will be sent for each item that meets the criteria. If the Combine multiple alerts into summary notification box is checked, a single message containing information for all items that meet the criteria will be sent to each recipient.

Icon-Tip Typically, when this frequency is picked, the Combine multiple alerts into summary notification box is checked to minimize the number of Email messages sent. See Combine Alerts into a Summary Alert for more information.

The timer job that processes alerts with this setting is called Bamboo Every Day Timer Job.

By default, it is configured to run daily, starting at 12:00AM.

Every Week

Choose this option if you want to check for items that meet the alert criteria once a week. A message will be sent for each item that meets the criteria. If the Combine multiple alerts into summary notification box is checked, a single message containing information for all items that meet the criteria will be sent to each recipient.

Icon-Tip Typically, when this frequency is picked, the Combine multiple alerts into summary notification box is checked to minimize the number of Email messages sent. See Combine Alerts into a Summary Alert for more information.

The timer job that processes alerts with this setting is called Bamboo Every Week Timer Job.

By default, it is configured to run weekly, starting on Monday at 12:00AM.

Every Month

Choose this option if you want to check for items that meet the alert criteria once a month. A message will be sent for each item that meets the criteria. If the Combine multiple alerts into summary notification box is checked, a single message containing information for all items that meet the criteria will be sent to each recipient.

Icon-Tip Typically, when this frequency is picked, the Combine multiple alerts into summary notification box is checked to minimize the number of Email messages sent. See Combine Alerts into a Summary Alert for more information.

The timer job that processes alerts with this setting is called Bamboo Every Week Timer Job.

By default, it is configured to run monthly, starting on the 1st of the month at 12:00AM.

Custom Schedule

Choose this option if you need something different than the other available options. Depending on the type of schedule picked, the interface will change to ask for the relevant information. See below for the required information to create a custom weekly schedule.

custom schedule weekly.png

NOTE: The Time of day to send alerts is the time of day the timer job will process. Alerts are not necessarily sent every time the job processes; they are sent when the job processes and find items that meet the alert criteria.

Icon-Tip If your alert needs to process lots of items, it may be best to create a custom schedule for it even if one of the default schedules would work just as well. Custom Timer Jobs are created for and process only one specific alert, where the default timer jobs process all alerts configured for the default frequency.

A new timer job is created each time an alert with a custom schedule is created. The job is specific for that alert. The name of the timer job includes the URL for site where the alert was configured and the alert ID. For example:

Bamboo Alert Plus Custom 
Timer Job - Weekly at 
thu 17:45:00 - site url 
[http://hvbs20134
/sites/Bamboo/TTM] 
- alert ID [11]

Edit an existing alert

Edit an existing alert

HW05_EditMenu.jpg To edit an existing alert in Alert Plus, click the Title of the alert or select Edit Item from the drop-down menu for the alert Title.

The alert configuration page is displayed with the current settings.

Icon-WarningIMPORTANT: Changes will take effect the next time the alert is scheduled to run.

AlertPlus.jpgMake your changes and then click the Save and Close button in the Alert Plus toolbar to save the updated alert configuration.

For information about possible changes, see:

Disable (or Enable) an alert

Disable (or Enable) an alert

HW05_DisableAlert.jpg

To disable an alert so that the alert job no longer runs or sends alert notification e-mails, edit the alert and change the Status of the alert to Disable.

When you want to enable the alert again, edit the alert and change the Status to Enable.

Determine Which Alerts You Are Subscribed To

Determine Which Alerts You Are Subscribed To

This capability is part of the Alert Plus Subscriber Web Part. Place this Web Part onto the desired page, and when users visit that page a list of the alerts they are subscribed to will be displayed. The list is limited to providing results from a single Alert Plus Configuration List whose path is specified in the Web Part Tool Pane. It will also only display the alert subscription list for the currently logged on user.

Delete an alert

Delete an alert

HW05_DeleteAlert.jpg

To delete an alert, move your cursor over the alert Title, click the item drop-down arrow, and select Delete Item. The alert will be deleted.

Icon-Tip Disable you alert before deleting it. This will ensure that any custom timer jobs and event handlers are removed before the alert is deleted.

Create a new alert

Create a new alert

Overview of the Alert Plus Web Part

Go to the page in your Portal, where the Alert Plus Web Part exists. If it hasn’t been added to a page yet, see How to add a web part to a SharePoint wiki page.

Icon-Tip It is not necessary to add an Alert Plus web part to a page in each site. Because you specify the URL for the site where the alert items reside, you can consolidate your alerts in one web part on a single page in your site collection.

To create a new alert, follow these steps:

Step Action
1. click new item in alert plus.pngFrom the Alert Plus toolbar, click New Item.
2. Give the new alert a title. You won’t be able to save the alert without a title.

alert title.png
3. The new alert will have a Status of Enable by default. If you don’t want this alert to run right away, choose Disable.
4. On the Event Tab, identify the source for the alert. The source can be a SharePoint list or library or a Bamboo List Rollup. For details, see Configure the Alert Plus Event Tab.
5. On the Recipient Tab, identify who will receive the alert. For details, see Configure the Alert Plus Recipient Tab for more information.
.
6. On the Mail Format Tab, configure the Subject and Body of the email message that will be sent when an item meets the criteria for the alert. For details, see Configure the Alert Plus Mail Format Tab.

Copy an alert

Copy an alert

Sometimes the easiest way to create a new alert is to copy an existing one and make any required changes.

HW05_AlertCopy.jpg

To create a copy of an existing alert, move your cursor over the alert Title, click the item drop-down arrow, and select Copy Item.

A copy of the existing alert—including its entire configuration—is created and added to the list of alerts. The Title column of the new alert will be prefixed with “Copy of” and can be changed by editing the alert.

Important: The new alert job will be disabled by default, even if the original alert was enabled. This prevents duplicate alerts from being sent out before you have a chance to edit the alert configuration. To enable the new alert, edit the alert and change the Status field in the Event tab to Enable.

Combine Alerts into a Summary Alert

Combine Alerts into a Summary Alert

When you configure an alert that sends a notification immediately, receiving one message per item is usually the expected outcome. However, when you schedule an alert to be sent once per hour, once per day, once per week, once per month, or on a custom schedule, you usually want just one email containing information about all the items that met the alert criteria during the timeframe. For example, if you have three tasks coming due in four days, you may want information about all three tasks in one email message rather than receiving three separate emails.

Follow these simple steps to configure an alert that combines information from multiple alert items into one message:

Step Action
1. how often are email sent with checkbox and choice.jpgOn the Event Tab, specify the frequency of the alert.

2. Check the Combine multiple alerts into summary notification.
3.

On the Mail Format Tab, configure the mail message. Consider these tips when formatting your message:

  • The Subject line appears only once in the message, so don’t include any tokens there unless the value displayed will be the same for all items included in the message.
  • By default, the Body will be repeated for each alert item that meets the alert criteria during the timeframe, so include something that will visually separate one item from the next.

Consider the two Summary Alert examples below:

sumary example1.jpg 1. This format…

summary ex1 email.jpgGenerates an email that looks like this.

sumary example2a.jpg 2. This format…

summary ex2 email.jpg…generates an email message like this:

4.

In Alert Plus 4.0 and later versions, you can break email content into separate sections for header, body, and footer.

To do this, simply add the email content in the desired layout, then use the HTML editor button a the bottom of the message window. Add the flowing tags to break the email into the desired sections.

Icon-Warning IMPORTANT: The tags described below are case sensitive. If you do not use the correct case in the header and footer tag, the content located inside these tags will be repeated rather than appearing just once.

  • Add “<#Header>” to mark the beginning of the header section, and “</#Header>” to mark the end of the section. Any content located inside these brackets will appear at the beginning of the alert, and will not be repeated for each item.
  • Add “<#Body>” to mark the beginning of the body section, and “</#Body>” to mark the end of the section. Any content located inside these brackets will appear in the middle of the alert, and will be repeated for each item in the summary.
  • Add “<#Footer>” to mark the beginning of the footer section, and “</#Footer>” to mark the end of the section. Any content located inside these brackets will appear at the end of the alert, and will not be repeated for each item.

    Icon-Tip The header, body, and footer tags can also be used to break up other HTML content to handle activities such as creating a single table that contains multiple alert items. For this example, simply place the <table> tag in the header section, the <tr> and <td> tags in the body, and the </table> tag in the footer.

CAML Criteria Builder

CAML Criteria Builder

Overview of Alert Plus Event Tab

When configuring the Event tab in Alert Plus, you have a choice regarding which items in the List will generate an alert for you. That choice gives you a variety of options to choose:

  • Everything in the list generates an alert
  • Items in a particular view will generate an alert
  • Some Items (Advanced) allows you full control over the set of items in the Alert List that generate alerts. In order to specify which items to alert on, you will build a CAML Query that will be used to filter the list.

The easiest way to build a CAML Query is to use the Criteria Builder Tool on the Alert Plus Event tab. This tool provides a simple user interface to construct filter criteria and save it to the CAML Query field. This filtering capability allows you to specifically target your alert on items with specific List field values. Once you get familiar with it, the CAML Query builder is fairly simple and straightforward. The Criteria Builder resides at the bottom of the page. You simply pick the criteria based on content in a field.

As an example, consider an alert sent when the Author field is equal Mark Twain:

Step Action Result
1. Choose from a drop down list of all the columns in the list; in our case, we selected Author Equals.png

Some content may not be labeled in identical ways; some may enter “Twain, Mark” or some may use “Mark Twain” so in this instance, we prefer to use the comparison “Contains” and eliminate extraneous values so that the query finds anything in the author column that contains “Twain”.
Contains.png

2. Choose the Comparison operation.
3. Type in the Value; in this example, Mark Twain.
But we want to set an alert on multiple values; for example, whenever a document contains one value or another.
4. In our example, we want to pick on the Author column again, but in this instance choose Twain or Dickens. AndOr.png
When selecting the Or option, a second level on the Criteria Builder becomes available so we can further define our selection criteria.
5. Once we have built our criteria, we use the button at the bottom of the web part to copy our criteria into the CAML Query box. Copy2.png
CAMLQuery.png
When you look closely at that string inside the CAML Query box, you can make out some of the choices we made in the criteria builder. Notice the statement is referencing the Author column, the value is Text and the words that we typed into the Value box are spelled out “Twain” “Dickens.”

The above example is a very simple way of explaining the Alert Plus Criteria Builder. Developers and power users can become very proficient in writing CAML Queries and Bamboo provides this option to give you quite a lot of control over setting alert criteria.

Also see Additional Tips for using the CAML Criteria Builder

Alert on a Tasks List and send alerts for every task to the assigned person

Alert on a Tasks List and send alerts for every task to the assigned person

As a project manager, you have set up a Tasks List for the team to work on their assignments. Every time a Tasks List item is created or updated, you want to send an alert message to the person to whom the task is assigned. This use case uses the standard SharePoint Tasks List with the Assigned To field defined as a lookup field to the SharePoint User Profile where the e-mail address is stored.

Alert List – What list contains the items to alert on? Tasks List
Event Type – What triggers the alert? An item is created or modified
E-mail Frequency – How often are e-mails sent? As Soon As Possible
Item Criteria – What items in the list generate an alert? All Items
Who should the alert e-mails be sent to? Lookup an E-mail Address in the Alert List
Where is the e-mail address to lookup stored? In SharePoint User Profiles
Which user lookup column in the Alert List should be used to find the recipient? Assigned To

hw05076.jpg

hw05078.jpg

Step 1 – Create Alert Event

  • Select the Tasks List from the drop-down list.
  • Select the trigger action for when the item is either created or modified.
  • Select mail frequency for when you want the alert e-mails to go out.
  • For filter criteria, select All Items in the list.

Step 2 – Create Recipients

The Assigned To column in the Tasks list is a lookup field into SharePoint’s User Profile Information. We will set Alert Plus to use this field to resolve the recipient e-mail address. That way each e-mail alert will go to the individual that is assigned the task.

hw05080.jpg

  • Select “Lookup an E-Mail Address in the Alert List” from the first drop-down list.
  • Select the “Assigned to” column which is the index field to the user profile information.
  • Select “in SharePoint User Profiles” as the source of e-mail addresses.

Step 3 – Create E-Mail Message

Create your notification e-mail message.

Add a Hyperlink Tag in the Email Message

Add a Hyperlink Tag in the Email Message

email example with long URL.pngWhen you use the {itemlink} token in the body of your email message, the URL to the item that triggered the alert is displayed in the message, as shown here.

If your URL is really long, you may prefer to have the link associated with a word or an image.

Using the format for the email shown above as an example, follow these steps to use a short hyperlink to the email message body.

Step Action
Edit the alert.
edit alert.png
On the Mail Format tab, modify the email body in HTML view.
edit email body to add hyperlink.png
In the HTML view, add a hyperlink tag.

add a tag to html view.png

The tag added has this syntax:

<a href="{ItemURL}">HERE</a>

Icon-WarningIMPORTANT: Use the {ItemURL} token in the tag, not the {itemlink} token! Be careful, tokens that refer to list columns are case-sensitive, but other tokens are not.

When finished, click back to the Design view to make sure you like your change.
go back to design mode.png
The new email should look like this:

example of email with short url.png