In addition to allowing users to view and interact with the iSheets you create, it is also possible to configure email alerts, triggered by new additions or changes to the data.
In order to have a successful working alert, you will need to ensure the following are in place:
- Enable sheet alerter needs to be checked in the iSheet properties page
- One of the iSheet views must be designated the Alerter view in order to tell the system which column details should be sent in the alert
- Any choice columns you want users to select for their email preferences must have Include within alert preferences checked on the specific column configuration page
- Each users Email preferences must be set in the iSheet module itself. A user must have one of the frequencies checked (immediate, daily or weekly) plus any particular choice values they wish to be alerted on
- The correct written condition must be entered into the 'Email alert conditions' text field in the iSheet properties page
Further information about all the items listed can be found here.
iSheet alerts are independent of general system alerts and need to be configured separately for each iSheet you create.
Enabling iSheets Alerts
The first step in creating any iSheet alert will be to enable the function from the Properties page of a particular iSheet. Navigate to the iSheet administration area accessed from the Admin module of a site and click directly on the linked name of the iSheet you wish to enable.
This will then take you to the Properties page where you will find the option to enable the alert at the bottom of the page, as shown below.
Once Enable sheet alerter is checked the column references and Email alert conditions field will appear.
Make sure you save this change by clicking the save button at the bottom right of the page, as we will come back to this location once we have configured the rest of the alert requirements. This is where we will enter the written condition that will drive the logic of the alert.
Email View
You need to tell the system what information should be sent when an alert condition is encountered. We do this by assigning a view as our designated Alerter view.
Navigate to the iSheet administration area and click the more actions icon to the right of the iSheet you want to assign an Alerter view for and select Manage views, as seen below.
Once you have selected this you will be presented with the views that are available to be assigned as the alerter view. Click the more actions icon to the right of the desired view and set that view as the alerter view by selecting Set as alerter view.
Once selected, the view will indicate that it has been set, as below. There is no need to save this configuration.
Only one view may be designated as the alerter view.
Including in Email Preferences
If you want to give users the option to be alerted when specific choice values are selected in an iSheet record, then you need to make sure that those columns are included in the Email preferences. This means that when a user sets their Email preferences from the iSheet module, those included columns will appear and the user can select which choice values should trigger alerts.
This option is reserved for Choice columns.
From the iSheet administration area, click the more actions icon to the right of the iSheet, select Manage Columns and then click on the column you wish to include. Near the bottom of the column specific settings, you will see an option to Include within alert preferences. Check this option and save the column configuration at the bottom of the page.
Email Preferences
Each user, regardless of their status, has the ability to set their own iSheet email alert preferences. They may select the frequency of the alerts they receive, and if available, they may also select which choice values to be alerted of. With this in mind, a Site Admin can also set the preferences for each user. If you intend to set up alerts in a specific way, it may be advantageous for the Site Admin to set these in advance of granting users access to the iSheet and issuing some instructions to the users that the alerts have been preset. Email preferences must be set on a user by user basis.
To set your own or a user's alert preferences, whilst viewing the iSheet you wish to set alerts for, click the more actions menu at the top right of the iSheets module and select either Email Preferences or Set user email alerts.
In Email Preferences, choose a frequency (users will need to have at least one of the three frequencies to receive alerts) and check any specific choices you wish to be alerted on from the available options that have been included in the alert preferences and click Save. These preferences must be set for all users you want to receive alerts.
Alert Conditions
Alert conditions are the "engines" of iSheet alerts. Using a predetermined syntax and logical operators, we can create conditions that enable us to craft specific alert behaviours. The basic idea is that the condition formula must evaluate to true in order for the condition to be satisfied and the alert triggered.
Below are some examples of how alert conditions are written and their expected behaviour. You may copy and paste the syntax in the examples into your email alert conditions field and replace the column references (the operand) with those displayed in your iSheet.
containsAnyOf(#{col_1283}, 'NY')
The above condition is a hard-coded condition, where the value that triggers the alert has been hard set in the condition itself. This condition is saying IF column 1283 is equal to NY, then send an alert to all subscribed users, based on the frequency they have selected. This kind of alert condition ignores any specific choices the user has set in the preferences.
containsAnyOf(#{col_1283}, 'NY') || containsAnyOf(#{col_1283}, 'NJ')
This is a combination of two conditions joined together by the use of a logical operator. It is possible to combine any number of columns together using the AND or OR operators. The two operators used in creating combined conditions are as follows:
|| = OR
&& = AND
Put simply, the condition above is saying, IF column 1283 equals NY OR NJ, then send the alert. Again these are hard-coded conditions that ignore any specific column alert selections.
containsAnyOf(#{col_1283}, #{ucol_1283})
You may have noticed that all Choice columns have two references in the Alert area. This is to allow us to refer to the user-selected email preference.
If you wish to alert on specific values entered into your iSheet record and allow your users to choose what those values will be (or indeed, choose for your users), then you will use this condition syntax. This condition informs the system that whenever an item is added or an existing item is modified to check each user's iSheet alert preferences and send an alert if the value of the choice column for that item (col) matches the user's alert preference (ucol).
Like with any other alert conditions, user-selected conditions can be combined via the use of AND or OR operators.
Receiving an Alert
Once you have completed all of the above configurations, you should begin to receive email alerts. The columns included in the email alert are determined by the columns configured in the designated alerter view:
Included in this email is a link you can click to take you to the Collaborate site to view the iSheet in full.
Notification options
When alerts are enabled on an iSheet, users will have the option to suppress an email alert, or to send it immediately to subscribed users. The default setting for iSheet email alerts is to respect a user's preference.
Selecting Send now to every subscribed user will trigger an immediate alert to those users who are subscribed to receive such email alerts as part of a daily or weekly digest. Note that a user who receives email alerts when the 'Position' choice column is equal to 'Administrative Assistant' however, would not receive a notification of an item added or modified with another 'Position' choice value, even if 'Send now to every subscribed user' is selected.
Advanced
Alerts for all item additions and modifications
Alert conditions must evaluate to a value of true (or 1), so it is possible to enter the number 1 by itself in the alert conditions field. Doing so will trigger alerts to subscribed users at their designated frequency every time an iSheet item is added or modified.
Alerter view filters
If you have configured filters in the designated alerter view, they will limit which items are available to trigger email alerts. Ensure that filters applied to the alerter view will not conflict with a user's email preferences. If you are providing a user with the option to select a Choice column value to trigger alerts, filters should not be applied on the alerter view that would filter out any of the choices a user may select. In the example above, if the email alerter view filtered out items where Position is equal to 'Technical Assistant', users who opted to receive email alerts for new or modified items where 'Technical Assistant' is selected for the Position would never receive alerts, as such items are not included in the alerter view.
Email preference configurations
If the Choice column allows a user to add their own values, that is, the Other option is enabled, it is not possible to set up a condition that is triggered when an Other value is selected. Even if a user subscribes to receive alerts on all values for that Choice column, alerts are not triggered if the Other option is selected for that item.
If you configure a hard-coded choice value as part of the alert condition, that choice column should not be made available to the users as an email preference. For example, a user may opt to receive alerts when Position equals 'Administrative Assistant', but if the alert condition is configured to only trigger alerts when Position equals 'Technical Assistant', the user will never receive an alert. Therefore, if the condition uses hard-coded values from the Choice column, do not include that Choice column in the alert preferences to avoid giving users the false impression that they can control which values for that Choice column will trigger email alerts.
Also, if a Choice column is included within alert preferences, but no corresponding choice condition is defined in the alert conditions field, the Choice column value options will appear in the email alert preferences but a user's selection(s) will have no impact on when alerts are triggered. Therefore, if a Choice column is not configured as a user choice in the alert conditions, do not include it in alert preferences.
Troubleshooting
If alerts are not sending, first confirm that all the configurations described in this article are properly set, and check that the alert condition syntax is correct. There are a few circumstances to consider in which alerts would not be sent:
- If a Choice column is included in the email alert preferences, but is left blank, no email alerts will be triggered. Consider making such a Choice column mandatory and/or setting a default value if this is not the desired behaviour.
- As described above, alerts are not triggered for a Choice column with the "Other" option enabled if the "Other" option is selected.
- Alerts are not sent when items are deleted.
