Support multiple eligibility verifiers per agency

[thekaveman]

Date: March 2022
Deciders: @angela-tran @thekaveman

Background

Early thinking

To introduce Courtesy Card support, we outlined a wholesale refactor of the data model and the way in which the UI was composed in #253. After some early exploration in #230, #265, and #266 -- we have decided that this is not an appropriate scope of changes to be making and actually reduces some amount of flexibility we have with the current architecture.

What we actually need

A simple way to express the need to support Courtesy Cards (and similar programs) in terms of benefits technical architecture is to say: Transit agencies in Benefits need to support multiple Eligibility verifiers. A user, having chosen their Transit agency in Benefits, must be able to choose which of the agency's verifiers they would like to use.

Coming full circle

An early data model in benefits had this notion that a Transit agency may have one or more Eligibility verifiers. In #26, the data model was simplified so that each agency had only a single verifier. Now we need to go back and undo what #26 removed in some sense (not necessarily verbatim).

User stories

• Add MST Courtesy Card Option and Document Info #197
• Rider MST CC information successfully verified  #198
• Rider MST CC information not successfully verified  #207
• Link credit card for valid MST Courtesy Card #205

Tasks

• Model eligibility verification form field validation #208
• Make msgids and structure consistent in .po files #318
• Update TransitAgency model to ref many EligibilityVerifier #320
• Track EligibilityVerifier in user session #321
• Update EligiblityVerifier model to support custom text content #319
• Create VerifierSessionRequired middleware that expects a verifier to exist in session #323
• Update eligibility verification form to use dynamic data #324
• Add a new "start eligibility" view/URL #332
• Django form to capture user's EligibilityVerifier selection #322
• Refactor language files for multiple verifiers #338
• Eligibility index does not reset eligibility types #346
• Enhance form rendering: Radio button list #347
• Update main layout to show large image by default #362
• Write UI automation tests for multiple verifiers #339
• "Unverified" page should use translation fields on EligibilityVerifier #379

Selecting an Eligibility verifier

We need a new page where the user picks from the list of EligibilityVerifiers for the selected TransitAgency.

Decisions

• Rework the eligibility app index page to present this selection
• Django form is needed for this page to capture the choice
• Store selection in session like agency
• Edge case: If the agency only has one verifier, user could shortcut directly to the “Start eligibility” instructions page

Eligibility verification customizations

A few UI elements are now variable and must be configurable per TransitAgency:

Eligibility verification selection

The "discount option" labels, with (optional) extra description

Pre-form instructions page

The title, verification media item, and page blurb may all differ

Form page

The title, blurb, labels, and placeholders may all differ

Success page

No changes needed (page doesn't have anything that needs to be configurable per TransitAgency).

Failure page

The page content title and blurb need to be configurable per TransitAgency (see #319 (comment)).

Decisions

• Store each of these items as new fields (TextField) on the EligibilityVerifier model
• Store the msgid keys with database model, use to dereference message and translate at runtime
  • Since this is all user-facing text, needs internationalization support, want to leverage our existing .po files / pipeline
  • Want to clean up the msgid keys/hierarchy similar to what was started in [WIP] Refactor data model for more flexibility #230
• Handle form field validation as part of this by storing a regex pattern on the verifier for the sub field; update the common eligibility form to put a (generous) max length on the name field.
• Look at adding fields to EligibilityType and pursuing Refactor model to split eligibility from benefit #90 only if/when we need to override labels or messaging for different scenarios

Eligibility verification flow

The Eligibility Verification API spec defines the fields that are sent with each request, only two of which are user-supplied. This means the eligibility form and verification logic should more or less work the same for any verifier. If a user is verified, regardless of which verifier that got them there, they proceed into the same enrollment flow.

Decisions

• Update existing eligibility form to accept dynamic components: labels, placeholders, validation
• Update TransitAgency calculation of types to verify to consider only the selected verifier. See Refactor handling of eligibility types #89 for more context.
• Update the Eligibility API Client to take an additional parameter for the selected verifier.

[thekaveman]

The bulk of the work for the Courtesy Card integration in Benefits was completed, via the Task List above.

Some User Stories remain open, and will be fully addressed when the integration with a Courtesy Card verification server is complete.

This Epic is now closed.