Configuring an Instance and creating a Program - global-121/121-platform GitHub Wiki

This page contains a functional description of how to configure an Instance of the 121 Platform and create a Program.

An Instance refers to an "installation" of the 121 Platform software on a (virtual) Server. The idea is that an organization runs one Instance of the 121 Platform and can use that for all their Programs.

With installing an Instance comes the configuration of that Instance. And with creating a Program comes the configuration of that Program. Configuration of an Instance and creation of a Program are currently handled together by loading a so-called "seed script". A seed script is a text-based document that the 121 Platform reads to configure an Instance and create a Program. At the moment it is not possible for a Portal User to configure an Instance or create a Program. This has to be done by an Administrator (technical person) via an API Call.

This page contains functional descriptions of the configuration options of an Instance and the options when creating a Program. A User may create a document in plain language describing the desired options. An administrator then needs to manually transform this document into a seed script.

Currently only supports the configuration of the following properties:

1. Instance name
2. Instance display name (as shown in the Portal)

1. A program can be created by just providing titlePortal and currency.
2. Using this configuration, a program will be created with one programRegistrationAttribute named "fullName" configured as fullnameNamingConvention.
3. From there, you can edit the program with further configurations.

1. Program includes validation: can have value true or false, configuring if the Validation functionality is enabled for this Program. If enabled, then the tab in the Portal "Registration" becomes "Registration and Validation", and People Affected can get the status Validated.
2. Program Regisration Attributes: a collection of attributes that are related to a Person Affected. These attributes are often gathered during the registration of People Affected, this usually happens via a kobo form. They can later added/edited in the Portal if Aidworkers need to keep track of it an example of such an attribute is 'has the PA completed a milestone'. A (sub)set of these attributes are used in our integrations with FSPs (like a phonenumber to send people mobile money). See separate section below for the types and parameters that a program registration attribute can have.
3. FSPs configurations: a collection of the FSPs configurations that are available for this Program, including any configuration parameters the FSP needs. See separate section below for more details.
4. Enable 'scope': If enabled, than 'scope' can be set for both registrations and users of this program, whereby users with a certain scope, can and only see/edit registrations within their scope. See more on Registration-scope.

1. Distribution duration: the number of Payments that will be done during the Program. Can be updated during a program by admin-user if needed.
2. Transfer value: the default transfer value per PA for each Payment. Can be changed manually before each Payment.
3. Payment amount multiplier formula: A formula can be entered, such that the 'payment amount multiplier' is automatically calculated based on the answers to some program registration attributes. The format should be 'A + B _ attribute1 + C _ attribute2 (etc.)', e.g. '0 + 1 * householdSize'. If this formula is filled in, then any manual updating of this multiplier is disabled. If the formula-attribute is not used, then manual entry/updating of the multiplier is enabled and expected.
4. Notification-number example value: an example of the phone number format a Person Affected needs to input during registration, for receiving notifications via SMS. The example should include the country code.
5. Distribution frequency: the interval with which payments will be done in the Program, can be week or month. Used to calculate provisionary future payment dates.
6. Try WhatsApp first: if set to 'true', then invitation messages will be tried to WhatsApp first. If it fails, then it defaults to SMS. (NOTE: currently only set this to 'true' if the program has FSP 'Intersolve voucher WhatsApp' configured.)
7. Enable maximum payments: if set to 'true' then a maximum number of payments per Person Affected can be set. If the maximum is reached, then the PA automatically goes from status 'Included' to status 'Completed' and can no longer receive payments. When the maximum is increased, the PA can be set back to 'Included' again.
8. Languages: determines in which languages the program is available in the PA-app. IMPORTANT: English must always be one of the languages currently!
9. Monitoring Dashboard URL: optionally set a URL to a PowerBI Dashboard which will be shown in the 121 Portal Dashboard page of a program instead of the default metrics. The 121 Platform only allows URLs from domain: https://app.powerbi.com
10. Evaluation Dashboard url: optionally set a URL to a PowerBI Dashboard which will be shown in the 121 Portal Evaluation tab of a program. The 121 Platform only allows URLs from domain: https://app.powerbi.com

1. Location: the geographical location of the Program. Is only shown in the Dashboard and has no effect on any functionality.
2. Title: the title of the Program, as shown in the Portal.
3. NGO: The name of the NGO running the Program. Is only shown in the Dashboard and has no effect on any functionality.
4. Start date: start date of the program. Is only shown in the Dashboard and has no effect on any functionality.
5. End date: end date of the program. Is only shown in the Dashboard and has no effect on any functionality.
6. Currency: the currency in which the People Affected are paid out. Is only shown in the Dashboard and has no effect on any functionality.
7. Fullname Naming Convention: the names of the fields that make up the 'name' column in exports.
8. About program: description with details about the program.
9. Number of targeted registrations: is shown per program in the program-overview page of the portal.
10. Description: general description about program. Shown in programs overview in portal.

