Update Facility Locator to allow plain language search for VA health services via Lighthouse V1 (Phase 3)

[xiongjaneg]

User story

As a Veteran, I want to be able to search for a VA service provided at my closest VA location so that I can choose the facility which meets my needs. As a Veteran, I want the search results to accurately reflect the services available at the facilities returned.

Background

In Phase 1, we updated Vets-API to point to Lighthouse v1 to unblock teams dependent on this functionality (#15344). In Phase 2, we converted the Facility Locator to use Facility API v1 with existing functionality (#12907). This work will update Facility Locator search by service for all of the ~90 services we can receive from Lighthouse v1.

Current behavior

The current search experience allows Veterans to search for 19 VA health services by selecting "All" or a specific service from a dropdown. The Facility Locator then queries Lighthouse to get the facilities associated with the specified service as defined by a legacy data source. This data source has not been entirely accurate for some time and is no longer maintained given the launch of Lighthouse Facilities V1 in August 2023.

VA health search screenshot for reference


Desired behavior

We can now implement Lighthouse v1 and provide a list of possible VA health, benefit, and Vet Center services which is complete, accurate, and can leverage the taxonomy data for plain language and other keywords.

MVP for this effort is VA health services (+ Vet Centers, as a stretch)

For example:

• VA service taxonomy: Optometry
• VAMC Patient-friendly Name: Vision care, corrective lenses and eyeglasses (currently formatted as a comma-separated string, ticket submitted to change this to an array, consider additional work for front end depending on either of these formats)
• VAMC Description: Our optometrists offer you routine eye exams, preventive vision testing and treatment for conditions like glaucoma. We also provide prescriptions for eyeglasses and other assistive devices.
• VAMC Common Conditions: vision exams, prescription eyeglasses, contact lenses (similar to patient-friendly name)

Veterans can enter keywords such as "optometry", "vision", "eyeglasses", "eye exam", "glaucoma", and "eye" to search for facilities with Optometry services.

Figma designs

Approach

SPIKE results: https://github.com/department-of-veterans-affairs/va.gov-cms/issues/15054#issuecomment-1743766937

The plan for this search has been to

1. publish a static Json from CMS which contains the fields/details/keywords from the taxonomy which is made available on page load and refreshed during content publishing cycle
2. based on the words entered/selected by the Veteran, a parameter ID is used to query Lighthouse for facilities with that requested service

ACs (draft)

• [ ] When Facility type = VA health, a Veteran can enter search parameters using plain language terms
• [ ] Search functionality for all other types of facilities is maintained
• [ ] Veterans (including those using screen readers, screen magnification, or keyboard navigation)
  • [ ] are aware of the type of search used by the field
  • [ ] are aware of the option to search for all VA health services
  • [ ] are aware of the option to search using a popular search suggestion
  • [ ] can select the option to search for all VA health services or one of the popular service suggestions
  • [ ] are aware of services which match the Veteran's search term
  • [ ] can select a matching service to search
  • [ ] are presented with an appropriate error message if the search terms do not match keywords in the service taxonomy
• [ ] When reached by keyboard navigation, the list of popular service suggestions and matching search terms receives focus
• [ ] Search results are presented with a header which includes the search parameters and other existing behavior
• [ ] Search parameters remain visible after search results are displayed
• [ ] ( may require design) Error messages / intended behavior are verified for
  • [ ] situations in which the search terms do not match keywords in the service taxonomy --
  • [ ] situations in which no results are found for the specified service and location -- examples: only 12 locations offer Bariatric surgery, 3 locations offer Genomic medicine, and 6 offer Hospital medicine
• [ ] Review and sign-off by Design, A11y, PM, and PO

  
  ### Tasks

• [ ] https://github.com/department-of-veterans-affairs/va.gov-cms/issues/18909
• [ ] https://github.com/department-of-veterans-affairs/va.gov-cms/issues/18910
• [ ] https://github.com/department-of-veterans-affairs/va.gov-cms/issues/18911

[xiongjaneg]

Additional tickets may be created during refinement of this ticket.

Per Michelle in Slack: "this work is the major set of changes we need to break down"

[xiongjaneg]

We currently have about 19 services that can be searched. Lighthouse v1 can provide many more.

The new search is a plain language search.

KISS file could be queried (ask Steve).

What's the data source? The taxonomy from Lighthouse v1 can be leveraged.

Common conditions and patient friendly name fields are likely comma separated lists.

There will also need to be error handling because taxonomy may not support all search terms.

[xiongjaneg]

This needs a lot of accessibility

[xiongjaneg]

Sept. 20 meeting around Facility Locator that this may need to inform.

[jilladams]

Found previous notes on this: https://github.com/department-of-veterans-affairs/va.gov-cms/issues/11542#issuecomment-1613718211

Some implementation nuances came up in 6/29 design review, documenting here for ref when we get to build ( with Michelle, Kamari, Swirt, Ryan, Jordan, Alexis, LauraF, Christian, and RyanT / Amanda Klausmeier):

Regarding how string search will work:

• Exact strings will be returned, e.g. search for "vision" will return all terms that include "vision"
• Algorithmic relationships between search terms will be limited to the content of the service taxonomy fields. For example:
  • For opthalmology, fields on the VA Service taxonomy term for that include the word "vision".
  • The data for these terms will be pulled into a JSON that will be the source material for establishing relationships.
  • SO: when a user searches "vision", they will get "Opthalmology" as a suggested result, due to the CMS term/content relationship.
  • If the taxonomy term does not include the word "Eye", then searching for "eye" will not return Opthalmology as a result.

Meaning: we are using the content of the taxonomy to drive search results here. We are not expanding scope to build a larger web of term relationships, to supplement search results.

Additional design notes are here: https://github.com/department-of-veterans-affairs/va.gov-cms/issues/14011#issuecomment-1613716121

[thejordanwood]

A couple of questions came up when reviewing this with engineers. I didn't have an answer at the time but will add them now.

1. How many options can show in the Service type dropdown?

This plain language search design comes from the 526EZ disability compensation form. My opinion is that we should default to however many options they show in their dropdown. If we can't find this info, the design system recommends less than 15 options.

2. How far away are we going to let health services show?

My opinion here is that we should default to the same distance that we use for the Community Providers search. If there are no results within a certain area, Community Providers displays a no results message and gives instructions for how to get better results. We should keep the experience consistent and do this for the plain language search as well.

[mmiddaugh]

Regarding the distance/radius - is there a difference in the radius for VA providers vs Community care providers? Is there a reason we can't maintain the same functionality for VA health searches as it exists today?

[thejordanwood]

I'm not sure if there's a difference, but agree that we should use the same functionality that exists today or try to be consistent with other search types (like Community Providers).

[mmiddaugh]

Functional Acceptance Criteria for consideration

• When Facility type = VA health, a Veteran can enter search parameters using plain language terms
  • Search functionality for all other types of facilities is maintained

Veterans (including those using screen readers, screen magnification, or keyboard navigation)

• are aware of the type of search used by the field
• are aware of the option to search for all VA health services
• are aware of the option to search using a popular search suggestion
• can select the option to search for all VA health services or one of the popular service suggestions
• are aware of services which match the Veteran's search term
• can select a matching service to search
• are presented with an appropriate error message if the search terms do not match keywords in the service taxonomy
• When reached by keyboard navigation, the list of popular service suggestions and matching search terms receives focus
• Search results are presented with a header which includes the search parameters and other existing behavior
• Search parameters remain visible after search results are displayed
• Review and sign-off by Design, A11y, PM, and PO

[mmiddaugh]

Design question: If the search term entered matches a keyword in the VAMC Description or Common conditions list, how will the matching services be presented? (compared to the highlighted word "vision" in the patient friendly names in Jordan's example above)

• example - if Veteran enters "movement" it matches the VAMC description but is not present in the Name or Patient-friendly name
  • Name: Physical therapy, occupational therapy and kinesiotherapy
  • Patient friendly name: PT, OT, KT
  • VAMC description: Physical therapy, occupational therapy and kinesiotherapy can help restore movement and function if you have been disabled by injury or disease.

Error messages

• If not yet available, we will need error messages and/or intended behavior for situations in which the search terms do not match keywords in the service taxonomy
• If not yet available, we will need updated error messages and/or intended behavior for situations in which no results are found for the specified service and location
  • examples: only 12 locations offer Bariatric surgery, 3 locations offer Genomic medicine, and 6 offer Hospital medicine

[davidmpickett]

1. How many options can show in the Service type dropdown?

This plain language search design comes from the 526EZ disability compensation form. My opinion is that we should default to however many options they show in their dropdown. If we can't find this info, the design system recommends less than 15 options.

While type-ahead =/= AutoSuggest, I think we should follow the Design System guidance and limit display to five suggestions.

Up to five suggestions are presented to the user in a dropdown menu after they have typed three characters or more in the query input box.

[thejordanwood]

I totally missed that! Thank you for calling that out and I agree that we should only show up to 5 suggestions.

[jilladams]

Added suggested ACs / error handling to ACs in ticket body. @thejordanwood can you confirm if the error states / intended behavior for those kinds of states are addressed in the design?

Also noting: the SPIKE around KISS data closed without incident. Takeaways are here: https://github.com/department-of-veterans-affairs/va.gov-cms/issues/15054#issuecomment-1743766937. This should be ready now to refine and figure out if we do actually need anything from Drupal, or if this implementation is all KISS.

[thejordanwood]

@jilladams Error states are not addressed in the design, but I can get them added this sprint.

Edit 10/31/2023: I've been unable to prioritize this work, and to keep track of this request I created #15935.

[mmiddaugh]

Relevant insights to consider in Research Findings: Facility Locator - Assistive Technology Discovery and Usability Study

[jilladams]

Status is still:

Also noting: the SPIKE around KISS data closed without incident. Takeaways are here: https://github.com/department-of-veterans-affairs/va.gov-cms/issues/15054#issuecomment-1743766937. This should be ready now to refine and figure out if we do actually need anything from Drupal, or if this implementation is all KISS.

If we do have Drupal work to unblock, need to get this refined and understand what work that is, for Q2 prioritizing. Queued for next refinement, though it might not happen in our very next refinement meeting.

[davidmpickett]

Noting that 526EZ team recently presented research findings about their AutoSuggest implementation: 7_1_2024 Conditions Page Design and Research Share.pdf

https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/disability/526ez/research/CC-Team-Research/202403%20Improved%20Autosuggest/Report.md

[davidmpickett]

From sprint planning today. @mmiddaugh would like to start getting a sense of scope/lift on this effort due to pressure from stakeholder to improve search functionality. Added @dsasser @Agile6MSkinner and myself as assignees for pre-refinement.

• After we have a good sense of the scope of this ticket, may want to also look at #18656 as a lower-lift, interim solution. But until we scope this one we can't gauge that one

[davidmpickett]

@mmiddaugh - notes from prefinement meeting with @eselkin @Agile6MSkinner and @dsasser today:

This story (14993) probably constitutes 3 separate pieces of work for an estimated 16 points

• JSONifying taxonomy data (~5 points)
• Ability to search/query the JSON (~3 points)
• Building the autosuggest component in Facility locator (~8 points)

Alpha list (18656) on the other hand, is not even roughly pointable right now

• Would need additional UX work on the exact flow and behavior of the how the list interacts with the main search app
• Requires adding an entirely new page to Facility locator
• Also needs to query the taxonomy and JSONify data and possibly in a different way than above
• Doesn't actually get us much closer to the primary desired state
• Is probably more work / has a longer lead time
• Not as well scoped/refined since it hasn't been the focus of previous SPIKES

[jilladams]

• In Product sync today, Michelle agreed that the effort toward Alpha list doesn't seem worth pursuing since it's not a lighter lift. We'll stay focused on autosuggest / typeahead filtering.
• Dave is happy to help cut tickets for the pointed efforts above, so they'll work on that this week.
• The 16 points listed represent the effort to get typeahead into staging for UX research, not to get it all the way to prod. Once it's in staging, we'll end up needing a launch ticket after research / iterations. Just making sure that's noted, per convo with Dave.

Also: FYI that @randimays is also interested in supporting the Facility Locator work, if / as needed (this and mobile map prototype). Chatted with her about that today, and we can include her on prefining / refining this stuff as well, whenever that might be necessary.

[mmiddaugh]

Update 11.5.2024

• this work is a priority in 4Q2024 and 1Q2025 (CY)