Program Setup - global-121/121-platform GitHub Wiki

Program Setup Guide

1. Instances

Is an instance set up per client?

Yes, currently, each client has a dedicated instance. However, the plan is to migrate all clients to a single, general instance in the future.

2. Program Setup Process

2.1 Creating a New Program

  1. Prepare the Kobo Form:

    • Ensure all fields in the program have a label (including calculated fields and scope).
    • Include all mandatory questions, which must be either calculated from other questions or static defaults for all registrations:
      • fspName
      • maxPayments
      • preferredLanguage
    • The answers to these mandatory questions must align with the options available in 121.
    • Add "Program configuration" questions for attributes shown on the Overview page and other metadata.
      • Refer to this Template XLS Form (Last 21 rows) to see required program configurations.
      • Fields like fullnameNamingConvention, language, and financialServiceProviders can contain comma-separated values—this feature is still under review.

  2. Add Tags for Specific Questions:

    • FSP Questions: Prevent these questions from being recreated.

    • Deduplication Questions: Mark questions for deduplication.

    • How to Tag:

      • Using XLS Form: Add a hxl column and use the following tags:
        • #121+dedupe for deduplication
        • #121+fsp for FSP questions
      • Using Kobo Builder: Go to the question, click Settings, and add the HXL tags.

      image

    Note: A field can only have one tag. If a field is both an FSP question and for deduplication, update the FSP question via API endpoints on an instance level.

  3. Configure FSP Questions:

    • The internal names of FSP questions must match those in 121, or the Kobo Connect headers must be adjusted.
    • Each FSP has a standard set of questions. For example:
      • Visa: street, postal code, etc.
      • AH voucher: phone number
    • Obtain related FSP questions and internal names using GET /api/fsps.

  4. Phone Number Formatting:

    • The field name should be phoneNumber.
    • Include the country code in the phone number.

  5. Dropdown Questions in 121:

    • Dropdown questions cannot be empty, so ensure that a value is provided even if skip logic results in the question being empty.
    • The default answer option must also be in 121.

    Tip: If dropdown fields might expand in the future (e.g., location options), consider configuring these fields as text in 121. If a field is a dropdown and an unlisted option is selected, the registration will fail.

  6. Setting Up the Program in the Menu:

    • Go to "Create program" in the menu.
    • Set the Kobo Token and Kobo Asset ID:
      • Kobo Token: Obtain it from kobo.ifrc.org/token (requires login with a user that has access to the Kobo form).
      • Kobo Asset ID: Find this in the URL of the Kobo form in the 'back-end' (kobo.ifrc.org/#/forms/[assetID]/summary).

  7. Create a Kobo User for the Instance (if not already done):

    • Use POST /api/fsps.
    • Add this Kobo user to the program team with a role restricted to creating registrations.
      • Navigate to the program via the Home page, click Team in the program menu.
      • Example:
        image

  8. Add Required Headers to the REST Service in KOBO:

    • URL: https://kobo.ifrc.org/#/forms/**[assetID]**/settings/rest
    • Headers:
      • url121: e.g., https://training.121.global
      • username121: The email of the Kobo user, e.g., [email protected]
      • password121
      • programid (if necessary)

  9. Test the Setup:

    • Ensure everything is working as expected.

2.2 Troubleshooting

  • Program Creation Fails:

    • Ensure no dropdown options are set to NaN (especially when using xlsTo121).
    • The admin role must be set up in the instance, though the admin user does not need to have this role assigned.

  • Kobo Connect Issues:

    • Dropdown questions in 121 cannot be empty. Ensure a default answer is posted if necessary.
    • phoneNumber must always be included in the payload, though it can be empty if allowEmptyPhoneNumber is true.

3. Additional Information

  • Distribution Frequencies: (To be added)
  • Program Questions:
    • answerType must be one of the following: numeric, dropdown, tel, text, date.
    • questionType must be one of the following: standard, custom.