Versions Compared

Old Version 23

changes.mady.by.user Shu-Chun Lu

Saved on

compared with

New Version Current

changes.mady.by.user Gillian Javetski

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

titleThis feature requires a CommCare Software Plan

...

Multiexcerpt include macro
macro_uuid9078ada9-7c16-4fe4-af1c-4ddd91c1ebe9
nameSoftware Plan - Advanced
templateDataeJyLjgUAARUAuQ==
pageCommCare Help Site Design Guidance
addpanelfalse

Table of Contents:

Table of Contents
stylenone

One of the primary uses of CommCare Messaging is to send out surveys via SMS.

Some common use cases:

  • Asking a patient if they have taken their medication

  • Asking a community health worker some questions about their most recent visit

Surveys are very easy to build because they use the same Form Builder as CommCare.

...

Getting Started

Navigate to the tab that is called "Applications."Image Removed

...

You can find basic information about the Form Builder here or in the Beginner Tutorial. It is highly recommended that you complete the Beginner Tutorial before proceeding.

...

Design your Survey

...

Panel
panelIconIdatlassian-cross_mark
panelIcon:cross_mark:
bgColor#EAE6FF

Warning!

Please do not make the first question in your SMS survey a question list. This may lead to errors in the sending of the SMS survey.

Please note that the following are not supported in SMS surveys:

  1. 'commcaresession' instances and 'location' instances are not supported in SMS surveys

  2. referencing lookup tables are not supported in SMS surveys (via conditional alerts). thorough testing is strongly recommended.

Referencing the Form Builder Page, you can think through the different types of questions you may want to include in your survey, and how you want the structure of your survey.

The most common question types for SMS Surveys are:

  • Text

  • Multiple Choice - Single Answer

  • Multiple Choice - Multiple Answer (Checkbox)

  • Label - is a message that does not require any action- it is only to provide information

Be sure to consult the CommCare Messaging best practices for helpful hints on designing a good survey.

Let's imagine we want to create a survey like this:

  1. Did you go to the clinic today? Yes/No

  2. Great! What doctor did you see?

  3. Why not? Clinic was closed/I felt fine/Clinic too far/Was busy

  4. Going to the clinic is important- please call 555-555 to reschedule your appointment.

We can add a bit more detail to make it easier to build. For each question you'll want to define:

  1. Question ID- how do you want the answer to the question to be tagged in the data export

  2. Label Text- the text that will be sent to the recipient

  3. Question Type- which of the question types above

  4. Options- if a multiple choice answer, what are the choices

  5. Display Condition- when do you want the message to be sent?

Below you can see one way of thinking about our survey:

Question ID

Label Text

Question Type

Options

Display Condition

went_to_clinic

Did you go to the clinic today?

Multiple Choice-Single Answer

Yes, No

Always show

next_appointment

Great! What doctor did you see?

Text

-

If went_to_clinic = Yes

why_no_clinic

Why not? 

Checkbox

Clinic was closed, I felt fine,

Clinic too far, Was busy

If went_to_clinic = No

reschedule

Going to the clinic is important.

Please call 555-5555 to reschedule your appointment.

Label

-

If went_to_clinic = No

CommCare Messaging will automatically number options; for example, the question why_no_clinic will be sent out as:

Why not? 1. Clinic was closed, 2. I felt fine, 3. Clinic too far, 4. Was busy.

...

Build your survey

Use the Form Builder to add questions, options, and display conditions just as indicated in the Beginner Tutorial.

The survey described above would look like this:Image Removed

...

It is important to keep things short! Specifically, when asking a multiple choice question you want to ensure that the text of the question, plus the text of all the possible answers fits in one message. If it is too long, it may be broken into multiple messages. Messages are not always assembled in the right order so it advisable not to have them break up.

There are certain words that cannot be used to test surveys. ex. SURVEY, START. 

...

Test your survey

