Skip to content

Program Setup combined

Jump to bottom
Sulaiman Mohammad edited this page Aug 27, 2024 · 1 revision

Setting Up and Configuring a Program on the 121 Platform

This guide provides a comprehensive overview of the steps required to set up a program on the 121 Platform, including the preparation of Kobo forms, configuration of instance and program settings, and integration with Financial Service Providers (FSPs).

1. Preparing the Kobo Form

a. Ensure Proper Setup of Kobo Form

  • Label All Fields: Ensure all fields in the form have a label, including calculated fields. This is crucial for correct data mapping and processing in the 121 Platform.
  • Mandatory Fields: Ensure that the following mandatory questions are included and correctly configured:
    • fspName
    • maxPayments
    • preferredLanguage
  • Program Configuration Questions: Add specific program configuration questions, such as attributes needed for the Overview page and other metadata.

b. Review and Adjust Form Templates

  • Review the Template XLS Form (last 21 rows) to ensure all necessary program configurations are included.
  • Be aware that certain fields, like fullnameNamingConvention, language, and financialServiceProviders, can contain comma-separated values, though this functionality might need review and testing.

c. Add HXL Tags for Special Questions

  • FSP and Deduplication Tags: Add tags to questions that should be treated as FSP-related or deduplicated to avoid duplication and ensure correct processing.
    • For XLS Form: Add a new column called hxl and use the following tags:
      • #121+dedupe for deduplication.
      • #121+fsp for FSP questions.
    • For Kobo Builder: Go to the question, click on the Settings button, and add the HXL tags as mentioned above.
  • Important: A field can only contain one tag. If a field should be both an FSP question and used for deduplication, update the FSP question via API endpoints on an instance level.

d. Consistency of FSP Questions

  • Ensure FSP questions have the exact same internal name as in the 121 Platform, or adjust the Kobo Connect headers to match the internal names used in the platform.
  • Use GET /api/financial-service-providers to obtain the required internal names and question sets for each FSP.

e. Other Important Considerations

  • Phone Number Formatting: Ensure the phone number is labeled as phoneNumber and includes the country code.
  • Dropdown Questions: Make sure dropdown questions are not left empty, even if affected by skip logic. A default answer (e.g., "No response") should be provided and must align with the options in 121.

2. Setting Up a Program in the 121 Platform

a. Create a Program

  • Navigate to "Create program" in the menu.
  • Set Kobo Token and Asset ID:
    • Kobo Token: Obtain the token from kobo.ifrc.org/token while logged in.
    • Kobo Asset ID: Find the Asset ID in the URL of the Kobo form in the backend (e.g., kobo.ifrc.org/#/forms/[assetID]/summary).
  • If not already done, create a Kobo user for the instance using POST /api/financial-service-providers. Add this user to the program team.

b. Configure REST Service in Kobo

  • Add the following headers to the REST Service in Kobo:
    • url121: e.g., https://training.121.global
    • username121: The email address of the Kobo user (e.g., kobo-user@training.121.global).
    • password121: The password for the Kobo user.
    • programid: Add this if necessary.
  • Test the connection to ensure everything is working correctly.

3. Configuring the Instance and Program

a. Instance Configuration

  • Instance Name: Set the name of the instance.
  • Instance Display Name: The name as shown in the Portal.

b. Program Configuration

Main Configurations:

  • Validation: Enable or disable validation functionality.
  • Inclusion Criteria: Define a set of questions that determine eligibility for the program.
  • Custom Attributes: Track program-specific attributes not directly asked during registration.
  • Financial Service Providers: Configure FSPs, including required credentials and questions.
  • Enable Scope: Set scope restrictions for registrations and users.

Additional Configurations:

  • Distribution Duration: Set the number of payments during the program.
  • Transfer Value: Default transfer value per PA for each payment.
  • Payment Amount Multiplier Formula: Automatically calculate payment multipliers based on a formula.
  • Notification Number Format: Set the example format for phone numbers.
  • Distribution Frequency: Choose the interval for payments (week or month).
  • WhatsApp First: Optionally enable WhatsApp as the first notification method.
  • Maximum Payments: Set a limit on the number of payments a PA can receive.
  • Languages: Select languages for the program, with English being mandatory.
  • Dashboard URLs: Set URLs for monitoring and evaluation dashboards.

Non-functional Configurations:

  • Location, Title, NGO, Start/End Date, Currency: Set these fields for informational purposes only.
  • Fullname Naming Convention: Define how names should be displayed in exports.
  • About Program: Provide a detailed description of the program.

c. API Calls for Program Creation and Adjustment

  • Use the 121 Platform’s API to create, adjust, or reset programs. Detailed API instructions are provided within the platform documentation.

4. Troubleshooting

a. Common Issues During Program Creation

  • Dropdown Questions: Ensure no option is set to NaN.
  • Admin Role: Verify the admin role is correctly set up, even if not assigned.
  • Kobo Connect Issues: Ensure dropdown questions in 121 are never empty, and the phone number is included, even if empty.

b. Advanced Troubleshooting

  • Instance Admin Setup: Ensure that an instance admin is correctly configured.
  • API Response Codes: Always check API response codes (20x for success, 400 or 500 for errors).

5. Creating and Managing Program Content

a. Inclusion Criteria Setup

  • Define the name, label, answer type, options, scoring, persistence, export settings, and duplicate check for each criterion.

b. Message Templates

  • Set up notification message templates for automated communications via SMS or WhatsApp.

c. Adding Financial Service Providers

  • Configure FSPs with details like portal names, PA-app names, integration types, and notification settings.
  • Define specific questions for each FSP and manage program-specific settings for FSP integration.
Clone this wiki locally