Conditional Alerts

Definition

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.

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 Custom Schedules 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:

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:

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:

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:

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 Custom Schedules for more information.

At

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

Start Date

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

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:

Recipients

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

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:

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

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

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

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: