Skip to content

CVA‐IM support

Jump to bottom
Sulaiman Mohammad edited this page Dec 11, 2024 · 151 revisions

Objective

The 121 product can benefit from CVA-IM support in several ways:

  • Support in implementations
    • Configuration of programs, users, Kobo-Connect, etc.
      • Feedback and improvement of Kobo forms
    • Give trainings / demos
  • Build "extra" functionalities (dev light)
    • EspoCRM-121 extension
    • ...
  • Use knowledge from CVA implementations to improve the 121 product

Way of working CVA-IM team

  • The CVA-IM team works in sprints of 2 weeks
    • Sprints of CVA-IM team and 121 team are synchronised (CVA-IM Tuesday and 121 Wednesday)
  • The board related to 121 tasks can be found here: CVA-IM board 121
    • The product owner of 121 is owner of the backlog

How to enter and configure 121

  • Some configurations of the 121 platform can be executed through the 121 Portal, for other configurations you need to use the 121 API endpoints
  • The "global" page with all 121 instances can be accessed through https://status.121.global/
    • Also a demo instance can be found here
  • Navigate to the instance you want to enter or modify
  • In order to:
    • Go to the Portal, click: Portal | vx (bottom right)
    • Go to the endpoints, click: 121-service | vx (top right)

121 API endpoints

How to use 121 API endpoint

  • NB: In order to be able to use the API endpoints, you should be logged in as an admin. You can do this by going to POST /api/users/login (see below) and use the credentials from Bitwarden.
  • Click on the API endpoint you want to use
  • Click on Try it out
  • Depending on type of endpoint, give input, eg:
    • Specific field that is asked for - might be required or not
    • Request body - an example is given already, which you can use to understand how the body should look like
  • Click on Execute
  • Review response

Different HTTP request methods

There are different methods, the ones used by 121 API endpoints are listed here:

  • GET - The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.
  • POST - The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
  • PATCH - The PATCH method applies partial modifications to a resource.
  • PUT - The PUT method replaces all current representations of the target resource with the request payload.
  • DELETE - The DELETE method deletes the specified resource.

Information from first Google hit

Highlight of 121 API endpoints

This part will highlight some API endpoints that have been used as CVA-IM support

Tips:

  • To get the id of the program, go to the program in the portal and check the url, eg: https://portal.demo.121.global/program/[id]/payment

financial-service-providers

  • GET /api/financial-service-providers - Get all Financial Service Providers

financial-service-providers/intersolve-voucher

  • GET /api/programs/{programId}/financial-service-providers/intersolve-voucher/instructions - Get Intersolve voucher instructions image - used by Twilio to include in Whatsapp message
  • POST /api/programs/{programId}/financial-service-providers/intersolve-voucher/instructions - Post Intersolve voucher instructions image

instance

  • POST /api/scripts/reset - Reset instance database
    • Explanation of seed scripts and other inputs

notifications

  • GET /api/notifications/{programId}/message-templates - Get all message templates per program
  • POST /api/notifications/{programId}/message-templates - Create message template
  • DELETE /api/notifications/{programId}/message-templates/{type} - Delete message template(s) by type and optionally language
  • PATCH /api/notifications/{programId}/message-templates/{type}/{language} - Update message template

programs

  • POST /api/programs - Create a program
    • Explanation of creation from Kobo
  • GET /api/programs/{programId} - Get program by id
  • DELETE /api/programs/{programId} - Delete program and all related data
  • PATCH /api/programs/{programId} - Update program
  • GET /api/programs/{programId}/fsp-configuration - Get all ProgramFspConfigurationEntity for a specific program
  • POST /api/programs/{programId}/fsp-configuration - Create ProgramFspConfigurationEntity for a program
  • PUT /api/programs/{programId}/fsp-configuration/{programFspConfigurationId} - Update ProgramFsPConfigurationEntity
  • POST /api/programs/{programId}/program-questions - Create program question
  • PATCH /api/programs/{programId}/program-questions/{programQuestionId} - Update program question
  • DELETE /api/programs/{programId}/program-questions/{programQuestionId} - Delete program question and related answers

