Conditional Alerts

IMPORTANT

Before continuing, make sure you understand Case Management well.

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.



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 Custom Schedules 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 Registering a Case Contact.

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.