Collecting data using SMS or integrated voice response (IVR) interactions is sometimes easier, more efficient, or less expensive than sending a data collection team to the field. This feature allows you to collect data using RapidPro flows, which utilize SMS or IVR as its mode of data collection and push those submissions from the connected flow to a form in Ona. Once the data has been passed to Ona, you can use any of the data analysis or visualization tools on the data you collected. You can choose to use RapidPro flows, Enketo webforms, or ODK Collect to collect data and analyze all the data collected, regardless of the data collection mode, in one location utilizing all the data analysis and visualization tools the Ona platform has to offer.
This feature will utilize both a RapidPro flow and an XLSForm built using similar field names.
To use RapidPro for data collection, you need an account on a RapidPro instance. You can create an Ona-hosted RapidPro account on rapidpro.ona.io. Read this step-by-step guide to learn how to get started with RapidPro.
Creating flows
To collect data using RapidPro, you need to create flows. Flows allow you to define the SMS or IVR interactions and follow-up actions with your contacts. Responses received from the interactions are passed to an XLSForm connected to the flow. The form should then be uploaded to your Ona account.
To create a flow in your RapidPro account, click on the flow icon, then click on Create Flow on the left side of the flows page.
A flow starts with a command that allows you to perform some action. For example, an action may be to send a response message to a contact.
An action is usually followed by a response rule, which is a conditional statement that directs your contacts to the next step of the flow after evaluating the response entered. Variable names in the response rules should match their associated field names in your XLSForm, so data submitted on the RapidPro flow is submitted to the connected form. For example, if you have a field name respondent_age, then you should save your response rule result as respondent_age, instead of the default result for Wait for response.
Read the RapidPro documentation site for more information on how to create flows.
Passing submissions to a form
To pass submissions to your form on the Ona platform, you will be required to call a webhook at the end of your flow. To call a webhook, select the option Call a webhook under actions, then click Ok.
A webhook modal will pop up, where you need to provide the URL to which data should be submitted. Select POST, then enter the URL https://api.ona.io/[username]/[form-id]/submission. The form-id is the last number in the URL after loading a form on the Ona platform. For example, in the URL https://ona.io/dynamite/123567/764055, the form-id is 764055.
Then, click the HTTP Header to add additional configurations as shown below. You need to add Authorization as this is not present by default.
There is a string of characters after Token. This is your account’s API token for a personal account or the API token of an admin user of an organization account on Ona.
NOTE: Any time the API token is updated for this account, you will have to update it on the webhook HTTP Header page. If the API token is incorrect, the webhook post will fail.
To find the API token of an account, go to the account’s settings from the drop-down menu next to the account’s avatar (highlighted below in the red box), and select the API tab. You will be required to enter your password to access the API key.
The webhook allows you to configure RapidPro to send new submissions to your form. Each time a new submission is done, RapidPro will make a POST request to the URL you configured with the body of the POST containing the details of the submission pushing the RapidPro data to your XLSForm on the Ona platform.
Note: This feature has the following limitations:
- no retries in the event of failures
- no logs
- no status of failed or successful execution of the web service