kobo-connect

Connect Kobo to anything.

Description

Synopsis: a dockerized python API that sends Kobo submissions and their attachments to other API-enabled applications, changing field names if necessary. It is basically an extension of the KoboToolbox REST Services.

Details: see the docs.

EspoCRM

Using the kobo-to-espocrm endpoint, it is possible to save a Kobo submission as one or more entities in EspoCRM.

Basic setup

1. Define which questions in the Kobo form need to be saved in which entity and field in EspoCRM.
2. In EspoCRM,
   • Create a role (Administration>Roles), set Access to the target entity on enabled, with the permission on yes to Create (if you need to update records, also add Read and Edit).
   • Create an API user (Administration>API Users), give it a descriptive User Name, select the previously created role, make sure Is Active is checked and that Authentication Method is API Key. After saving, you will see a newly created API Key which is needed for the next step.
3. Register a new Kobo REST Service for the Kobo form of interest and give it a descriptive name.
4. Insert as Endpoint URL

https://kobo-connect.azurewebsites.net/kobo-to-espocrm

6. In Kobo REST Services, add under Custom HTTP Headers:
   • In Name add targeturl with in the Value the EspoCRM URL (for example, https://espocrminstancex.com).
   • In Name add targetkey with in the Value the (newly) created API Key (from EspoCRM API User).
7. For each question, add a Custom HTTP Header that specifies which Kobo questions responds to which entity and field EspoCRM:
   • The header Name (left) must correspond to the Kobo question name. (You can check the Kobo question name by going into edit mode of the form, open 'Settings' of the specific question and inspect the Data Column Name. Also, the Kobo question names can be found in the 'Data' table with previous submissions. This Kobo question name is different from the Kobo question label and can not contain spaces or symbols (except the underscore).).
   • The header value (right) must correspond to the EspoCRM entity name, followed by a dot (.), followed by the specific field name. Example: Contact.name. (EspoCRM name is different from the EspoCRM label, similar to the difference between Kobo question name and Kobo question label).

Important

If you need to send attachments (e.g. images) to EspoCRM, add a Custom HTTP Header called kobotoken with your API token (see how to get one).

Advanced setup: select many, repeat groups, etc.

• If you have a question of type Select Many (select_multiple) in Kobo and you want to save it in a field of type Multi-Enum in EspoCRM, add multi. before the Kobo question name in the header name.
  • Example header: multi.multiquestion1: Entity.field1
• If you have a repeating group of questions in Kobo:
  • you will need to save each repeated question in a different field in EspoCRM;
  • in the header name:
    • add repeat., followed by the repeating group name, followed by a dot (.);
    • then add a number to specify the number of the repeated question (starting from 0), followed by a dot (.);
    • then add the name of the repeated question after the number;
  • in the header value:
    • as before, use the entity name, followed by a dot (.), followed by the field name in EspoCRM.
  • Example headers:
    • repeat.repeatedgroup.0.repeatedquestion: Entity.field1
    • repeat.repeatedgroup.1.repeatedquestion: Entity.field2
  • Not all repeated questions need to be filled in nor saved to EspoCRM.
• If you need to update a pre-existing record:
  • add a question of type calculate called updaterecordby in the kobo form, which will contain the value of the field which you will use to identify the record;
  • add a Custom HTTP Header called updaterecordby with the name of the field that you will use to identify the record.

121

Using the kobo-to-121 endpoint, it is possible to save a Kobo submission as a Person Affected (PA) registration in the 121 Portal.

Step by step:

1. Define which questions in the Kobo form need to be saved in which field.
2. Create a new Kobo REST Service.
3. Insert as Endpoint URL https://kobo-connect.azurewebsites.net/kobo-to-121.
4. For each question, add a Custom HTTP Header that specifies to which entity and field it corresponds to.
   • The header name (left) must correspond to the Kobo column name (not label).
   • The header value (right) must correspond to the field name in 121.

Special Headers:

• The headers url121 is required and corresponds the url of the 121 instance (without trailing /, so e.g. https://staging.121.global)
• Headers username121 and password121, corresponding to the 121 username and the 121 password respectively, must be included as well.
• If programid is included as a (select one) question, the XML Value of the question in kobo needs to be the corresponding number in the 121 portal, the label can be something else, see below
• If programid is not included as a question, it needs to be added to the header as a number

See below for an example configuration, in which programId was not included as a question so it is included in the header.

Nota Bene

The 121 API is currently throttled at 3000 submissions per minute. If you expect to go over this limit, please reach out the the 121 platform team.

Create headers endpoint

If you need to map a lot of questions, creating the headers manually is cumbersome. The /create-kobo-headers endpoint automates this. It expects 4 query parameters:

• system: required, enum (options: 121, espocrm, generic)
• kobouser: your kobo username
• kobopassword: your kobo password
• koboassetId : the assed id of the survey (to be found in the url: https://kobonew.ifrc.org/#/forms/`ASSETID`/summary)

In the body you can pass all the headers you want to create as key value pairs, for example:

{
 "last_name": "lastName",
 "first_name": "firstName",
 "household_size": "hhSize"
}

This endpoint assumes the IFRC kobo server (https://kobonew.ifrc.org)

Generic endpoint

See the docs.

Run locally

cp example.env .env
pip install -r requirements.txt
uvicorn main:app --reload