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.
...
Recipient Type | Description |
---|---|
The Case | The case which matches the rule will be a recipient. See Contact Registration. |
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. |
...
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. |
Bulk download and upload of SMS content in conditional alerts
This page is accessible via an upload button on the main conditional alerts page:
...
The page itself is a standard bulk upload/download page:
...
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).
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:
...
Create a new mobile worker in your project space (ex. 'Dummy Mobile Worker')
...
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.
...
Make your desired update to the conditional alert and click ’Save.'
...
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.
...
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:
Create a new mobile worker in your project space (ex. 'Dummy Mobile Worker')
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.
Make your desired update to the conditional alert and click ’Save.'
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.
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:
...
The page itself is a standard bulk upload/download page:
...
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).