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. 

Before staring this tutorial, setup a new project space unless you've already done so. 

Create a Keyword to Report Daily Activity

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.  

1. Add a new application to the project by going to the Applications tab and choosing New Application -> Blank Application.  

Open

2. Update the first module and set the name to Data Reporter Surveys.

Open

3.. 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. 

1. Rename the Untitled Form to Daily Report and add questions so it resembles the following:

2. 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

1. 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).

2. 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. 

3. 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.

4. 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.  

1.. In your project create a new application called Data Reporter Management

2. Update the name of the first module to set the name to Data Reporters

3. 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:

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).  

1. To setup a reminder, go to the Messaging tab, then in the left side bar choose Reminders.  Then click on the + Add Reminder button.  

2. 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. 

3. 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). 

4. 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. 

5. 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. 

1. To setup the data collection keyword, go the Messaging tab, then on the left side choose Keywords.  Then click on the + Add Keyword button.  

2. 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.  

3. 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.  

Setup a Sample Case

1. Register a new mobile worker for your project and add a new phone number as described in https://dimagi.atlassian.net/wiki/x/-yjKfw.

2. 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).  

Other troubleshooting tips are available here: https://dimagi.atlassian.net/wiki/x/1S-Kfw.