Conditional Alerts

A Conditional Alert is similar to a Broadcast in that you are sending content to recipient(s) on a specific schedule. The main difference is that for broadcasts the system only ever creates one instance of the schedule you define, and with conditional alerts the system creates an instance of the schedule for each open case that matches the given rule criteria.  Conditional Alerts are designed to create an instance of the schedule you define every time the rule's criteria go from being False to being True for an open case. That could mean that the rule is being run for the first time and it matches a case, or it can mean that a case which didn't match the rule before is later updated to match it.

Before continuing, make sure that you are familiar with the concepts of

 

About Conditional Alerts

Conditional Alert Use Cases

Send a Welcome Message

This is one of the simplest use cases. To send a welcome message once to each case contact you register, just create a Conditional Alert that sends for all cases of a particular case type, choose to send it Immediately, and choose to send it to the case. Then every time you register a case of that case type, your message will be sent to that case contact. 

Send an Appointment Reminder

Sending appointment reminders to your case contacts is another common use case. To do this, just choose to start the Conditional Alert on a date from a case property. You will need to store the date of the appointment in this case property from your app. You can then choose to send the reminder a certain number of days before that date, and choose who to send your message to the case (or whoever you want to).

Sending a Missed Appointment Alert

This use case is a bit more involved because it requires your app to work closely with the Conditional Alert. You start off the same as an Appointment reminder, by starting on a date from a case property. You then want to send the alert the day after the appointment. Most importantly, when the appointment takes place, in order for this to work properly, a user must fill out a form in your app to record the appointment and update the appointment date case property to either be the next appointment or be blank if there is no next appointment. This way, if the appointment happens, then the alert will either reschedule when the new appointment date is set or will unschedule if it is set to blank. But if the appointment does not happen then the appointment date will not change and the alert will be sent one day later. 

Sending an SMS Campaign

Sending an SMS Campaign can be accomplished by using a Custom Daily Schedule. See the documentation on  for more information.

How do Conditional Alerts Respond to Case Changes?

To understand how Conditional Alerts respond to case changes, consider the following example. Suppose your project has 3 cases, all with case type "person", and you track a "status" case property which can either be "green" or "red". These are the 3 cases in your project:

Name

Case Type

Status

Name

Case Type

Status

Joe

person

red

Jaime

person

red

Monica

person

green

With these three cases existing in your project, suppose you now create a Conditional Alert which will send an Immediate SMS to Mobile Worker Bob for each "person" case with "status" equal to "red". As soon as you save the Conditional Alert, the rule will run against all "person" cases in your project and for each one that is in "red" status, it will create an instance of the schedule (which in this case is an immediate SMS) to be sent to Mobile Worker Bob. Put simply, it will send 2 SMS to Bob - one in response to Joe being in red status and one in response to Jaime being in red status. From here on out, you do not need to resave the Conditional Alert to send new SMS - the system will automatically keep the rule up to date with changes made to your cases. If you do save the Conditional Alert again but don't make any changes, no new SMS are sent because nothing changed.

 

Now suppose a new case is created so that you now have 4 cases in your project:

Name

Case Type

Status

Name

Case Type

Status

Joe

person

red

Jaime

person

red

Monica

person

green

Oscar

person

red

When the case for Oscar is created, a new SMS will be sent to Bob in response to Oscar being in red status. No other SMS will be sent because no other cases were created or changed.

 

Now suppose Monica is updated to be in red status as well, so that now the 4 cases in your project look like this:

Name

Case Type

Status

Name

Case Type

Status

Joe

person

red

Jaime

person

red

Monica

person

red

Oscar

person

red

When Monica's case is updated, a new SMS will be sent to Bob in response to Monica being in red status because the rule went from being False to being True for her case. No other SMS will be sent because no other cases have been created or changed.

 

Now suppose Joe's case is updated, but his status is not changed - it's still red. In this situation, no new SMS will be sent because the rule was already True for Joe, and the schedule is only initiated when the rule goes from being False to being True.

However, if Joe's case's status was updated to be green and then updated to be red again after that, that would trigger another SMS to be sent to Bob for Joe because the rule went from being False to being True on the second update.

