Import Data From KoboToolbox

DevResults integrates fully with KoboToolbox, a popular mobile data collection platform. Respones to survey forms in KoboToolbox projects can be imported to DevResults as a data table.

In this article:

• Tips for designing your KoboToolbox survey
• Create a DevResults data table and import KoboToolbox data
• Refresh an existing DevResults data table with KoboToolbox data
• Set up automatic import of data from KoboToolbox to DevResults
• Edit information in a KoboToolbox-linked DevResults data table
• Data validation when importing data to DevResults from KoboToolbox

Tips for designing your KoboToolbox survey

Whether or not you've already created your KoboToolbox surveys, please reach out to us at help@devresults.com to chat about the design. We can provide you with an automatically-generated file that contains the multiple choice answers to your survey questions so that all you need to do is upload it to KoboToolbox and link it to your questions. This means that: 

1. It saves you time creating the survey.
2. Most importantly, this is the best way to make sure that what you import from KoboToolbox will match your indicator's geographic and demographic disaggregations in DevResults. Multiple choice answers in KoboToolbox must match your disaggregation categories in DevResults in order to be imported, and we have a simple way to ensure that they match, and to keep things synced as you change or expand your program information. 
3. If you're collecting new location information via KoboToolbox, we can help with a shortcut to add those new places to DevResults, which is also key to keeping things synced between the systems. 

Back to top

Create a DevResults data table and import KoboToolbox data

From any page on DevResults, go to Program Info > Data Tables.

Click (+) New Data Table, name the table, and select Import from KoboToolbox. Then click Next. 

You will now be prompted to enter information on the KoboToolbox form you would like to connect to.

You will need to enter the Server name (this is the prefix to your KoboToolbox URL, typically 'kf' for the global server or 'eu' for the European Union server), the Asset ID (the string of random characters and numbers from your KoboToolbox project URL), as well as your KoboToolbox email and password. Alternatively, you can use your personal API key from the KoboToolbox account security page instead of a username and password.  If you're unsure about any of these fields, please refer to KoboToolbox's documentation and then reach out to us at help@devresults.com.

Once you've entered this information, click Next.

You can now configure the titles and types of columns you want to import, de-select fields you don't want to import, and choose to either create the table and import data or create the table without importing data.

Click (+) Create Data Table to complete the import process.

Back to top

Refresh an existing DevResults data table with KoboToolbox data

DevResults offers a click-to-import option to pull data from KoboToolbox to DevResults. When new information has been collected on KoboToolbox, refresh the data table by clicking on the right-hand gear icon and clicking "Import from KoboToolbox."

DevResults does not store external passwords or API keys, so you will be prompted to enter your KoboToolbox password or API key once again. 

You will then be asked to review the new and updated rows of information before you can complete the import. Click Import data once you've reviewed the new information.

Back to top

Set up automatic import of data from KoboToolbox to DevResults

DevResults also offers a webhook-automated import option to pull data from KoboToolbox to DevResults. 

1. In DevResults, create an API key that will be used by KoboToolbox to log into DevResults. The key should belong to a permission group that has View & Edit permissions for the  Data Table Contributor role on all projects (assigned and unassigned); sometimes it makes sense to create a group just for the new API Key. Take note of the "API Key" field (you do not need the "API Secret" field).

2. In KoboToolbox, register a new REST service (webhook) for each table that you'd like to automatically update. 

• Give the service a name (perhaps with the same name as the relevant data table)
• Point the webhook at the relevant endpoint URL for each table. You can find the API endpoint at the bottom of the Design tab for each KoboToolbox-linked data table. The format for the API endpoint is: 

https://{site}.devresults.com/api/dynamictables/{dynamicTableID}/webhook

• For each webhook, add the API token you created above. Add a custom HTTP header named X-DevResultsApiToken and paste in the API key.

KoboToolbox will send error messages to the data table's diagnostics tab, but there may be more information available in the KoboToolbox app itself. If the data does not import as expected, please reach out to us at help@devresults.com and we will investigate.

Back to top

Edit information in a KoboToolbox-linked DevResults data table

You may add/import, edit, or delete data in a KoboToolbox-linked data table just as you would any other data table. You may also add, edit, delete, or reorder columns, though any changes you make will not automatically synchronize with KoboToolbox. 

Each row of KoboToolbox data in DevResults is associated with both a DevResults KeyValue and a KoboToolbox ExternalKeyValue. This ExternalKeyValue will let you identify the same row of data in DevResults and KoboToolbox. 

You can look up specific rows in KoboToolbox by clicking on the Data tab, and filtering the _id field for a particular ExternalKeyValue, then view or edit the matching record.

Back to top

Data validation when importing data to DevResults from KoboToolbox

Information imported from KoboToolbox must match the data type of the DevResults data table column it's being imported to.

Values imported to a: 

• date column must be a date. 
• yes/no column must be a 0/1, T/F, true/false
• numeric column must be a compatible value (e.g. whole number, decimal, percentage). 
• project column must match an existing DevResults project. 
• geography column must match an existing DevResults geography. 
• disaggregation column must match an existing DevResults disaggregation category. 

With click-to-import, data validation errors show in the import modal and must be resolved before data can be imported.

• The click-to-import process pulls only the survey responses that are new since the last time the click-to-import process was used.
• Anything previously imported that was then changed/deleted in DevResults will not be edited/overwritten/re-added in subsequent imports. 

With webhook-automated imports, data validation errors show in the diagnostics tab.

• Once validation errors are resolved, no action is needed to import the data, because KoboToolbox will periodically re-try any failed webhook pushes. Eventually the data will be imported successfully and the diagnostics tab will turn green. 
• Alternatively, you can use the click-to-import option to immediately refresh results. But note: The click-to-import option will try to import any new data since the last time the click-to-import option succeeded, not the last time a webhook-automated import succeeded. 
  • No duplicates will be created, because the system uses the external key value to identify rows. 
  • If rows were imported via webhook between click-to-import actions, then edited in DevResults, those rows would be overwritten to what's in KoboToolbox. 
  • If rows were imported via webhook between click-to-import actions, then deleted in DevResults, they would need to be deleted from KoboToolbox (because DevResults cannot update a deleted data table row).

Back to top

Didn't answer your question? Please email us at help@devresults.com.