Messaging can also be set up to allow users (mobile workers or cases) to initiate interact with the system themselves. This functionality can be setup through SMS Keywords.
A mobile worker or case can message the keyword to an HQ phone number. This will trigger a form to be run for the user.
For example, a mobile worker may want to register a new beneficiary or a beneficiary may need to request a service or report some information.
Some caveats:
Only known phone numbers can use keywords. To allow users to register themselves in the system, see SMS Self Registrationarchived.
If a Mobile worker sends in a keyword to initiate a form that normally requires the user to first select a case from the case list, then they will also need to provide the external ID for that case. For example, if you have keyword "edit" tied to a form that updates a case, the mobile worker will need to send in "edit <external_id>", where <external_id> is the external_id case property of the case they wish to open the form for. This is true for both normal keywords and structured SMS.
Keyword Set-up and Example Keywords
To setup the keyword, choose the Messaging tab, then In the left side bar, select "Keywords". Click the "+Add Keyword" button.
Keyword: SMS Response
When setting up a keyword, you need to specify the following:
Basic Information
Keyword: This is the word that the user will message to initiate the interaction. Keywords need to be unique within a project.
Description: A description for the keyword does.
Respond to Sender
Send: This controls what is sent to the person sending the keyword (a simple message or an SMS survey)
Survey or Message: The survey or message to send
Notify Another Person:
This will let you notify another contact when someone sends a message to the keyword.
Recipient: The person to send the message to, a mobile worker group or the case's owner if the message was sent by a case.
Send: This controls whether to send the person an SMS message or a survey.
Survey or Message: The survey or message to send.
Advanced Options:
Restrict Keyword Initiation: Restrict the type of contact who can use this keyword. Use 'Case Only' if you want to escalate messages to the Case Owner.
Once you've specified the keyword and form, save the keyword.
Keyword: SMS Survey
Advanced Options:
Override open SMS Surveys: Sending in this word will override any existing surveys that the user is currently filling out and trigger this keyword.
Notes:
SMS Surveys can have conditional triggers, for example send a satisfaction survey after a clinic visit.
By creating a keyword, you can simulate that condition, and test an SMS Survey in a reliable way.
Keyword: Structured SMS with Custom Delimiter
If the you choose Structured Keyword, if you want to send in all of your SMS questions at once.
The users are able to send an SMS that looks like <keyword> <answer1> <answer2> <answer3> etc.
The defaults assumes that the user provides answers to each question, separated by spaces. This will work well for most situations.
Custom Delimiter
To setup a custom separation character, check the custom delimiter option and choose the characters you want to use to separate each answer. This could be a "," or "|" or even multiple characters like "||".
This example below uses a period (.) as a custom delimiter.
Custom Delimiter: This is useful if you want to use something else to separate each answer. For example, if any of your answers have spaces, the default separator of a space will not make space.
Keyword: Structured SMS with Named Answers
Named Answers
Named Answers allow users to skip questions or answer questions in a different order. This works by allowing the user to provide an identifier for each answer.
To use named answers, check the named answer option.
Specify the Name that the user enters, and the question (via xpath in the form) that it maps to.
For example, you may want to map two properties
/data/name to "name"
/data/household_size to "members"
By adding a joining character, the name and the value are paired together. The joining character in this example is a semi colon : .
As you build your Named Answers set-up, look at the Example Structured Message to understand how the message should look.
Both of these examples are valid options
visit name:123 members:456
visit members:456 name:123
Setting up an SMS Information Service
To create an SMS information service, you need to define a keyword that the user can text (ex. INFO) and a form (survey) that manages the interaction with the user. For this example, we're going to create a brief form that provides participants in a study with information about the medical trial and content. Users will send in the keyword INFO and will receive a set of options asking them what they need information on.
Form Creation
You need to define a form (or survey) that controls the interaction flow with the user. You can visualize each question or label in the form as an SMS sent and received from the phone. You can use logic in your form to drive how workflow.
Review the instructions here on creating a form for CommCare Messaging (https://dimagi.atlassian.net/wiki/x/DirKfw). Some things to think through when building your form:
SMS Surveys only support text, number, date or choice questions. You can't capture pictures, GPS locations, etc.
Limit your messages to 160 characters or less. Some phones don't handle longer messages (and will have the content split into multiple messages).
Create a form and name it Information Form. Add a question titled "Which information?" with the options titled Medical Contact, Contact Study Staff and Leave Study.
Now we will add labels that provide the right information for each option. The text for the labels is "Please call Dr.Ravi at 19995551432", "Contact us at 18001321234" and "Text LEAVE if you want to stop study".
We also want to each label to only display based on the option chosen. We can do this using Display Conditions. Display conditions control whether a particular question is shown based on the answer to previous questions. Choose a label, go down to the Logic Section and hit the Edit button on Display Condition. You can then drag and drop questions from the left tree to setup the logic. An example is shown below:
Once you've setup the expression, Save and create similar logic conditions for each of the other labels. Once you're done, choose the green Save button in the corner of the form builder.
Keyword interaction
Once you've built your form, you want to set it up to run when the keyword INFO is sent in. This will start sending questions back to the person who sent in the keyword. Once they respond, the next question or label in the form will be sent back to them.
A keyword is managed or created from the Messaging section of the CommCare Messaging site and clicking “Keywords”.
Create a simple keyword called INFO that will simply reply with the form you created to the user. There are some options on the keyword page that are a bit more advanced (will let you send a message to someone else when the keyword is sent in, or collect additional data in the same message as the keyword). These are not needed here. Once you've setup the keyword, hit the Save button at the bottom of the page.
User registration
Users will need to be registered before they can interact with the system. There are two types of users who can interact with the system - contacts who are registered (cases) or mobile workers. Mobile workers are project staff who can use the system via SMS (ex. registering participants). Cases are just contacts registered with the system (ex. study participants). Depending on your use case, you may need to use setup cases, mobile workers or both. Details on how to register users are provided below.
This tutorial will introduce keywords. Keywords are used in Messaging to allow users to report data or request information from CommCare HQ. They do this by sending a special word in an SMS to a gateway connected to CommCare HQ. This tutorial will build a basic daily activity reporting system. Users will be able to report the number of houses they visited and participants they counselled on a daily basis. Supervisors will be notified if a given user does not report on their activity in a given data. We'll also have a keyword that allows a user to request help from their supervisor, which will send the supervisor an SMS messages stating that the user has requested help.
In this tutorial you will learn the following:
Setting up a Keyword for Structured Data Collection
Setting up a Keyword to Notify Another Person
Creating a Reminder to Send Out if a Data Collection is Missed
We'll now setup a keyword to report the daily activity for each user. To collect data, we first need a form that contains the questions we want to capture. This is similar to an SMS Survey (that is not actually used in any application but is only used by Messaging).
Setup the SMS Application
We need to add a new application to the existing project. This application will contain all the form that represents the data to be collected by each data collector.
Add a new application to the project by going to the Applications tab and choosing New Application -> Blank Application.
Update the first module and set the name to Data Reporter Surveys.
And then set the case type to data_reporter.
Add the Daily Activity Form
We'll add a daily activity form that is used by the data collector to report their work. This form will also contain a last_reported_date hidden value that will be saved to the case. We'll use this date to trigger alert reminders to the supervisor.
Rename the Untitled Form to Daily Report and add questions so it resembles the following:
Question ID
Type
Label
Required
Calculation
Question ID
Type
Label
Required
Calculation
number_visits
Integer
Number of Houses Visited
Yes
number_participants
Integer
Number of Participants
Yes
last_reported_date
Hidden Value
today()
Save the form and configure the case management for the form. This form will be setup to update or close cases. We'll only save the case property last_reported_date. When we setup the missed data collection reminder, we can use this case property to determine if the person was late to report data by more than a day.
Configure the Data Collection Keyword
To setup the data collection keyword, go the Messaging tab, then on the left side choose Keywords. Then click on the down arrow to choose Add Structured Keyword. This will add a keyword that is used for structured data collection (one SMS will provide multiple pieces of data).
We can now configure the basics of the keyword. A structured keyword will allow a user to answer all the questions in a given survey in a single SMS (by sending in a specially formatted SMS). For example, to report stock on hand, a user might send in SOH 65 12 to indicate they have 65 ORS packages and 12 zinc tablet packages on hand.
Keyword: This is the word that the user must send into the system to trigger the keyword. For this tutorial, we'll use the keyword REPORT
Description: A quick description for what the keyword does. For this tutorial, we can set the description to "Allows a data collector to report on their daily activity".
Survey: This is the survey that contains the questions to be answered. For this, we'll choose SMS Surveys - Data Collector Surveys - Daily Report.
Delimiters: This allows you to choose a different character to separate each answer in the message. For example, instead of sending SOH 65 12, some projects may prefer to send SOH-65-12. For this tutorial, we'll just use the default delimiter (a space).
Use Named Answers: This allows you to specify a name for each answer (useful if you want to allow users to skip particular answers). For example, instead of sending in SOH 65 12, a project may prefer to send in something like SOH o65 z12. This would then allow users to just send SOH z12 or SOH o65.
For this tutorial, we'll setup named answers to make it easier for users. We'll use h for houses visited, and p for number of participants.
The xpath refers to the question in the form that each named answer is mapped to. This is just the path of that question when writing logic in the form. For example, a question with the ID number_participants would have the xpath of /data/number_participants.
Example Structured Message: Based on the options you've chosen, you'll see a sample of the message that should be sent by a user.
In the Response section, we can configure a message that goes back to the sender or someone else when we receive the keyword. For this keyword, we can just send a message to the sender (the data collector) to let them know that we've received their report.
The advanced section will let you configure who can send in keywords (cases, mobile worker or both). There is also a setting to configure if they keyword will override any existing surveys. For example, if the user uses the word REPORT in a response to an SMS survey, this option will close that survey and trigger the REPORT keyword instead.
Setting Up a Case to Report Data
This tutorial requires the use of a two-way SMS gateway. Your project must be on the Pro or higher Software plan to test this out. Follow the instructions at https://dimagi.atlassian.net/wiki/x/hCTKfw to choose a gateway for your project. This gateway should allow you to do two-way messaging. The Twillio gateway supports most countries in the world, but you may have to pay an international messaging fee to use it.
Why Use Cases For Reporting Data
This tutorial is going to setup a case for each user to report activity data. (That is, each user who reports activity data is going to be a case). This is necessary for a couple of reasons:
Cases are used to trigger reminders - if we want to send an alert email if a daily report is missed, we need to have a case to store the information for that user
Cases can be associated with a supervisor (or a case owner). This allows us to send an alert to the supervisor instead of just to the case
Setting Up a Case Registration Application
We'll create an application in our project to register these cases that are used to report data.
In your project create a new application called Data Reporter Management.
Update the name of the first module to set the name to Data Reporters
And then set the case type to data_reporter.
Create the Registration Form
This tutorial assumes you already know how to create a form with hidden values. Rename the Untitled Form to Registration and add questions so that it resembles the following. Some important things to note:
We name the phone number question contact_phone_number. This is the name of the special case property that Messaging will look for when creating a new case. When entering a phone number here, it must include the country code. For example, for an US phone number you would enter 15551234567. For an Indian number you would enter a number like 919560196285.
We add a hidden value called contact_phone_number_is_verified with a calculation of 1. This is also needed as a case property for Messaging to know to send messages to a case.
The full definition of the form is listed below:
Question ID
Type
Label
Required
Validation
Calculate
Question ID
Type
Label
Required
Validation
Calculate
name
Text
Name
Yes
contact_phone_number
Phone Number or Numerical ID
Phone Number
Yes
contact_phone_number_is_verified
Hidden Value
1
Save the form and configure the case management to create a new case. Save all the questions as case properties. Its important the contact_phone_number and contact_phone_number_is_verified case properties are named correctly.
This form is now setup to create a register a case that will report on their daily activity. The phone number on each case is the phone number of the user who will report data.
Setup a Reminder Alert for Missed Data Collection
This reminder will be configured to go out in the evening if the user does not report data for the day. The reminder will be sent the day after the last_reported_date. Since the last_reported_date is updated whenever daily activity is reported, if the user does not report their activity, this will cause the reminder to be sent out on that day (since last_reported_date will be yesterday).
To setup a reminder, go to the Messaging tab, then in the left side bar choose Reminders. Then click on the + Add Reminder button.
We'll now configure when the reminder will be sent. Give the reminder a name (ex. Missed Report Alert) and scroll down to the Start section.
Send for Case Type: This controls which case type will cause the reminder to send. Choose data_reporter from the dropdown list.
Send Reminder For: This can be used to choose which cases will cause the reminder to send. We want the message to be sent to All Cases.
Day of Reminder: You can also control date and the reminder will be sent. For this reminder, we want it to be sent based on a Date In Case. Choose the last_reported_date and send the reminder after the date by 1 day.
Time of Day: We'll send this reminder in the evening at 7pm, so choose At a Specific Time and 19:00.
The next step is to choose who will receive a reminder. There are a number of options (the case, the case's owner, or a specific mobile worker group). We want this reminder to go to the case's owner (the supervisor).
We can now specify the message content to send. Choose the SMS send option and provide the message to send. For this reminder, we can set the message to "{case.name} did not report data today. Please check in with them." The {case.name} will refer to the name of the case (the data collector) in the message.
This reminder doesn't need to Repeat and we don't need any of the advanced options, so we can just go ahead and choose Create Reminder button.
Our system is now setup, so we can now test the messages and reminders.
Setup the HELP Keyword
We'll now setup a basic keyword that data collectors can use to indicate they need some help or support. This will trigger a message that will go to their supervisor indicating that the user needs some help.
To setup the data collection keyword, go the Messaging tab, then on the left side choose Keywords. Then click on the + Add Keyword button.
We'll now configure the basics of the keyword. We need to provide the keyword, description and indicate what needs to happen when the keyword is sent in.
Keyword: This is the word that the user must send into the system to trigger the keyword. For this tutorial, we'll use the keyword HELP
Description: A quick description for what the keyword does. For this tutorial, we can set the description to "Allows a data collector to request help from a supervisor".
Send to Sender: This will indicate how you respond to the sender of the keyword. You can respond with either an SMS survey or just a message. For this tutorial we'll just respond with a message.
Message: The message to respond with to the sender. Our message for this tutorial will be "Thanks for the message. We'll let your supervisor know."
Notify Another Person: This lets you send a message to another person when this keyword is sent in. We want to send an SMS message to the case's owner (the data collector's supervisor). The message for this tutorial will be "{case.name} has requested support. Please contact them." The {case.name} syntax will allow us to use the data collector's name in the message.
In the advanced options, we'll need to restrict the keyword for usage to only cases (since it will only be useful for data collectors).
We'll now setup a reminder that will go to supervisors (the case owner) if the data collector does not report their activity for a day.
Test the Keywords and Alerts
Now that our reminders and application is setup, you can use a mobile worker to register a new pregnant mother and view her scheduled reminders on CommCareHQ.
Install the application on a phone and register a new data collector using the application. Make sure you enter a valid different phone number (including country code) when registering the mother.
Test a Data Report
Use the data collectors phone number to send in a daily activity report (ex. REPORT h23 p86). You should see the report in the Message Log report and a reminder scheduled to go out to the mobile worker who registered the case. This reminder will be for the next day (so if data collector doesn't report data, the message will get sent out).
Basic Troubleshooting
If your messages are not in the message log, there is some basic troubleshooting that you can do.
Check the Error Log: View the Reports -> Messaging History report. This shows a list of all messaging events (reminders, keywords, etc.) and whether they had any errors. Review this list and address any issues.
Verify the Phone Number: You may have entered the phone number incorrectly - make sure you've included the country code when entering the number for the case or phone. You can also send test message. Go to the Messaging tab and choose Compose SMS. Type the phone number here and a message and choose Send.
Upcoming Messages not in Calendar: If the upcoming messages are not in your reminder calendar, then you may have not configured your reminder correctly. Use the Case List report to make sure the registered cases have the right set of case properties (and match your reminders).
