Connect Kobo to anything.
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.
Using the kobo-to-espocrm
endpoint, it is possible to save a Kobo submission as one or more entities in EspoCRM.
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
).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.Endpoint URL
https://kobo-connect.azurewebsites.net/kobo-to-espocrm
Custom HTTP Headers
:
Name
add targeturl
with in the Value
the EspoCRM URL (for example, https://espocrminstancex.com).Name
add targetkey
with in the Value
the (newly) created API Key (from EspoCRM API User).Custom HTTP Header
that specifies which Kobo questions responds to which entity and field EspoCRM:
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).)..
), 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 aCustom HTTP Header
calledkobotoken
with your API token (see how to get one).
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.
multi.multiquestion1
: Entity.field1
repeat.
, followed by the repeating group name, followed by a dot (.
);.
);.
), followed by the field name in EspoCRM.repeat.repeatedgroup.0.repeatedquestion
: Entity.field1
repeat.repeatedgroup.1.repeatedquestion
: Entity.field2
calculate
called updaterecordby
in the Kobo form, which will contain the value of the field which you will use to identify the record;Custom HTTP Header
called updaterecordby
with the name of the field that you will use to identify the record.skipconnect
in the Kobo form;1
(based on some condition), the submission will not be sent to EspoCRM.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:
Endpoint URL
https://kobo-connect.azurewebsites.net/kobo-to-121
.Custom HTTP Header
that specifies to which entity and field it corresponds to.
Special Headers:
url121
is required and corresponds the url of the 121 instance (without trailing /
, so e.g. https://staging.121.global)username121
and password121
, corresponding to the 121 username and the 121 password respectively, must be included as well.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
programid
is not included as a question, it needs to be added to the header as a numberSee below for an example configuration, in which programId was not included as a question so it is included in the header.
skipconnect
in your Kobo form. If the field is set to 1
, the submission will not be send to 121.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 usernamekobopassword
: your Kobo passwordkoboassetId
: 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
)
See the docs.
cp example.env .env
pip install -r requirements.txt
uvicorn main:app --reload