Notifications
To get to the notifications page select Modules and then Workflow, then click Notifications in the menu bar.
Notifications Page
Adding
Click the Add button.
Give the notification a name
Select the trigger
Select the notification target
Leave the checkbox Enabled as checked (unless you want the notification to be disabled)
The remaining settings will vary depending on the selections made for trigger and target
Note
Notifications can be sent to multiple comma separated email addresses.
Trigger
The following can trigger a notification:
A submission. A result submitted from a survey. Including submission from an oversight form (replaces old console update)
A task reminder. If a task has not been completed within the specified time.
A case management alert.
A periodic timer. Daily, weekly, monthly, quarterly or yearly.
A Server Calculation change
Submission
Settings include:
Trigger from any survey in the selected bundle or from a specific survey
Survey or bundle whose submission triggers the notifications
Filter. Restrict which records will trigger a notification. For example: "${age} > 80"
Note
A submission notification is only triggered once for each record of data. So if a record is updated through a submission from an oversight survey or a task then the notification will not be triggered. If you want to be notified when an update happens you will need to filter on data values set by an update.
Task Reminder
Task reminders can be specified for a task group. All tasks created in that task group will then have reminders associated with them.
Warning
Only task groups that contain tasks generated automatically from submissions to a survey can have a reminder.
Settings include:
Task Group that contains the tasks that will trigger this notification.
Interval. Duration after the task is created that the reminder will be sent if the task is not completed.
Note
The email address to be used for a reminder can be specified directly in the notification, as it can for any other email notification, and this is the most reliable approach to use. You can optionally specify that the email address comes from a question in the source survey that triggered the task. However this will only work if in the task group for "Initial Data" you specified "Pre-populate form with existing data" or "Update existing results". If you specified "No Initial Data" then the data for the email question is not retained in the task and it can't be used in a reminder notification.
Periodic
Available with Smap 23.07.
Periodic triggers run reports and automatically send them by email. Report data is filtered by dates determined by the selected period.
Daily: Data from the day before will be included.
Weekly: Data from the previous week will be included.
Monthly: Data from the previous month will be included.
Quarterly: Data from the previous quarter will be included. (Available in version 25.02+)
Yearly: Data from the previous year will be included.
Note
Data submitted the same day that the report is generated will not be included. So you can set a daily report to be created at 10am every monday and it will include data from the previous 7 days up until midnight on Sunday.
Note
If you set a start and end date in a report that is run automatically by a periodic notification, these dates are ignored. However, date ranges set in the report's advanced filters are still applied.
The settings are:
Report. The report to run. Either a survey report (only XLS reports are supported), which must be set up as a public report in the Reports module, or the Operations Summary of the organisation's case management and workflow, see Operations Monitor.
Target. Only email is available for periodic notifications
Period. Daily, weekly, monthly, quarterly or yearly
Time. The time of day at which the trigger should fire
Day of the week. (Only if weekly is set as the period)
Day of the month. (Only if monthly, quarterly or yearly is set as the period)
Month. (Only if yearly or quarterly is set as the period. For quarterly it is the month within the quarter, 1 to 3)
Email. A comma separated list of email addresses that should be sent the report
Subject. The email subject.
Content. The email content.
Server Calculation
Available with Smap 24.03
In notifications select a trigger of “Server Calculation”. You will also need to specify:
The survey containing the server calculation
The Server Calculation question
The value that will trigger the notification. Note this value should be text and quotes are not required.
Target
Notifications can be sent as:
An email.
A web hook. Calls a web service in another system with the data.
Escalation (assignment) of a case to a user.
A reference. Gives one or more users read only access to the record.
A SharePoint list. Inserts or updates a row in a SharePoint list.
DHIS2. Keeps aggregate totals in DHIS2 up to date as records change.
An SMS. Only if SMS has been enabled in the server settings (Server)
Email
Settings are:
Attach. Attach a PDF of the record or a link to a webForm containing the data. (Not available for periodic triggers).
Email. One or more comma separated email addresses
Email Question. A question that contains the email address. (If the trigger is a submission of a completed survey, not periodic triggers)
Email Meta Item. A meta item of the submission whose value is the email address, for example Submitter when user names are email addresses. Values that are not valid email addresses are ignored.
Send Email to assigned user. Also send the email to the user the record is currently assigned to, using the email address in their user details.
Subject. The subject of the email.
Content. The body content of the email.
Note
Email questions can be of type select multiple or select one. Enter the email address as the name of the choice
The subject and message content can be customised using data from the submitted results. Use the following placeholders in either:
${username} : The user who submitted the results.
${surveyname} : The name of the survey
${hrk} : The key that is created on the server
${instancename} : The instance name that is generated on the server
${device} : The device IMEI used to submit the results
${questionname} : Where questionname is the name of any question in the survey.
${assigned} : The person assigned the record as a case.
${url} : The link to a webForm if you specified that a webForm should be included in the email
For example:
${username} has submitted ${surveyname} with a value of age of ${age}.
Web Hook
Settings are the callback URL and optionally a user name and password. See Webhooks for what is sent and how to monitor the calls.
SMS
Settings are:
Phone Number
A question that contains the phone number in the submission (If the trigger is a submission of a completed survey)
SMS Sender Id. The ID of the sender that is shown to the user when they receive the SMS message
SMS content
Escalation
An escalation assigns a case to a user. The word usually means that the case has been reassigned to a different user because it has been "escalated" in importance, however it can be used to assign a user to an unassigned case.
Settings are:
Survey to complete. The survey for the user to complete. The survey needs to be in the same bundle as the survey that triggered the notification.
Assignment type. User or Role.
Assign User. When the assignment type is user, one of:
A named user.
Submitter. The user who submitted the record.
Assign from data values. Select the question that contains the user ident. If it has more than one value the first is used.
None. Leave the case unassigned, or unassign it.
Assign to users with role. When the assignment type is role, the case is assigned to the first user, in alphabetical order of their ident, who has the role and is allowed to access the record by the role's row filter. If there is no such user the case is left unassigned.
An escalation can be accompanied by emails. The settings are the same as for the "email" target, including the Send Email to assigned user checkbox.
Reference
Requires SmapServer v26.06. A reference gives users read only access to a record without changing who it is assigned to. The users to reference are chosen in the same way as for an escalation. See References.
DHIS2
Requires SmapServer v26.09
There are no settings. Whenever a record is added, changed or deleted, the totals for the period and organisation unit that record belongs to are recalculated and sent to DHIS2.
What is sent is set by the export mapping on the bundle, not here, so a notification is only the instruction to keep DHIS2 in step. See Sending data to DHIS2 for setting up the mapping and for what to expect once the totals update on their own.