Make sure to try out your survey before going live. You can give it a keyword (Setup SMS Keywordshttps://dimagi.atlassian.net/wiki/x/KCXKfw ) and register yourself in the system (Configure a Mobile Worker for Messaginghttps://dimagi.atlassian.net/wiki/x/-yjKfw).

Using the keyword you can try out the survey multiple times. To test the survey using the keyboard, text the system using the format: #start keywordImage Removed

...

When completing your survey keep in mind:

  • You can indicate a choice by replying with either the text of that choice or by simply putting the number of that choice (i.e. you can either reply with 2 or I felt fine. CommCare Messaging will ignore changes in spacing/capitalization, but not in spelling)

  • If your question is a Checkbox response you can reply with multiple numbers separated by a space. (i.e. in the example above you could indicate both Clinic too far and Was busy by replying: 3, 4)

If you reply with something that is not an acceptable reponse (i.e. there are 4 choices and you reply with "5") CommCare Messaging will send back a generic message that the response could not be understood, and that they should try again.

...

Schedule your survey & View Data

You can schedule your survey either using a Broadcast or Conditional Alert.

...

Data

...

Data from SMS Surveys are set-up in Forms. To review your SMS survey data, apart from other SMS data, you can go to the Form Exports in CommCare.

If you are looking for data from SMS users who are cases, be sure to select "unknown users" to export that information.

SMS Survey FAQs

What question types can I use to send out questions via SMS survey? 

  • Good

    • Integer, respond with a number

    • Single-select, respond with a specific choice

    • Date based, set the date sequence for your project space

  • Not so good

    • Text questions are prone to error data entry errors, and hard to interpret

  • Not supported

    • Images, multimedia

    • GPS

What are limitations for using SMS Surveys?

  • SMS Surveys require inbound messages. Support for inbound messages is limited to projects with a subscription that is PRO or higher.

  • SMS Surveys are not idea for collecting unstructured incoming messages

  • A contact cannot have more than one open survey at a time.

  • A contact cannot restart or overwrite submitted SMS surveys

How flexible is two way messaging?

  • Two way messaging with mobile workers requires a verification workflow to enable inbound messages, where each phone replies ‘123’ to establish the phone number in HQ.

How do you test that the SMS survey is setup correctly?

  • Try creating a Keyword, that can trigger the form used for the SMS survey.

How do I test the send time of an SMS Survey?

  • Timezones in HQ are set to UTC as a standard. Use the reminder calendar, to compare the time configured in the reminder to the planned delivery in the calendar.

SMS Survey Tutorial

Below is an SMS Survey Tutorial that walks you through the steps of setting up an SMS Survey!

Expand
titlePlease expand the below to see this tutorial!

This tutorial will describe how to setup an SMS survey for your project.  This builds on the application already developed in the Messaging Beginner Tutorial, so please complete that tutorial before continuing. We will add an SMS survey to that application that will check with the mother if she has visited the clinic.  

Panel
panelIconIdatlassian-info
panelIcon:info:
bgColor#EAE6FF

Learning Objectives for SMS Survey Tutorial

In this tutorial, you will learn the following:

  • Creating an SMS Survey in CommCareHQ

  • Sending an SMS Survey in a Reminder

Creating an SMS Survey

An SMS Survey is just another form in CommCareHQ.  You can have the same logic you have in forms (display logic, validation logic).  You can also use the survey to update cases as you can with regular CommCareHQ forms.  The only limitation on SMS surveys is that only some question types will work over SMS (text, label, numbers and single and multiple choice).  

Setup the SMS Application

We need to add a new application to the existing project created for the Messaging Beginner Tutorial.  This application will contain all the SMS surveys so they don't appear in the existing health worker application. 

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

Image Added

  1. Update the first module and set the name to Pregnancy Surveys.

Image Added

  1. And then set the case type to pregnancy.  This module will contain all surveys related to pregnant women.  

Image Added

Add the Clinic Attendance Survey

This tutorial assumes you already know how to create a form with hidden values.  

  1. Rename the Untitled Form to Clinic Attendance Survey and add questions so that it resembles the following. 

image-20240422-200452.pngImage Added

The following calculations and display logic is used in the form:

Question ID or Choice Value

Type

Label

Required

Display Logic

Calculation

attend_clinic

Single Answer

Did you attend the clinic today?

Yes

yes

Choice

Yes

no

Choice

No

visited_clinic_label

Label

Great! Speak to your health worker about the results.

/data/attend_clinic = 'yes'

no_visit

Label

Its important you visit the clinic. Please try visit next week. 

/data/attend_clinic = 'no'

send_clinic_visit_reminder

Hidden Value

if(/data/attend_clinic = 'yes', 'no', 'yes')

Panel
panelIconIdatlassian-info
panelIcon:info:
bgColor#EAE6FF

Concept

Its important to keep label text short! SMS messages are limited to 144 characters and longer messages can be split up into multiple messages. These messages are sometimes not delivered in the correct order, confusing users.

  1. Save the form and configure the case management for the form.  The form will be setup to update or close cases.  We'll only save send_clinic_visit_reminder.  This will then affect the reminders that are based on this case property.  

f308fad2-2a6d-4067-8de6-c62e69002c27.pngImage Added

Now that our survey is setup, we can setup a reminder to send it to pregnant mothers. 

Setup an SMS Survey Reminder

We'll now setup a reminder so that the survey will only be sent to mothers who have been flagged by the CHW as needing to visit the clinic. This messages will also be setup to repeat on a weekly basis until either the CHW or mother indicates she has visited the clinic.  We'll schedule the message to send on Tuesdays in the evening (so that the mother can respond after visiting the clinic).  

  1. Add another reminder to the project (go to the Messaging tab, then choose Reminders and then click on the + Reminder button).

  2. We'll now configure which pregnant mothers will receive this reminder.  Give the reminder a name (ex. Clinic Visit Check) then scroll to the Start Section. 

  • Send for Case Type: We want to choose pregnancy from this list as the message will be sent to pregnant mothers. 

  • Send Reminder For: This will control which cases receive the reminder. We want to choose Only Cases in the Following State. Then set the reminder to send when the case property send_clinic_visit_reminder equals yes.

  • Day of Reminder and Time of Reminder: This controls what day and time of day that the mother will begin to receive this reminder. Our clinic day occurs on Tuesdays. So we want to send the mother a reminder on Tuesday evening to check if she visited the clinic. For Day of Reminder choose Specific Day of the Week and Tuesday. This option will send the message on the next upcoming Tuesday after the pregnant mother is flagged for a clinic visit.  For Time of Day choose at a Specific Time and 18:00.

98f0e0f9-be6a-4d46-9b05-4ea6d24780b4.pngImage Added

  1. The next step is to choose who will receive the reminder.  We want this reminder to go to the health worker who registered the case (the case owner), so choose Case Owner.  

e041edc3-8c11-4621-964a-d7252ea9be2f.pngImage Added

  1. In the Message Content section, instead of sending an SMS Message, we want to send an SMS Survey,  We can now choose which form we want to send as the survey.  Use the dropdown to choose Clinic Attendance Survey.  

e7caa138-cadb-4934-a2ec-748bd63150d4.pngImage Added

  1. We will also configure to reminder to Repeat every week until the mother visits the clinic. Choose the Indefinitely option and specify that the reminder should repeat every 7 days.  Remember, the reminder will stop sending as soon as the Start condition becomes false (i.e. if send_clinic_visit_reminder is not equal to yes).

dcce7028-57bb-41ce-aefe-03b343949a3d.pngImage Added

  1. We can also look at and update some Advanced options for this reminder.

  • Stop Condition: This provides another way to stop the reminder.  Since we are just changing the start condition to stop the reminder, we can leave this as it is. 

  • Timeouts: With SMS Surveys, sometimes the user may not respond to a particular question.  We can use timeouts to re-send the question if the user does not respond after a certain amount of time.  We can specify a set of time intervals on which the survey will be sent out again.  The last number represents when we will close the survey (and stop allowing responses).  For example, specifying 30, 60, 120 will resend a question at 30 minutes and 60 minutes after initially sent, and close it at 120.  Set the timeout to 30, 60, 120. 

  • Submit Partial Forms: If a survey is partially filled out (user only responded to some of the questions), this controls whether we will save those partial answers.   For now, we can leave this off for this reminder. 

edb9ee9a-7b7e-4254-b4c0-74fd54b53a06.pngImage Added

  1. Our reminder is now setup so we can click on Create Reminder.

25165579-eb07-4f7d-b2fc-2f7e17363ab4.pngImage Added

We can now view the scheduled reminder in the calendar and test out how it works. 

Test and Verify the Survey

Now that our reminder is setup, we can test it using our phones and view it in the reminder calendar.  

Setup a Sample Case

Similar to how was done in the Messaging Beginner Tutorial, use the existing registered pregnancy or create a new pregnancy case and flag that case for high risk symptoms.  Please make sure the phone number you enter is unique - that is, it is not used by any other case or mobile worker in the system. 

Panel
panelIconIdatlassian-info
panelIcon:info:
bgColor#EAE6FF

Concept

Duplicate Phone Numbers: Each phone number used for two-way (SMS Survey or Keyword) communication must be unique within and across projects. This is because CommCareHQ uses the phone number to determine which case or mobile worker an incoming message is associated with. If your phone number is not unique, you won't be able to verify the phone number for a mobile worker (https://dimagi.atlassian.net/wiki/x/-yjKfw), and CommCareHQ won't send out any surveys for that case or mobile worker.

If a survey is not sent out due to a duplicate phone number, this will appear in the Reminders In Error report, which is in the Messaging tab.

View Surveys in the Reminder Calendar

Once you've registered a case, the reminder should appear in the Reminder Calendar (available in the Messaging tab). 

c02491c9-3e22-44bd-b28c-6a3d9f11942c.pngImage Added

Testing a Survey Using a Broadcast

Since reminders are scheduled in the future, its sometimes hard to test how they behave immediately after creating them.  To test a survey immediately after we create it, we can use a Broadcast, that will send that survey to a mobile worker.  The survey won't behave exactly as it should (it won't be associated with a case), but will still be testable. 

  1. First create a mobile worker (https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143954052/Messaging+Beginner+Tutorial#Setup-a-Mobile-Worker-for-Messaging) and make sure you verify the mobile worker's phone number.  This is necessary for two way surveys.  

  2. We now need to put the mobile worker in a Group  Go to the Users tab and choose Groups on the left pane.  Then type a group name (ex. Test Group), then click on the Create Button.

aea50226-4461-4cd3-87a0-f105c672bce1.pngImage Added

  1. Add you test mobile worker (the one with the verified phone number) to the group and click on Update.

d1249e4b-edac-4fcb-a8bf-ac09ad737c0e.pngImage Added

  1. Go to the Messaging tab and choose Broadcast Messages in the left pane.

  2. Click on + New Broadcast to create a new broadcast. 

0dcd2489-6203-414d-b7fd-8dad8334b261.pngImage Added

  1. Setup the broadcast to send to Test Group immediately as shown below.  Choose the Clinic Visit Check survey to be sent. 

31187fc7-0e52-4724-95b9-8cbca7130edc.pngImage Added

Your test mobile worker should now receive the survey shortly.  To respond to multiple choice questions, you can respond with a number (ex. 1) representing the answer in the list.  

Note: This survey won't affect any existing cases and is just a way to test the questions.  

If your survey is not sent out, check the Reminder Calendar.  If it doesn't appear on the reminder calendar, check the Reminder in Error report to see if there was an issue with the survey.  

Viewing Surveys in Reports

By default, surveys filled in by cases will not display in the Submit History report.  In the Groups and Users filter, click and make sure you also include [Unknown Users].  

f3b1524c-f770-4d5c-9278-f727f703fdce.pngImage Added

Congratulations, you've completed the SMS Survey tutorial!  Use the https://dimagi.atlassian.net/wiki/x/XCrKfw page to read more about messaging and other functionality.