programs/registrations

  • PATCH /api/programs/{programId}/registrations - Bulk update registrations using a CSV file

roles

  • GET /api/roles - Get all user roles
  • POST /api/roles - Create new user role
  • PUT /api/roles/{userRoleId} - Update existing user role
  • DELETE /api/roles/{userRoleId} - Delete existing user role

users

  • GET /api/programs/{programId}/users/search - Search for user based on username
  • POST /api/users - Sign up new user
  • DELETE /api/users/{userId} - Delete user by userId
  • POST /api/users/login - Log in existing user
  • PATCH /api/users/password - Reset user password without current password

Tips

  • Note that for PATCH endpoint you do not need to fill all the fields in the body, you can only give the input on the things you want to change
  • Some FSPs can be configured per program using the FSP configuration (only Excel?). For more information on how to use the API endpoint with Excel, read the documentation here: /~https://github.com/global-121/121-platform/wiki/Excel-payment-instructions-FSP

FAQ

Instances

  • Is an instance set up per client?
    • At the moment, there is an instance set up per client, but in the future the idea is to have all clients on one general instance

Set up of program

  • How do I create a new program?

    • Prepare Kobo form so that it is correctly set up

      • Make sure all fields that are going to be part of the program have a label (thus calculated fields as well! - incl. scope)
      • Make sure all mandatory questions are in the form, either calculated based on questions or 'static' / default for all registrations. The mandatory fields are: fspName, maxPayments and preferredLanguage. Also make sure the answers to these questions coincide with the options of these fields in 121.
        • The options for preferredLanguage are the ISO 2-letter language codes
        • The options for fspName can be obtained by using GET /api/financial-service-providers
      • Add "Program configuration" questions, like the attributes in the Overview page, and other meta data
        • Review the following template to see which program configurations are necessary: Template XLS Form (Last 21 rows in template)
        • There are fields that can contain comma separated values, namely: fullnameNamingConvention, language, financialServiceProviders - This is not working correctly yet, to review!
      • Add tags for questions
        1. that are FSP questions, so that these questions are not created again
        2. that the program team would like to deduplicate on
        • How:
          • If you work with XLS Form you should add a new column called hxl and in the rows of the specific questions put the following: #121+dedupe (for deduplication) or #121+fsp (for FSP question)
          • If you work with Kobo Builder you should go to the question, click on the Settings button and add the HXL tags as follows: image
        • NB: One field can only contain one of the two tags. If a field is a FSP question AND it should be a field used for deduplication, this can be done currently by updating the FSP question via the API endpoints, which means it's done on an instance level.
      • FSP questions should have the exact same internal name as in 121, OR the Kobo Connect headers should be changed later to the correct internal name used in 121
        • Each FSP has a standard set of questions (eg. for Visa we need street, postal code, etc. - for AH voucher we need phone number)
        • The FSP questions (and its internal names) related to a certain FSP can be obtained by using GET /api/financial-service-providers
      • Phone number should be called phoneNumber
        • Advise is to make phoneNumber a text field in Kobo, so that it can start with a 0
      • Phone number should be including country code
      • Tip: Review if the answers of dropdown fields could expand in the future (eg. for location), and define if it should be better to have this field as text in 121 (should be manually configured later) - Problem is that if in 121 a field is dropdown and the answer received is something that is not an option for that field, 121 does not accept it and the sending of the registration from Kobo to 121 fails (eg. the initial form has two options on location: Den Haag and Amsterdam, thus in 121 these two options are created for the location field. During registration, the team adds a new location: Utrecht - this option is not automatically added to 121 and thus the sending of these registrations from Kobo to 121 will fail! If the field is text in stead of dropdown, this is no issue)

    • Go to "Create program" in the menu

    • Set the Kobo Token and Kobo Asset ID

      • Kobo Token: Go to kobo.ifrc.org/token while being logged in as a user with access to the Kobo form (assuming the Kobo form is on the IFRC server)
      • Kobo Asset ID: Can be found in the URL of the Kobo form in the 'back-end' (kobo.ifrc.org/#/forms/[assetID]/summary)

    • If not there already, create a Kobo user for the instance

      • Use POST /api/users
      • Define username and displayName according to convention: kobo-user@<instance>.121.global (where "instance" is the name of the instance, eg. "training") and Kobo User

    • Add the Kobo user to the program team of the program that you just created. The role should be to only create registrations.

      • Go to the program that you just created through the Home page. Then click on Team in the program menu.
      • eg. image

    • Add the following headers to the REST Service in KOBO - kobo.ifrc.org/#/forms/[assetID]/settings/rest

      • url121 - eg. https://training.121.global
      • username121 - the email address of the kobo user added above, eg. kobo-user@training.121.global
      • password121
      • and if necessary programid
        • programid can either be a calculated field within the Kobo form or a static field in the headers. If the programid is not specified in the Kobo form, it should be specified in the headers - If it is both in the headers and in the Kobo form, it will take the programid from the header
        • programid can be found in the URL of the newly created program, eg: portal.training.121.global/program/[programid]/people-affected

    • Test if it works :)

  • Creation of program fails, what can I check?
    • No option of a dropdown question is set to NaN
      • Could happen when using xlsTo121 (option None -> NaN) - Interesting to check how this works with the "Create program" functionality
    • Admin role should be set up in the instance, although the admin user does not even has to have this role assigned
  • Kobo Connect does not work, what can I check?
    • select_one / dropdown questions in 121 cannot be empty, make sure they are posted (if necessary with a default answer, eg. No response)
    • phoneNumber should always be part of the payload
      • Although can be empty if allowEmptyPhoneNumber is set to true in the program set up
  • What are the distribution frequencies I can use?
    • Add answer
  • Program Questions
    • answerType must be one of the following values: numeric, dropdown, tel, text, date
    • questionType must be one of the following values: standard, custom

