Skip to content

Latest commit

 

History

History
124 lines (79 loc) · 6.36 KB

kobotoolbox.md

File metadata and controls

124 lines (79 loc) · 6.36 KB
Raw

KoboToolbox

What is Kobo Toolbox?

  • Kobo Toolbox is a data collection tool specially designed for Humanitarian Work
  • It allows for creation of sophisticated forms
  • Kobo’s Android App can be used to collect data without internet
  • Sempo can automatically sync with Kobo, so no manual upload is required

How can Sempo integrate with Kobo Toolbox?

Sempo can integrate to use Kobo Toolbox for three forms:

  1. Beneficiary Enrollment This form will be used to add each beneficiary to Sempo.
  2. Vendor Enrollment This form will be used to add each vendor to Sempo.
  3. Vendor Know-Your-Customer This form will be used to add vendor identity information to Sempo. It is separate to the Vendor Enrollment form, because we may need to collect further information about the vendor. For example, if a vendor’s drivers license does not match their bank details. This means you can re-submit this form multiple times, as long as the Vendor Phone does not change.

Creating a Kobo form

You can create your Kobo Form using Kobo’s web interface. How Sempo treats a field depends on its category.

Required fields are fields that you MUST include in a form and must fill out in order for the data to be synced. The fields are not case sensitive, but they must match Sempo’s documentation. For example, for the required field “phone”, you CAN provide “Phone” but cannot provide “Phone number”. But, you can override this using XML, the ‘Data Column Name’ or some special features (more on this later)

Optional fields are fields that are not required, but treated specially by Sempo. For example if you provide a “location” such as “Port Vila”, sempo will try to find the GPS location for “Port Vila”. Like required fields, you must match name in the Sempo documentation.

Custom fields are any fields that are not required or optional. Sempo will save these fields as “Custom Attributes” for each user, allowing you to filter and group users according to this information. You can use any name you want for a custom field.

Required Fields

For Beneficiary and Vendor enrollment the required fields are:

  • “first_name”: The participant’s first name
  • “last_name”: The participant’s last name
  • One of:
    • “Phone”: The participant’s phone number (must be a valid phone number)
    • “public_serial_number”: The ID of the Touch-to-pay card that is being given to the participant (use the Barcode/QR Code type)

{% hint style="warning" %} Make sure to include the underscores in the field names! {% endhint %}

For Vendor KYC the required fields are:

  • “Phone”: The same phone number provided in the sign up form
  • “Photo ID”: A photo of the Vendor’s Identity Card (Drivers License etc)
  • “Selfie”: A photo of the Vendor, holding up their Photo ID
  • “Supporting ID”: A photo of a supporting Identity Document such a bank statement IF the vendor is accepting more than 5,000 AUD a week (https://docs.withsempo.com/policies-and-security/faqs#what-are-sempo-account-limits)

There are many optional fields. The fields that might be useful are:

  • “is_vendor”: (Checkbox only) - whether the participant is a Vendor or Beneficiary. Defaults to “false” if not provided.
  • “location”: The text address or town of the participant, for example “Pango”
  • “gps_location”: The GPS coordinates of the participant, provided using Kobo’s “Point” field.

Linking a form to Sempo

Step 1 - Get your Kobo Credentials:

  1. Go to your Sempo deployment (app.withsempo.com)
  2. Click ‘Settings’ on the side bar.
  3. Find the box titled ‘Integration URL’.
  4. Ensure the "Preproces Inputs", and "Return Raw on Error" boxes are checked.
  5. Copy the integration URL from the textbox.

Allow Modifications

The Kobo integration can be configured to allow modifications to existing users. If you submit a form that has the same Phone or Card ID as an existing user, it’ll update the existing user’s settings. This is useful for providing more KYC information at a later date

{% hint style="warning" %} WARNING: This setting should only be turned on when it’s needed, as it makes it easier to accidentally use the same Touch-to-pay card twice on two different users. {% endhint %}

To turn this setting on, ensure "Allow User Updates" is checked in step 4, in addition to the other required fields.

Settings Page

Step 2 - Connect your Form

  1. Make sure your form is deployed on KoboToolbox.
  2. In the form you would like to connect, go to ‘Settings’.
  3. Next, go to ‘REST Services’
  4. Click ‘Register a new service’

  1. Complete the following fields:
  2. Name: Sempo
  3. Endpoint URL: URL Copied from Step 1
  4. Ensure ‘Enabled’ is CHECKED
  5. Type: JSON
  6. Security: No Authorization
  7. Scroll down and click ‘Create’
  8. You have now connected your KoboToolbox form to Sempo!

Advanced Kobo Integration Features

Default Values

We now support Default values on a per-form level. This means that unlike last time, enrollers don’t need to select “is vendor”: “true” every time they sign up a person:

To add a default value, add a custom wrapper, for example {"_data": %SUBMISSION%, "is_vendor": true} at the bottom of the “Add Rest Service” section.

You can add anything you want as a default value. Don't forget that you always need to include "_data": %SUBMISSION%!

Field name overrides

Any field name can be overriden on a case-by-case basis. This is useful for supporting groups, which add the group name to every field

For example if the group was “Identity Information” and the Field was “Phone”, Kobo will submit this as

“Indentity_Information_Phone”

This can be manually updated on Sempo to be recognised as just “Phone”.

{% hint style="info" %} For now, this needs to be done by a Sempo team member. {% endhint %}