KoboToolbox Integration

Background

“KoboToolbox is a suite of tools for field data collection for use in challenging environments. Our software is free and open source. Most of our users are people working in humanitarian crises, as well as aid professionals and researchers working in developing countries. Our teams of developers and researchers are based in Cambridge, MA and many other places around the world.””

Source: https://www.kobotoolbox.org

How KoboToolBox can be used with Corteza

One of the key features of KoboToolBox is the ability to create custom forms to suit your data collection needs. These forms can be accessed either Online or Offline allowing for their use in environments where internet connection is not possible.

Due to Corteza being a Web Based application an active internet connection is required to use Corteza. This allows Corteza to remain lightweight and usable on machines regardless of their processing power. This also means that Corteza may not be an adequate solution for use in the field.

This means that KoboToolBox and Corteza have synergistic properties where KoboToolBox can be used to collect the required data and once an internet connection is reestablished the data can easily be pushed to Corteza for  effective processing and management.

Understanding The Corteza Api Gateway

Due to the APi-Centric design of Corteza Corteza can connect to any provider using REST Protocols. This can easily be accomplished by using the Integration Gateway feature of Corteza.

The full documentation for the integration gateway can be found here: https://docs.cortezaproject.org/corteza-docs/2022.9/integrator-guide/compose-configuration/index.html

Creating an Endpoint

Here we can see the endpoint “/crm/leads” has been created. The full address of the endpoint is “https://latest.cortezaproject.org/api/gateway/crm/leads”. This will serve as the endpoint for the data to be sent to, we also select the “GET” method from the dropdown menu.

We also see the Prefiltering,Processing and Postfiltering options. Once the data payload has been created and sent to Corteza we then need to process the payload. This can be done by creating a Workflow in Corteza. More information on Workflows can be found here: https://docs.cortezaproject.org/corteza-docs/2022.9/developer-guide/corteza-server/workflows/

Sending a request in KoboToolbox

KoboToolbox allows for REST services to be activated directly from the settings menu. In this example we will use the settings in the image below. KoboToolbox will then trigger the requests and perform the service. More documentation on this topic can be found here: https://support.kobotoolbox.org/rest_services.html

By enabling the profiler in the Corteza integration gateway page we can see the status of the requests. By clicking on a request we can see more information such as the  request route, the header settings and the body of the request.

Processing the payload

Once the payload has been received by Corteza, the data may need to be processed into a specific record page and we can do this using Corteza’s Workflow Builder. An example of a workflow processing a payload can be found in the image below.

The output of this workflow will create a new record page containing the data found in the payload.