Rule Criteria

First specify all of the rule criteria for matching the cases that you want to create schedules for. All criteria must be true in order for the rule to evaluate to True for a case. Below are the different criteria options.

Case Type (required)

You must choose a case type that the rule applies to, and it cannot be changed after saving the Conditional Alert. Only cases with this type will match the rule.

Note that the case will need to have the case property contact_phone_number saved with the correct phone number (country code plus number) in order for the messages to send correctly. For instance, if I was registering a case in India (country code +91) the contact_phone_number case property should be saved with a value like 919833553138.

If you do not specify any other criteria, the rule will evaluate to True for all open cases in your project which match this case type.

Case Property (optional)

First, type the name of the case property to match. Then select the different match types from the following options:

Match Type

Description

Match Type

Description

equals

The case property must exist and must equal the given value. Do not add quotes to the value you enter.

does not equal

The opposite of "equals". So, if the case property does not exist then "does not equal" evaluates to True. Again, do not add quotes to the value you enter.

has a value

The case property must exist and must have a value other than a blank string or string with spaces.

does not have a value

The opposite of "has a value".

Schedule

On the scheduling tab, the first thing you will do is define the type of schedule to spawn in response to the rule matching a case. You can choose whether or not the schedule is active, and the Active / Inactive value chosen here has the same effect as activating / deactivating the Conditional Alert on the Conditional Alert List page.

From there, defining the schedule has the same functionality as for a Broadcast, with a few extra options:

Send

In addition to the schedule types available in a Broadcast, you also have one more custom schedule type available - the Custom Immediate Schedule. See for more information.

Note

If you choose an Immediate schedule, or a Custom Immediate schedule, you will not be able to change the schedule type while editing the Conditional Alert later on.

At

When choosing a Daily, Weekly, or Monthly schedule, you have a new option for the time to send:

Option

Description

Option

Description

The time from case property

When scheduling the content, the system will inspect this case property on the case that matched the rule. If this case property's value is a time (a string in the 24-hour format HH:MM), then it will schedule the content at this time. Otherwise, it will default to scheduling the content at 12:00.

Start Date

For Daily, Weekly, and Monthly schedules, you have a few options for the Start Date of the schedule:

Option

Description

Option

Description

The first available time after the rule is satisfied

As an example, if you have a daily schedule which sends at 9am and a case is updated to match the rule on 1st April at 8am, then the schedule created will start on 1st April with the first event being sent at 9am. If the case were updated on 1st April at 10am to match the rule, then the schedule created will start on 2nd April with the first event being sent at 9am.

The date from case property

When a case matches the rule, the start date of the created schedule will be the date from the value in the case property you specify here for that case. If the case property's value is not a date, then no schedule is created.

Note: If the value of the case property is a date which is in the past, then the first event scheduled will be the first event in the schedule that does not occur in the past. If all events occur in the past, then nothing will be sent.

A specific date

This is the same Start Date option as with a Broadcast.

Begin

You may also choose to actually start the schedule at some offset from the Start Date. The options for when to begin the schedule in relation to the start date depend on what type of schedule it is:

Type of Schedule

Description of Options

Type of Schedule

Description of Options

Daily

Exactly on the start date: The schedule will begin exactly on the Start Date as defined by the Start Date option

Before the start date by: The scheule will begin this many days before the Start Date as defined by the Start Date option

After the start date by: The scheule will begin this many days after the Start Date as defined by the Start Date option

Weekly

The schedule must begin on a specific day of the week. For example, if you choose Tuesday here, the schedule will begin on the first Tuesday that occurs on or after the Start Date as defined by the Start Date option, and for the purposes of the schedule a full week would start on Tuesday and end on Monday.

Recipients

The options for recipients are the same as for Broadcasts, with some extra options:

Recipient Type

Description

Recipient Type

Description

The Case

The case which matches the rule will be a recipient. See .

The Case's Owner

The owner of the case which matches the rule will be a recipient. If the owner is a user group, then all users in that group will be recipients. If the owner is an Organization, then all users assigned to that Organization will be recipients.

The Case's Parent Case

