Skip to main content

FV Decipher Support

All the topics, resources needed for FV Decipher.

FocusVision Knowledge Base

Alert Tag: Send Survey Email Notifications

 

 

Overview

The alert system enables you to receive notifications via email when specified conditions are met. Alerts are triggered when a respondent successfully completes a survey while the survey is LIVE or in testing.

Alerts will not be triggered by SST (simulated data) or DUPE respondents.

Use the alert system to stay informed and resolve any potential issues that may arise. Alerts can be set based on selections made at particular questions, when quotas have been reached or met a specified threshold, or based on any condition logic you see fit.

All alert emails sent out are stored in the survey.log file with the associated timestamp, label and email addresses sent to. Email bouncebacks and error messages are not recorded.

The alert system should not be used to contact respondents. Emails sent out this way do not respect remove lists, bouncebacks or prior spam complaints.

Messaging should be similar to what we have in other documents to learn how to set this up in the Survey Editor click here.

Make sure you are sending emails to a completely willing audience.

1: Attributes

The <alert> tag has access to the following attributes:

1.1: label - Set the Alert Name

The label attribute is a string representing the unique label for the alert.

e.g. <alert label="A1" ...>

1.2: emails - Set the To: Email Addresses to Receive the Alert

The emails attribute is a space-separated list of email addresses for those who should receive the alert.

e.g. <alert ... emails="bob@domain.com jill@domain.com" ...>

1.3: sender - Set the From: Email Address Sending the Alert

The sender attribute is the email address to show as the "From:" address for the email sent out

e.g. <alert ... sender="bob@domain.com" ...>

1.4: subject - Set the Subject Line of the Alert

The subject attribute is a string to show as the "Subject:" of the email sent out. For example:

<alert label="A1" ... >
 <subject>(/9d3/proj1234) Total quota has been met</subject>
 ...
</alert>

1.5: body - Set the Message Body of the Alert

The body attribute is the main message body of the email sent out. For example:

<alert label="A1" ... >
 <body>Quota marker /qual/ has reached its threshold (full)</body>
 ...
</alert>

1.6: cond - Set the Condition for the Alert

The cond attribute is the condition that must be met to send the alert email out. For example:

<alert ... cond="Q1.r1.c1 and Q1.r2.c3" ...>

1.7: marker - Set the Quota Marker to Target

The marker attribute is the quota marker to target for the email sent out (must be used with threshold). For example:

<alert ... marker="/Gender/Male" threshold="full" ...>

1.8: threshold - Set the Quota Marker's Threshold

The threshold attribute can be set to "full" or an integer value. If set to "full", the alert email will be sent out when the quota bucket is full. If set to an integer (e.g. 10), the alert email will be sent out when the bucket has been met or exceeded. When the alert is created through the Field Report, the threshold is set to "full". (Must be used with marker.) For example:

<alert ... marker="/Gender/Male" threshold="100" ...>

1.9: qns - Set the Question Data to Include in Alert Email

The qns attribute is a comma-separated list of question labels to include in the email that will show the respondent's data for the questions provided. For example:

<alert ... qns="Q1,Q2,Q3" ...>

1.10: manager - Include the Alert Activity in the Alert Center

The manager attribute is a boolean value that enables the alert to be shown in the Alert Center. If manager="1" is set, the alert will be stored in a database and shown in the Alert Center. If this attribute does not exist, the alert will not exist in the Alert Center and only an email will be sent.
(Note: If the survey is opened in the survey builder, the manager="1" attribute will be added to the <alert>)

<alert ... manager="1" ...>

will show the alert in the Alert Center.

1.11: reminder - Set a Reminder Email to Go Out

The reminder attribute is a boolean value that enables reminder sends to be sent out after a specified number of days. For example:

<alert ... reminder="1" days="3" ...>

1.12: days - Set the Number of Days Until A Reminder is Sent

The days attribute is an integer representing the number of days until a reminder email is sent out due to inactivity in the Alert Center. For example:

<alert ... reminder="1" days="3" ...>

1.13: link - Include a Link to the Respondent's Data in Alert

The link attribute is a boolean value that, if enabled, will provide a link to the respondent's entire survey results in the email sent out. This requires access to the reporting feature. For example:

<alert ... link="1" ...>

2: Survey Alerts

Survey alerts are triggered based on condition logic. You can supply logic relative to selections made at a specific question (or questions), extra variables relative to the respondent, or any other Python expression that you can come up with.

Alerts are triggered after the respondent has sucessfully completed the survey (e.g. qualified, terminated or overquota).

See the example <alert> below:

<alert label="Q1_Alert" cond="(q1.r1 or q1.r3)"
  sender="user@domain.com"
  emails="user@domain.com user2@domain.com user3@domain.com"
  qns="q1" link="1"
  reminder="1" days="3"
  manager="1">
  <subject>Selection Made at Q1</subject>
  <body>The respondent selected r1 or r3 at Q1 -- Please follow up and confirm that...</body>
</alert>

When a respondent selects r1 or r3 at question q1, the alert will be triggered. Illustrated in the screenshot above, the email sent to those specified in the emails attribute will contain helpful information including:

  • the case number and a link to the alert case in the Alert Center
  • the title, subject and main message of the alert
  • the selections made at the question(s) contained in the qns attribute
  • a link to the respondent's entire data collection for the survey

You can also dynamically set most attributes of the <alert> tag. Consider the following example, which updates the <alert> subject and receiving email addresses depending on the selection made at question q1:

<exec>
subject = "(%s) selected at question Q1"

if q1.r1:
    Q1_Alert.subject = subject % "r1"
    Q1_Alert.emails = Q1_Alert.emails + " user4@domain.com"
elif q1.r3:
    Q1_Alert.subject = subject % "r3"
    Q1_Alert.emails = Q1_Alert.emails + " user5@domain.com"
</exec>

<alert label="Q1_Alert" cond="(q1.r1 or q1.r3)"
  sender="user@domain.com"
  emails="user@domain.com user2@domain.com user3@domain.com"
  qns="q1" link="1"
  reminder="1" days="3"
  manager="1">
  <subject>Selection Made at Q1</subject>
  <body>The respondent selected r1 or r3 at Q1 -- Please follow up and confirm that...</body>
</alert>

The subject line was properly updated in the <exec> block and since r3 was selected, user5@domain.com also received an alert.

The <body> attribute cannot be set dynamically due to security concerns.

3: Quota Alerts

Quota alerts are triggered once based on the quota system and specific marker counts. When a respondent completes and fills a specific bucket to the threshold specified, athe quota alert is triggered.

See the example quota <alert> below:

<alert label="Gender_Males_FULL_Alert" marker="/Gender/Male" threshold="full"
  sender="user@domain.com"
  emails="user@domain.com user2@domain.com user3@domain.com">
  <body>Quota marker /Gender/Male has reached its threshold (full)</body>
  <subject>[selfserve/9d3/proj1234] Quota /Gender/Male reached</subject>
</alert>

Once the bucket for "/Gender/Male" has been filled, the email above would be sent to all emails listed in the emails attribute.

By default, quota alerts do not appear in the Alert Center. Manually append the manager="1" attribute to access the quota <alert> from the Alert Center. Consider the following example:

<alert label="Gender_Males_FULL_Alert" marker="/Gender/Male" threshold="100"
  manager="1"
  sender="user@domain.com"
  emails="user@domain.com user2@domain.com user3@domain.com">
  <body>Quota marker /Gender/Male has reached the limit (100)</body>
  <subject>[selfserve/9d3/proj1234] Quota /Gender/Male reached</subject>
</alert>

Once the "/Gender/Male" bucket reaches 100 completes, the alert above will be sent out and the case will be visible in the Alert Center.

4: Customize the Alert Email

You can use the nstyles file in your project's directory to override the default notification email that is sent out. Copy and paste the following into your nstyles file and override the content to fit the needs of your project:

*alert.email:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>$(subject)</title>
    <style type="text/css">
        body {
            margin: 0;
            padding: 0;
            -webkit-text-size-adjust: none;
        }

        body, #backgroundTable {
            font-family: arial, 'Helvetica';
            font-size: 15px;
        }

        body #backgroundTable {
            width: 100% !important;
            height: 100% !important;
        }

        p {
            margin: 0 0 20px 0;
        }

        table td {
            border-collapse: collapse;
        }
    </style>
</head>
<body marginwidth="0" marginheight="0" offset="0" topmargin="0" leftmargin="0">
    <a href="$(detail)#/?case_id=$(case)">Case ID: $(case)</a>
    <br/><br/>
    $(body)
    <br/><br/>
    $(content)
    <br/><br/>
    <a href="$(detail)#/?case_id=$(case)">View Case in Alert Center.</a>
    <br/><br/>
    $(review_link)
    --
    <br/>
    This email was sent automatically. To opt-out from this alert, visit
    $(host)/apps/notify/$(path):mute?email=$(email)&label=$(label)
</table>
</body>
</html>

Learn more: The nstyles File

5: What's Next?

Check out these other documents related to the <alert> tag: