Skip to content

Program Setup combined2 with more details

Jump to bottom
tijsziere edited this page Dec 18, 2024 · 2 revisions

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. Overview

What is an Instance?

An Instance refers to an "installation" of the 121 Platform software on a (virtual) Server. Organizations typically run one Instance of the 121 Platform for all their programs. The setup of an Instance involves configuring the Instance itself and creating Programs. Both processes are managed by loading a "seed script" — a text-based document that the 121 Platform reads to configure an Instance and create a Program. Currently, only an Administrator (technical person) can perform these configurations via an API Call; this functionality is not available through the user Portal.

This guide covers the configuration options for an Instance and the options available when creating a Program.

2. 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.

3. 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.

4. 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:

  1. Program Includes Validation: Determines if the Validation functionality is enabled. If true, the "Registration" tab in the Portal changes to "Registration and Validation," and People Affected (PA) can attain the status of "Validated."
  2. Inclusion Criteria: A collection of questions that a PA must answer during Registration. These criteria, also known as Vulnerability Assessments or Program Questions, determine eligibility for the program. Each criterion can be customized with parameters like scoring and persistence.
  3. Other PA Custom Attributes: These are program-specific attributes not directly asked during registration but used to track specific details, such as the local partner organization of a PA or whether a milestone has been completed.
  4. Financial Service Providers: A list of FSPs available for the Program, including configuration parameters each FSP requires. Details on configuring FSPs are provided in a separate section below.
  5. Enable 'Scope': If enabled, scope restrictions can be applied to both registrations and users, allowing users with a specific scope to view and edit only the registrations within their assigned scope.

Additional Configurations:

  1. Distribution Duration: The number of payments to be made during the program. This can be updated by an admin-user if needed.
  2. Transfer Value: The default transfer value per PA for each payment, which can be manually adjusted before each payment.
  3. Payment Amount Multiplier Formula: A formula to automatically calculate the payment multiplier based on answers to certain questions (e.g., 0 + 1 * householdSize). If this formula is set, manual updating of the multiplier is disabled.
  4. Notification Number Format: An example of the phone number format a PA needs to input during registration, including the country code, for receiving notifications via SMS.
  5. Distribution Frequency: The interval at which payments are made (weekly or monthly), used to calculate provisional future payment dates.
  6. Try WhatsApp First: If enabled, invitation messages will first be sent via WhatsApp, defaulting to SMS if WhatsApp fails. This should only be enabled if the program has the FSP "Intersolve voucher WhatsApp" configured.
  7. Enable Maximum Payments: If true, sets a limit on the number of payments a PA can receive. Once the maximum is reached, the PA’s status changes from "Included" to "Completed," and they can no longer receive payments. If the maximum is increased, the PA can be reset to "Included."
  8. Languages: Determines the languages in which the program is available in the PA-app. English must always be included.
  9. Monitoring Dashboard URL: Optionally, set a URL to a PowerBI Dashboard to be shown on the 121 Portal Dashboard page instead of the default metrics. Only URLs from https://app.powerbi.com are allowed.
  10. Evaluation Dashboard URL: Optionally, set a URL to a PowerBI Dashboard for the Evaluation tab. Only URLs from https://app.powerbi.com are allowed.

Non-functional Configurations:

  1. Location: The geographical location of the program, displayed in the Dashboard but with no impact on functionality.
  2. Title: The title of the Program, as displayed in the Portal.
  3. NGO: The name of the NGO running the Program, shown in the Dashboard without affecting functionality.
  4. Start/End Date: The start and end dates of the program, displayed in the Dashboard without affecting functionality.
  5. Currency: The currency in which PAs are paid, displayed in the Dashboard without affecting functionality (Use ISO 4217, as per this list)
  6. Fullname Naming Convention: Defines how names should be displayed in exports.
  7. About Program: A detailed description of the program.
  8. Number of Targeted PAs: Shown per program in the program overview page of the portal.
  9. Description: A general description of the program, shown in the program overview in the portal.

c. API Calls for Program Creation and Adjustment

Creating a Program:

  1. Navigate to <environment>/121-service/docs/#/user/UserController_login.
  2. Click 'Try it out'.
  3. Enter your username and password in the 'Request body' section.
  4. Click 'Execute'.
  5. Navigate to <environment>/121-service/docs/#/programs/ProgramController_create.
  6. Review the example provided in the 'Example Value' section of the 'Program' parameter.
  7. Click 'Try it out'.
  8. Adjust all settings according to your requirements (consult this guide as needed).
  9. Click 'Execute'.

Adjusting and Resetting a Program:

  1. Navigate to <environment>/portal/home, log in, and select the program you want to edit. Note the 'programId' from the URL: <environment>/portal/program/**<programId>**/dashboard.
  2. Navigate to <environment>/121-service/docs/#/user/UserController_login.
  3. Click 'Try it out'.
  4. Enter your username and password in the 'Request body' section and click 'Execute'.
  5. Navigate to <environment>/121-service/docs/#/programs/ProgramController_findOne.
  6. Click 'Try it out', set 'formatCreateProgramDto' to true, and enter the 'programId' of the program you want to copy. Click 'Execute' and copy the returned content.
  7. Navigate to <environment>/121-service/docs/#/programs/ProgramController_create.
  8. Paste the copied result into the 'Request body' and adjust the program content as needed. Click 'Execute'.
  9. Verify the response code; if it's 20x, the update was successful. If it's 400 or 500, check the 'Request body' and try again.
  10. If the new program is created successfully, delete the old one by navigating to <environment>/121-service/docs/#/programs/ProgramController_delete, entering the 'programId' and 'Reset secret', and pressing 'Execute'.
  11. Check the result by navigating back to <environment>/portal/home.

5. Inclusion Criteria Configuration

a. Define Inclusion Criteria

  • Name: The internal ID the Platform uses to refer to this criterium.
  • Label: The question as it appears to the PA during Registration, in multiple languages.
  • Answer Type: The type of response expected (e.g., text, numeric, date, radio buttons, checkboxes, or phone number).
  • Placeholder: The format in which the PA must answer the question.
  • Options: Answer options, if the Answer Type is radio buttons or checkboxes.
  • Scoring: Numerical scores attached to each answer option, used to calculate an Inclusion Score (or Vulnerability Score).
  • Persistence: Indicates if the answer will be saved after validation. Non-persistent answers are deleted after validation to protect privacy.
  • Export: Specifies export types for persistent answers.
  • EditableInPortal: Determines whether the question should be editable in the portal.
  • ShortLabel: A brief summary of the question, displayed in the portal.
  • Duplicate Check: Indicates if the answer is included in the duplicate check.

6. Message Templates Configuration

a. Define Message Templates

  • Notification Templates: Specify templates for messages automatically sent via SMS or WhatsApp, for example, after a PA completes registration or when a digital voucher becomes available. Message templates must adhere to specific keys and be specified per language.

7. Adding Financial Service Providers

a. Add FSPs to the Program

  1. You can include one or more FSPs, with a maximum of one manual (non-API) FSP allowed within a single payment round.
  2. Configure each FSP with the following details:
    • FSP Portal Name: Displayed in the 121 Portal.
    • FSP PA-app Name: Displayed in the PA-app (where the PA chooses this FSP).
    • Integration Type: 'API', 'CSV', or 'XML' (where CSV and XML mean that payment instructions are exportable from the 121 Portal and must be uploaded into the FSP's portal separately; reconciliation data can be imported back into the 121 Portal if configured).
    • Notify on Transaction: Determines whether to automatically send a notification to the PA via SMS/WhatsApp after storing the transaction.
    • List of Questions: Configure questions for each FSP.
  3. For each question, provide:
    • Question Label: Displayed in the PA-app.
    • Placeholder Value: The placeholder text for the question.
    • Answer Type: Determines validation on input (e.g., "telephone" checks if a phone number exists). The same options are available as for Inclusion Criteria.
    • Options: Options for multiple-choice or multi-select questions.
    • ShortLabel: A brief summary of the question, displayed in the portal.
  4. For each program per FSP, configure program-specific settings (e.g., login credentials) within the 'financialServiceProviders.configuration' attribute of the program configuration file.
Clone this wiki locally