The parent of the case which matches the rule will be a recipient.

Note: This only works for parent/child relationships and not host/extension or parent/extension. If this is used with host/extension relationships, the SMS or email will not send and the error in the Messaging History Report will display as "Error - No recipient".

User Specified via Case Property

A commcare user whose username is a case property of the matching case. The case property in which to look up the username is specified in a text box under the recipient choices. The user must be a mobile worker in the same project space.

Email Specified via Case Property

An email address found in a case property of the matching case. The case property in which to look up the email address is specified in a text box under the recipient choices. This option can only be used for email alerts, not SMS ones.

Content

The options for content to send are the same as for Broadcasts.

When typing a message, you may also reference information about the case which matched the rule.  You can reference a case property in a message by writing {case.case_property_name}.  For example, you could write the following message "Hi {case.name}. Your appointment is on {case.appointment_date}".  Here is a list of all of the information you can reference from messages:

Reference

Meaning

Reference

Meaning

case.name

the case's name

case.case_property

any dynamic case property (here case_property is just an example)

case.parent

a reference to the parent case; for example, you can reference {case.parent.name}

case.host

a reference to the host of the extension case; for example, you can reference {case.host.name}

case.owner

a reference to the case's owner; for example, you can reference {case.owner.name}

case.last_modified_by

a reference to the user who last modified the case; for example, you can reference {case.last_modified_by.name}

When case.owner or case.last_modified_by is a user (web user or mobile worker), you can access the following properties:

Property

Meaning

Property

Meaning

name

the user's full username

first_name

the user's first name

last_name

the user's last name

phone_number

the user's preferred (first) phone number, if any

When case.owner is a group, you can access the following properties:

Property

Meaning

Property

Meaning

name

the group's name

When case.owner is an Organization, you can access the following properties:

Property

Meaning

Property

Meaning

name

the organization's name

site_code

the organization's site code

As a shortcut, you can also reference information about the recipient of the message using "recipient". For example, the message "Hi {recipient.name}, remember to take your medication" is also valid syntax. The reference to "recipient" will resolve to the recipient of the message and the properties that can be accessed from "recipient" will differ as described above whether the recipient is a user or a case.

NOTE: If you try to reference a value that does not exist, it will show up as "(?)" in the message.

Advanced

Besides the Advanced options which are shared with Broadcasts, the following options are available:

Option

Description

Option

Description

Restart Schedule

With this option enabled, you can specify a case property name in the adjacent field. Any time this case property's value changes on the case which matched the rule, then the schedule created for that case will automatically start over from the beginning, starting at that moment.

This is particularly useful for Immediate schedules. For example, you could set up a Conditional Alert which sends an Immedate message for each case that "has a value" for case property "last_transaction_id" in its rule, and then use this option to also resend the alert every time "last_transaction_id" takes a different value. This way, every time "last_transaction_id" takes a new value, the schedule will restart and a new Immediate message will be sent.

Note: Only dynamic case properties (that is, new case properties which you define in your app configuration) will work with this option. Also, once you set this option in a Conditional Alert configuration, it cannot be changed.

Interpret send times using GMT when recipient has no preferred time zone

This option is only visible for older reminders that were created with an older version of the scheduling framework. The old version of the scheduling framework would interpret all send times as GMT unless a contact had a preferred time zone configured. The new version of the scheduling framework interprets send times using the project's time zone (unless a contact has a preferred time zone). If you see this option, it means it is there to preserve the old scheduling framework's behavior that existed when this alert was created.

You may choose to disable this option, in which case send times will be interpreted using your project's time zone by default instead of GMT, but you will need to adjust the send times in your schedule accordingly. Also, once this option is disabled, it can no longer be re-enabled.

Use case property stop date

With this option enabled, you can enter the name of a case property that will act as a stop date for the alert. If the case property is blank or is not a date, it will have no effect. If the case property takes a value of a date, then the current date will be checked against the case property's date every time before the content related to the alert is sent, and if today's date is greater than or equal to the case property's date, the event will be deactivated and no content will be sent. Under some circumstances, you may see events scheduled in the Scheduled Events Report even if the date has passed, but those events will be deactivated before any content is sent.

