Objective

The 121 product can benefit from support from the CVA-IM team in several key areas:

• Implementation Support:

  • Configuration: Assistance with configuring programs, users, Kobo-Connect, etc.
    • Provide feedback and suggest improvements for Kobo forms.
  • Training and Demos: Conduct training sessions and product demonstrations.

• Development of Additional Features:

  • Light Development: Contribute to developing additional features such as the EspoCRM-121 extension.

• Product Improvement:

  • Leverage knowledge from CVA implementations to enhance the 121 product.

Way of Working - CVA-IM Team

• Sprint Structure:

  • The CVA-IM team works in 2-week sprints.
  • The sprint schedules for the CVA-IM and 121 teams are synchronized (CVA-IM on Tuesday, 121 on Wednesday).

• Task Management:

  • Tasks related to 121 can be tracked on the CVA-IM board 121.
  • The 121 Product Owner is responsible for managing the backlog.

Entering and Configuring 121

• Platform Access and Configuration:

  • Most configurations can be performed through the 121 Portal, while others require using 121 API endpoints.
  • Access all 121 instances through the 121 Status Page, where you can also find a demo instance.

• Navigation:

  • Portal Access: Use the Portal | vx link at the bottom right.
  • API Endpoint Access: Use the 121-service | vx link at the top right.

121 API Endpoints

Using 121 API Endpoints

• Authentication:

  • Log in as an admin before using API endpoints. This can be done via the POST/api/users/login endpoint with credentials from Bitwarden.

• Execution Process:

1. Click on the desired API endpoint.
2. Select Try it out
3. Input required data fields as indicated, you may use the default input in the request body as an example.
4. Click Execute and review the response:
   • Response Codes:
   • Informational responses (100 – 199)
   • Successful responses (200 – 299)
   • Redirection messages (300 – 399)
   • Client error responses (400 – 499)
   • Server error responses (500 – 599)
   • Information from first Google hit
   • Response Body: Contains detailed information depending on the endpoint used.

HTTP Request Methods Used by 121 API Endpoints

• GET Retrieve data from a specified resource.
• POST Submit an entity to a specified resource, potentially altering the server's state.
• PATCH Apply partial modifications to a resource.
• PUT Replace all current representations of the target resource with the request payload.
• DELETE Remove the specified resource.

Highlight of Frequently Used 121 API Endpoints

FSPs

• GET/api/fsps Retrieve all FSPs.
• GET/api/programs/{programId}/fsps/intersolve-voucher/instructions Get Intersolve voucher instructions image for use in WhatsApp messages via Twilio.
• POST /api/programs/{programId}/fsps/intersolve-voucher/instructions Upload Intersolve voucher instructions image.

Instance Management

• POST /api/scripts/reset Reset the instance database. Details about seed scripts and other inputs to follow.

Notifications

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

Programs

• POST/api/programs Create a new program. Details on Kobo creation to follow.
• GET/api/programs/{programId} Retrieve program details by ID.
• DELETE/api/programs/{programId} Delete a program and all related data.
• PATCH/api/programs/{programId} Update program details.
• GET/api/programs/{programId}/fsp-configuration Retrieve all ProgramFspConfigurationEntity for a specific program.
• POST/api/programs/{programId}/fsp-configuration Create a ProgramFspConfigurationEntity for a program.
• PUT/api/programs/{programId}/fsp-configuration/{programFspConfigurationId} Update ProgramFspConfigurationEntity.
• POST/api/programs/{programId}/program-questions Create program questions.
• PATCH/api/programs/{programId}/program-questions/{programQuestionId} Update a program question.
• DELETE/api/programs/{programId}/program-questions/{programQuestionId} Delete a program question and associated answers.

Program Registrations

• PATCH/api/programs/{programId}/registrations Bulk update registrations via a CSV file.

Roles Management

• GET/api/roles Retrieve all user roles.
• POST/api/roles Create a new user role.
• PUT/api/roles/{userRoleId} Update an existing user role.
• DELETE/api/roles/{userRoleId} Delete a user role.

