Mobile App to Go.Data Integration

Mobile apps and survey tools are widely used by Go.Data implementers and other health initiatives for on-the-ground data collection, response, basic monitoring. Many of these tools are open-source and developed on similar frameworks (e.g., ODK, Kobo Toolbox, ONA, CommCare), so the available integration options are very similar.

use-case-4

Use Case: #4. As a MOH employee, I would like to integrate case data collected via my mobile survey tool so that I can monitor new case registrations in real-time and quickly follow up with new contacts.

Solution Overview

In this reference implementation, we integrated a COVID-19 data collection form configured on Kobo Toolbox with Go.Data to deliver real-time case registration as mobile data is captured. See diagram below for the data flow.

  • Kobo Toolbox is a free mobile data collection app with offline support that is widely used in humanitarian response contexts.
  • Here we leverage the free-tier OpenFn integration platform to automate the data integration flow & quickly map Kobo data elements to Go.Data. OpenFn offers open-source and hosted implementation options. Learn more in Explore OpenFn.

dataflow-4

Implementation Steps

–> Watch the solution setup

  1. Consider how to extract data from your mobile application (see Integrating Mobile Apps for an overview of common options). In this implementation we configured a REST Service on Kobo Toolbox (see technical instructions) to automatically forward new Kobo Toolbox form submissions collected via mobile to a specified endpoint–our demo OpenFn integration layer.

kobo-rest-service1 kobo-rest-service2

See sample JSON output of a Kobo form submission once forwarded via the REST Service:

"form": "covid19-registration",
  "body": {
    "Age_in_year": "32",
    "Covid_19_suspected_criteria/HF_visited": "no",
    "Sample_Classification": "n_id",
    "patient_address/teknaf_Camp": "camp_23",
    "Covid_19_suspected_criteria/Symptoms": "difficulty_breathing",
    "Patient_name": "Jane Doe",
    ...
  1. We then mapped relevant data elements from the Kobo Toolbox survey form to Go.Data Cases. See example mapping specification.

kobo-mapping

In this step, it was important to determine the unique identifier that could be used to look-up existing Case records in Go.Data to ensure no duplicates were created (see the Unique Identifiers section for more on this design topic).

  1. We then drafted an OpenFn integration script (or “job”) to automate the data integration mapping whenever a new Kobo form submission is forwarded to the OpenFn project inbox via the Kobo REST Service.

In L21 we perform an “upsert” operation to (1) check if the case record exists, and then (2) insert/update the record in Go.Data accorndingly.

We chose to check for existing Go.Data records using the visualId as we are also capturing the external caseId (e.g., C19-930020123) in Kobo Toolbox and can using this unique identifier for matching resources.

upsertCase( //checks for existing cases & then sends PUT/POST request to Go.Data API Cases endpoint
    '3b5554d7-2c19-41d0-b9af-475ad25a382b', // outbreakId in Go.Data
    'visualId', //caseId - shared unique identifier 
    { data } //data mappings
  )

Check out the job on the OpenFn.org demo project or explore the OpenFn Inbox to see other example JSON payloads received from Kobo Toolbox. openfn-4

→ See the full job script. This job leverages the language-godata API adaptor, which offers helper functions like upsertCase(...) for quicker integration setup.

Explore the Implementation

  1. Watch the video overview, and the solution setup demo. And see here for other interoperability videos.

  2. See the Explore OpenFn page to explore the jobs on the live reference project.

  3. Kobo Toolbox: Explore the demo Kobo project & survey form at https://kobo.humanitarianresponse.info/ & REST Service configured. Use the following login details: 
    username: godata_demo
password: Interoperability

  4. Job scripts: See the Github interoperability-jobs to explore the source code used to automate these flows. These leverage an open-source Go.Data API wrapper - the OpenFn adaptor language-godata.

  5. Solution Design Documentation: See this folder] for the data flow diagram & data element mapping specifications mentioend above and used to write the integration jobs.