Updating Conditional Alerts

Users should be careful when updating conditional alerts as it is easy to accidentally re-trigger messages to all cases that meet the conditional alert criteria. 

Currently, conditional alerts will re-trigger to all cases that meet the conditional alert criteria any time a conditional alert is updated (ex. modifying  the name of the conditional alert or schedule of an alert, etc.) The only time this re-triggering doesn't occur is when users update only the content of the alert: the subject line or body of email, or the body of SMS messages.

To avoid re-triggering messages, users should complete the following steps:

  1. Create a new mobile worker in your project space (ex. 'Dummy Mobile Worker')

  2. Open the conditional alert that you wish to edit and navigate to the ‘Schedule& Recipients’ tab. Change the ‘Recipient(s)’ to ‘Users’ and select the mobile worker you just created. This will cause all of the messages that are re-triggered to be sent to this user.

  3. Make your desired update to the conditional alert and click ’Save.'

  4. Navigate to the messaging dashboard and review the ‘Messaging Events (Success/Error)’ logs. You should see a large number of errors - these errors are the messages firing to the dummy mobile worker you just created. Please note that these messages will not impact Dimagi’s email bounce rate, however, if you are performing updates on many domains or are re-triggering many messages, you should contact support@dimagi.com or reach out to your contact on the support team to notify them that these errors are expected. After all messages have been re-triggered, which usually takes less than five minutes, you will stop seeing new errors in the message logs.

  5. Once all messages have been sent, navigate back to the conditional alert you were editing and update the ‘Recipient(s)’ to ’The Case’ (or whatever your desired recipient is) and click 'Save.'

Bulk download and upload of SMS content in conditional alerts

This page is accessible via an upload button on the main conditional alerts page:

e42b5874-59cc-4d7d-9c07-dc964a6d8ae9.png

The page itself is a standard bulk upload/download page:

Screen Shot 2019-07-05 at 10.27.24 AM.png

Download

The download is formatted into two tabs: one for rules with translated content, one for rules with untranslated content - corresponding to the "Translate this message" box you see when editing a rule in HQ.

The download contains each rule's id, name, and message content. For rules that use custom schedules, the download contains one row for each event associated with the rule.

See "limitations" section below for reasons why a rule would be excluded from the download.

Upload

The upload can be used to edit a rule's name or its message content.

Partial uploads are accepted:

  • Uploads missing rows: the upload will update whatever rules are in the sheet.

  • Uploads missing columns: the upload must contain an "id" column, but any other column - name, some or all of the message columns - can be excluded.

Rules with custom schedules are supported:

  • Like the download, the upload must contain one row for each event associated with the rule. You cannot add or remove events.

  • If updating the rule's name, you must update it in all rows.

  • If there are any problems with a custom rule, like blank content, the entire rule will fail to update.

You can move rules from the "not translated" sheet to the "translated" sheet and vice versa. See "limitations" for specifics around moving messages between sheets for rule that have custom schedules.

The upload will update all rules that it can and will display explanatory messages for any rules it cannot update. See "limitations" section below for caveats to the upload functionality.

The uploader does not cause the edited rules to be re-processed.

Limitations

  • This feature only manages conditional alerts that send SMS content. It does not handle email, SMS surveys, or custom SMS content.

  • This feature only edits existing rules. It does not add new rules or delete rules.

  • You cannot update rules that are currently being processed.

  • Only languages specified in Messaging > Settings > Languages will appear in the download. Similarly, any languages not specified in Messaging > Settings > Languages (e.g., a language that has been deleted) will not be updated even if included in the upload.

  • For rules that are not translated, the single message may not be blank.

  • Custom schedule handling

    • If the existing rule’s messages are all on the same sheet, you can update any of them and can move all of them to the other sheet. You can’t move only some of them to the other sheet.

    • If the existing rule’s messages are split between sheets, you can move messages between sheets only if you’re moving all of the messages from one sheet to the other sheet (and it’s important to be careful, because they will be matched based on order, so if you have a rule with events A, B, and C, and A and C are translated but B is not, if you want to move B to the translated sheet you need to insert the B row between A and C).