Configuration of program

  • Explanation of difference between FSP and program questions (and custom attributes? But will be removed?)
  • How do I add a field after set up of the program?
    • Use POST /api/programs/{programId}/program-questions
  • How do I edit a field after set up of the program?
    • Use PATCH /api/programs/{programId}/program-questions/{programQuestionId}
  • How do I delete a field after set up of the program?
    • Use DELETE /api/programs/{programId}/program-questions/{programQuestionId}
  • How do I set up deduplication?
    • In the JSON object of the questions of the program, there is a key called duplicateCheck, which has a value of either true or false
    • If the duplicateCheck of a question is set to true, this field will be taken into account when exporting the "duplicate report"
  • Can I do deduplication on first and last name?
    • At the moment you can choose the fields which should be taken into account for the duplicate report, where it will only deduplicate against that field itself
    • It is possible to include both first and last name in the duplicate report, but it will be treated as two separate fields
    • It is possible to, when importing the registrations (either via Kobo or manual) to concatenate the first and last name into one name field and use this field in the deduplication report, BUT unfortunately, when the first or last name gets updated in the 121 platform, the one field name will not be automatically updated and thus should also be manually updated to not show up in the deduplication report anymore - thus this option is not optimal
    • In short, there is no easy way yet to deduplicate on both first and last name if those are separate questions in the program set up
  • How do I embed a monitoring / PDM dashboard in 121?
    • Use the "evaluationDashboardUrl": "example.org" and/or "monitoringDashboardUrl": "example.org" fields in the program (one of the two is going to be removed in the future)
  • How do I set up inclusion scoring?
    • Inclusion scoring with dropdown questions is done as follows:
      • { "name": "illness", "label": { "en": "People with chronic illness" }, "answerType": "dropdown", "options": [ { "option": "yes", "label": { "en": "Yes" } }, { "option": "no", "label": { "en": "No" } } ], "scoring": { "no": 0, "yes": 1 } }
    • Inclusion scoring with numeric questions is done as follows:
      • This is how you could do it if you want to give PAs 2 points for every dragon they have to take care of { "name": "dragon", "label": { "en": "Dragon count", }, "answerType": "numeric", "scoring": { "multiplier": 2 } }
  • How do I customize the PA table?
    • Update the question that needs to be shown in the PA table, set showInPeopleAffectedTable to true