1. Navigate to <environment>/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>/docs/#/programs/ProgramController_create
6. An example of a program can be found in the 'Example Value' section of the 'Program' parameter.
7. Click 'Try it out'
8. Adjust all the settings to your liking (by consulting this page).
9. Click 'Execute'.

1. Navigate to '<environment>/portal/home', login and click on the program you want to edit. Remember the 'programId' of the program you want to edit in the url: <environment>/portal/program/<programId>/dashboard.
2. Navigate to <environment>/docs/#/user/UserController_login. Click 'Try it out'. Enter your username and password in the 'Request body' section. Click 'Execute'.
3. Navigate to <environment>/docs/#/programs/ProgramController_findOne Click 'Try out'. Set 'formatCreateProgramDto' to true. Set the programId parameter to the id of the program you want to copy. Press 'Execute' and copy the contents of the return.
4. Navigate to <environment>/docs/#/programs/ProgramController_create. Paste in the result from 'find one' in the 'request body' and adjust the program content according to your needs. Click 'Execute'.
5. Check what the response code is. If the response code is 20x the update was success. If it is 400 or 500 something went wrong and you have to update the 'request body'.
6. If you successfully created the new program, you have to delete your old program. Go to <environment>/docs/#/programs/ProgramController_delete. Insert the program id you found in step 1 as programId parameter and the 'Reset secret' as secret in the body of the request. Press execute.
7. Navigate back to <environment>/portal/home to see the result.
8. You can go to <environment>/docs/#/programs/ProgramController_delete.

A Program Registration Attribute can have the following parameters:

• Name: the named ID the Platform internally uses to refer to this attribute.
• Label: the label as the Aid Workers sees it in the portal. This is a collection of labels, one per language.
• Type: how an Aidworker can fill in this attribute, being: as text, numeric, date, radio buttons (single select) or a phone number.
• Is Required: a boolean indicating if the attribute is mandatory.
• Placeholder: the format in which the Aid Worker needs to fill in the attribute.
• Options: a collection of answering options, if the Type is radio buttons or checkboxes.
• Scoring: a collection of numerical scores attached to each of the answering options, intended for calculating an Inclusion Score (also called a Vulnerability Score). In case of 'checkboxes', scores for all selected options are summed.
• Program ID: the ID of the program this attribute belongs to.
• Export: a collection of export types for which this answer will be exported. This only works if the answer is Persistent.
• Pattern: a regex pattern that the answer must match.
• Duplicate Check: a boolean flag that determines whether the given field should be used for duplicate detection.
  • Duplicates will appear in the Duplicate Status column on the registrations table, and as a banner on the registration details page.
  • The duplicate detection uses case sensitive exact string matching. For this reason, good candidates for duplicate checking include phone numbers and bank account numbers, whilst full names (due to case sensitivity and spelling variations) are less suitable.
  • This should not be used on attributes that are likely to give false positive, such as house number or number of children.
• Show In People Affected Table: a boolean indicating if the attribute should be displayed in the People Affected table.
• Editable In Portal: a boolean indicating if the attribute should be editable in the edit pop-up/page.

You can specify notification message templates that the 121-Platform automatically sends via SMS or Whatsapp, for example after a Person Affected finished Registration or when a digital voucher is available, or to optionally use when performing bulk actions such as 'include' or 'invite'. Message templates must follow specific keys and are specified per language.

1. You can include one or more FSPs Configurations to a program
2. Per FSP Configuration:
   1. Label: as displayed in 121-portal.
   2. FSP name. You can retrieve the available Financial Service Provider Names via <environment>/api/fsps. This endpoint also contains the required program registration attributes (like phoneNumber) and configuration properties (like password) for each FSP
   3. FSP Configuration properties. There are also program-specific settings for the same FSP that is used in multiple programs. For example different login credentials need to be specified per program. This can be done within the 'financialServiceProviders.configuration' attribute of the program configuration file.
3. FSPs that you can add to a FSP Configuration have the following attributes:
   1. Integration type: 'api' or 'csv' (where the last one means that payment-instructions are exportable from the 121-portal and have to be uploaded into the FSP's portal separately. Afterwards - if configured - reconciliation data from the FSP can be imported back into the 121-portal for overview on the status of transactions.)
   2. Notify on transaction: determines whether or not to automatically send a notification to PA via SMS/WhatsApp after storing the transaction.
   3. List of attributes that are required for this FSP like: phone number or bank account. These attributes need to be matched to the ones you configure in your program. As in if you FSP requires the attribute bank account you also have to set it in your program.