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. 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. Inclusion criteria: a collection of questions that a Person Affected needs to answer during Registration. Some people refer to Inclusion criteria as a Vulnerability Assessment or Program Questions. A Program can have any number of criteria. See separate section below for the types and parameters that a criterium can have.
3. Other Person Affected custom attributes: these are not attributes that are asked to the Person Affected in the PA-app, but are program-specific attributes to keep track of. This can be something that is known in advance, like 'which local partner organization the Person Affected is with', or it can be something to keep track off later, like 'has the PA completed a milestone'. It's possible to configure these attributes to be shown in the table in the Portal by setting the 'phases' property.
4. Financial Service Providers: a collection of the Financial Service Providers that are available for this Program, including any configuration parameters the FSP needs. See separate section below for more details.
5. 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 questions. The format should be 'A + B * question1 + C * question2 (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 PAs: 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>/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. 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>/121-service/docs/#/user/UserController_login. Click 'Try it out'. Enter your username and password in the 'Request body' section. Click 'Execute'.
3. Navigate to <environment>/121-service/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>/121-service/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>/121-service/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.

An Inclusion Criterium (also called Program Question or Vulnerability Assessment Question) can have the following parameters:

• Name: the named ID the Platform internally uses to refer to this criterium
• Label: the question as the Person Affected sees it during Registration. This is a collection of labels, one per language.
• Answer Type: how a Person Affected can answer this criterium, being: as text, numeric, date, radio buttons (single select) or checkboxes (multi select) or a phone number.
• Placeholder: the format in which the Person Affected needs to answer the question, the Person Affected sees the Placeholder before answering.
• Options: a collection of answering options, if the Answer 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.
• Persistence: yes or no, indicated if the answer will be saved after validation. To protect privacy the Platform deletes all non-persistent answers after Validation is completed and final Inclusion Score calculated.
• Export: a collection of export types for which this answer will be exported. This only works if the answer is Persistent.
• Phases: a collection of phase names for which this question should be shown in the table.
• EditableInPortal: a boolean (true/false) whether the question should be editable in the edit pop-up/page.
• ShortLabel: A shorter summary of the question. This short version of the question will be displayed in the portal.
• Duplicate check: yes or no, indicates if the data in the answers to this question are included in the check for duplicates.

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 Financial Service Providers
   1. Except that maximum 1 manual (non-api) FSP is allowed within 1 payment round.
2. Per Financial Service Provider:
   1. FSP portal name: as displayed in 121-portal.
   2. FSP PA-app name: as displayed in PA-app (where PA chooses this FSP)
   3. Integration type: 'api' or 'csv' or 'xml' (where the last 2 mean 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.)
   4. Notify on transaction: determines whether or not to automatically send a notification to PA via SMS/WhatsApp after storing the transaction.
   5. List of questions.
3. Per question:
   1. Question label: as displayed in PA-app
   2. Placeholder value:
   3. Answertype: Determines for example validation on input (e.g. "telephone" type checks if phone-number exists). Same options possible as for 'Inclusion Criteria'
   4. Options: Create options in case of multiple-choice or multi-select question (answertype="dropdown"/"multi-select")
   5. Phases: a collection of phase names for which this question should be shown in the table.
   6. ShortLabel: A shorter summary of the question. This short version of the question will be displayed in the portal.
4. Per program per financial service provider: 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.