User management

  • How do I add a new user?
    • Use POST /api/users, with the email as username and generate a strong password
    • The user is created and can now be found in the portal under "Users" in the main menu
    • The user then needs to be added to the correct program
      • This can also be done by the program team itself (although the first user with these "user management" rights need to be added by admin)
      • Go to the program
      • Go to "Team" in the top left corner
      • Click on "Add team member"
      • Search for the team member and give the user the correct role and if necessary scope
  • How do I change the role of a user?
    • The role of a user is set in the portal per program (not on instance level)
      • You go to the program and click on "Team" in the top left
      • You search for the user you want to update and click on the three dots on the right, then "Edit"
      • The role can be changed, then click on "Save"
    • Also see documentation on Roles and Permissions
  • How do I remove a user?
    • A user can be removed from a program (by the program team) by going to Team, three dots and click "Remove from Team"
    • If a user is not assigned to any program, the user can log in but not see any data
    • A user can also be completely deleted, by using DELETE /api/users/{userId}
      • Get the id of the user to remove by using GET /api/users
    • At the moment it is not possible to set a user to "inactive"
  • How can I make the Transfer Value Multiplier editable?
    1. The user should have a role where the following is included:
    2. The transfer value multiplier is not a calculated field
      • Thus, in the program json the paymentAmountMultiplierFormula is as follows:
      • "paymentAmountMultiplierFormula": null
  • Random information:
    • The username is case sensitive

Messaging / Notifications

  • Messages can be modified with the "notifications" endpoints
  • There is a json object for every message, per type and language
  • Messages can be send automatically in the 121 platform, or linked to certain actions
    • This is set through the type of the message
    • The following message types are linked to the corresponding action:
Topic Type Explanation Should be Twilio approved Example
Generic messages whatsappGenericMessage Generic message approved by Twilio, so that we can send any other not approved message to the PA afterwards yes There is a message waiting for you. Please reply "yes" to this message to receive it. Kind regards, Red Cross
whatsappReply Message send when a phone number that's registered in 121 doesn't have anything waiting (so no messages or vouchers) and sends us a message yes This is an automated message. Be aware, you cannot reply to this message. Questions? Please call XXX. Kind regards, Red Cross
whatsapp-default-reply Message send when an unknown phone number sends us a message (only necessary to set up this message for language "en", as there's no possibility to check in which language this should be send) yes This is an automated message. Questions? Please contact XXX. Kind regards, Red Cross
Status change included Message (optionally) send during action of inclusion of PA no Dear {{fullName}}, we would like to inform you that you have been included in the CVA program of the Red Cross. Within a week, you will receive more information. You will receive {{maxPayments}} payments.\n\nQuestions? Please contact XXX.\nKind regards, Red Cross
paused Message (optionally) send during action of pausing of PA no Dear {{fullName}}, we have paused your weekly payments. Please contact XXX for more information.\nKind regards, Red Cross
Visa messages visaDebitCardCreated Message send after PAs first payment with Visa, thus the Visa card will be created no Hello, we have sent your Visa card by post. You will receive it within 2 weeks. Once you receive the Visa card:\n- Activate your card\n- After activating your card there will be €[[1]] on your Visa card.\n- Every week we will put money on your card. Be aware, only if your card is activated.\n\nQuestions? Please contact XXX\n\nKind regards, Red Cross
visaLoad Message send after Visa card has been loaded, thus a PA with FSP Visa received a payment and has already a card no Hello, we have put new money on your card: €[[1]]. Spend the money on the Visa card before the end of the month.\nBefore using the card, please check the balance here: XXX.\n\nQuestions? Please contact XXX\n\nKind regards,\nThe Red Cross
reissueVisaCard Message send after a Visa card has been reissued for a PA no Hello, you have indicated that you need a new Visa card. We have sent a new card to you. You will receive it within three weeks. Your old card has been blocked. The amount on that card will be available on your new card. This amount will be available after you activate the new Visa card. Kind regards, Red Cross
blockVisaCard Message send ater a Visa card has been blocked no Hello, your Visa card has been blocked. If you do not know why, please contact XXX. Kind regards, the Red Cross
unblockVisaCard Message send after a Visa card has been unblocked no Hello, your Visa card has been unblocked. You can use the card again. Questions? Contact XXX. Kind regards, the Red Cross
Albert Heijn messages whatsappPayment Message that the AH voucher is ready to be send, PA should respond with 'yes' to receive it yes Hello, we are ready to send you your Albert Heijn Voucher on Whatsapp. Answer 'yes' to this message to receive your voucher.\nKind regards, Red Cross
whatsappVoucher Message with the actual AH voucher no Hello, with this message you receive:\n- Your Albert Heijn Voucher (the image with the barcode)\n- Click XXX to see how to use your AH voucher\n\nThe grocery voucher is worth €[[amount]]. You can use the grocery voucher in all Albert Heijn supermarkets in the Netherlands and in Belgium. You can use the grocery voucher multiple times, as long as there is money left on it.\n\nQuestions? Please contact XXX\n\nKind regards, Red Cross
paymentInstructions Message send together with the message "whatsappVoucher", which only includes a PNG picture (Intersolve voucher instructions image), used to send payment instructions to the PA no image Important! This is not a message template that can be updated through the notifications API endpoint, but should be updated through the following one: /api/programs/{programId}/financial-service-providers/intersolve-voucher/instructions, where you can update the payment instructions picture that is sent to the PA
paymentReminder Message used only for AH Vouchers, a daily reminder for PAs who did not collect their vouchers yet. The reminder is sent for 3 days and then stops (as not to spam) no No example yet
  • Example of how message sending works when updating a status:
    • image
  • Changing a PA to these statuses does not have the option to send a message or send an automated message:
  • There is the possibility to add message templates with other "types", this could be handy if the program team wants to manually send a certain message multiple times (eg. over time). Then, this message can be implemented as a "templated" message in 121, that can be send manually.
    • The message can be send as follows:
      • Do the action "Send message to PAs", click on "Custom Message", the list of "templated" messages that can be send manually is shown
      • image
    • Make sure that isSendMessageTemplate is set to true (check below).
  • There is the possibility of adding placeholders to a message:
    • General placeholders (of fields in program) can only be used in messages send through status update or custom messages - so NOT in payment messages.
      • This should be done as follows: {{field}}, where field is the internal name of the field you would like to have as placeholder.
      • Review which placeholders you can use by starting to send a custom message to a PA and checking which fields can be added, there you can also review the internal name of that field
    • Placeholders of amount in payment messages should be done as follows:
      • for visaDebitCardCreated, visaLoad and jumboCardSent: [[1]]
      • for whatsappVoucher: [[amount]]
      • eg: The grocery voucher is worth €[[amount]].
  • Besides the type, language and message itself, the json object contains the following:
    • label: The label of the message template, which shows in the list of "templated messages" options when sending a message manually.
      • NB: If this label should be multiple languages (because the portal can be used in different languages), ALL message templates in the json with that type should have ALL languages in the label, regardless of the actual language of that message.
      • Eg: image
    • isWhatsappTemplate: If this is set to true, the message will be send immediately, without first sending the whatsappGenericMessage. Thus, this can only be done with messages that are actually approved by Twilio. NB: This is not working yet!
      • NB: Make sure that all messages with a type for which isWhatsappTemplate should be true (see table above) are actually approved by Twilio! Take this into account when updating message templates.
    • isSendMessageTemplate: If this is set to true, the message will show as an option in the list of "templated messages" when sending a message manually. See the picture above. It is possible to set this to true for messages with a type that is linked to a certain action in 121.
  • If a templated message is send to a person with a preferred language for which the template does not exist, the message will be send in English. If English does not exist, an empty message will be send.

Other

  • How can I inspect the form definition of my Kobo form?
    • Go to: kobo.ifrc.org/api/v2/assets/[assetID]
  • What is the Transfer Value Multiplier or Payment Amount Multiplier in 121?
    • For each program in 121 you set a "base" transfer value. A PA can have a transfer value multiplier, with which this "base" transfer value is multiplied to get the transfer value for that PA.
    • Example: The "base" transfer value is €100,- and a PA has a transfer value multiplier of 3 (eg. because the household size is 3), this means that the transfer value for this specific PA is €300,-.
  • How to set the calculation of the Payment Amount Multiplier?
    • 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.

Training exercises

Clone this wiki locally