Users

• GET/api/programs/{programId}/users/search Search for a user based on their username.
• POST/api/users Register a new user.
• DELETE/api/users/{userId} Delete a user by their user ID.
• POST/api/users/login Log in an existing user.
• PATCH/api/users/password Reset a user password without needing the current password.

Additional Tips

• Patch Requests When using PATCH endpoints, you only need to provide input for the fields you want to change.
• FSP Configuration Some FSPs can be configured per program using the FSP configuration. For more details on using API endpoints with Excel, refer to the Excel Payment Instructions for FSP documentation.

Frequently Asked Questions (FAQ)

Instances

• Is an instance set up per client?
  • Currently, each client has a separate instance, but the goal is to consolidate all clients into a single, general instance in the future.

Program Setup

• How do I create a new program?

  • Prepare the Kobo form with proper configuration:

    • Ensure all fields that will be part of the program have labels, including calculated fields.
    • Include mandatory questions in the form (fspName, maxPayments, preferredLanguage), ensuring their answers align with 121 options.
    • Add "Program configuration" questions for program attributes and metadata, as outlined in the Template XLS Form.
    • Use HXL tags (#121+dedupe for deduplication, #121+fsp for FSP questions) to categorize questions.
      • Note: A field can only contain one tag. FSP questions that require deduplication must be updated via the API endpoints.

  • FSP questions should match the internal names in 121 or be modified via Kobo Connect headers.

  • Ensure phone numbers include the country code and follow the naming convention phoneNumber.

  • Dropdown questions should never be empty in 121; provide default values if necessary.

• Steps for Creating a Program:

  1. Go to "Create program" in the menu.
  2. Set the Kobo Token and Kobo Asset ID.
  3. If needed, create a Kobo user for the instance and add them to the program team.
  4. Add the necessary headers to the REST Service in Kobo settings.
  5. Test the setup.

• Troubleshooting Program Creation:

  • Ensure no dropdown question options are set to NaN.
  • Confirm that the admin role is set up in the instance.

• Kobo Connect Issues:

  • Dropdown questions in 121 must not be empty.
  • Ensure the phoneNumber field is included in the payload, even if empty.

Configuration of Programs

• Adding/Editing/Deleting Fields:

  • Add a field using POST /api/programs/{programId}/program-questions.
  • Edit a field using PATCH /api/programs/{programId}/program-questions/{programQuestionId}.
  • Delete a field using DELETE /api/programs/{programId}/program-questions/{programQuestionId}.

• Deduplication:

  • Set deduplication using the duplicateCheck key in the JSON object of the program's questions.

• Name Deduplication:

  • Currently, deduplication on both first and last names is not optimized. Combining names into one field is possible but requires manual updates.

• Embedding Dashboards:

  • Embed a monitoring/PDM dashboard using the evaluationDashboardUrl or monitoringDashboardUrl fields in the program setup.

• Intersolve Barcode Insertion:

  • Use the sendInvoice key with the appropriate boolean value to include the barcode in notifications.

Managing Registrations

• Manual Registration:
  • To register a person manually, use the POST /api/registrations or the registration web form.
• Bulk Registration:
  • For bulk registrations, use PATCH /api/programs/{programId}/registrations to upload a CSV file.

Roles Management

• User Roles Configuration:
  • Add, edit, or remove user roles using the respective API endpoints under Roles Management.
  • Ensure users have the correct roles assigned for their tasks.

Notifications and Communication

• Creating Message Templates:

  • Use the POST /api/notifications/{programId}/message-templates to create a new template.
  • To update or delete a template, use the corresponding PATCH or DELETE endpoints.

• Sending Notifications:

  • Use the POST /api/notifications/{programId}/messages endpoint to send a message to recipients.

Additional Resources

• Documentation: Refer to the 121 API documentation for more detailed information on available endpoints and their usage.
• Support: For further assistance, contact the CVA-IM team.

Version Control

This document is regularly updated to reflect changes in 121 API and best practices. Ensure to check for updates frequently.