Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
2 of 3 tasks
Tracked by #16686
xiongjaneg opened this issue Aug 28, 2023 · 21 comments
Assignees
Labels
crew-sitewide Facilities Facilities products (VAMC, Vet Center, etc) Facility Locator product owned by Facilities team Needs refining Issue status sitewide VA.gov frontend CMS team practice area VAMC CMS managed product owned by Facilities team

Comments

@xiongjaneg
Copy link
Contributor

xiongjaneg commented Aug 28, 2023

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

image

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: #15054 (comment)

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

Preview Give feedback
  1. 10 of 10
    Facilities Facility Locator VA services taxonomy VA.gov frontend ghp-closed sitewide
    eselkin
  2. Facilities Facility Locator VA.gov frontend ghp-refine points-3 sitewide
    eselkin
  3. Facilities Facility Locator Needs refining VA.gov frontend points-8 sitewide
    Agile6MSkinner
@xiongjaneg xiongjaneg added VA.gov frontend CMS team practice area Facilities Facilities products (VAMC, Vet Center, etc) Needs refining Issue status Facility Locator product owned by Facilities team labels Aug 28, 2023
@xiongjaneg
Copy link
Contributor Author

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"

@mmiddaugh mmiddaugh added VAMC CMS managed product owned by Facilities team Drupal engineering CMS team practice area labels Aug 29, 2023
@xiongjaneg
Copy link
Contributor Author

xiongjaneg commented Aug 31, 2023

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 xiongjaneg added the Epic Issue type label Aug 31, 2023
@xiongjaneg
Copy link
Contributor Author

This needs a lot of accessibility

@xiongjaneg
Copy link
Contributor Author

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

@jilladams jilladams changed the title Update Facility Locator search by service EPIC: Update Facility Locator search by service for plain language search Aug 31, 2023
@jilladams jilladams changed the title EPIC: Update Facility Locator search by service for plain language search EPIC: Update Facility Locator search by service to allow plain language search Aug 31, 2023
@jilladams
Copy link
Contributor

Found previous notes on this: #11542 (comment)

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: #14011 (comment)

@xiongjaneg xiongjaneg removed the Epic Issue type label Sep 19, 2023
@xiongjaneg xiongjaneg changed the title EPIC: Update Facility Locator search by service to allow plain language search Update Facility Locator search by service to allow plain language search Sep 19, 2023
@thejordanwood
Copy link

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.

Screenshot 2023-09-19 at 5 23 00 PM

  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.

  1. 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
Copy link
Contributor

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
Copy link

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

Screenshot 2023-09-19 at 5 23 00 PM

  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
Copy link

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

@jilladams
Copy link
Contributor

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: #15054 (comment). 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
Copy link

thejordanwood commented Oct 11, 2023

@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
Copy link
Contributor

@mmiddaugh mmiddaugh changed the title Update Facility Locator search by service to allow plain language search Update Facility Locator to allow plain language search for Lighthouse V1 implementation (Phase 3) Jan 2, 2024
@mmiddaugh mmiddaugh changed the title Update Facility Locator to allow plain language search for Lighthouse V1 implementation (Phase 3) Update Facility Locator to allow plain language search for VA health services via Lighthouse V1 (Phase 3) Jan 3, 2024
@jilladams
Copy link
Contributor

Status is still:

Also noting: the SPIKE around KISS data closed without incident. Takeaways are here: #15054 (comment). 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
Copy link
Contributor

davidmpickett commented Jul 3, 2024

@davidmpickett davidmpickett removed the CY24-Q2 Calendar year Q2 2024 priority label Jul 24, 2024
@davidmpickett
Copy link
Contributor

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.

@davidmpickett
Copy link
Contributor

davidmpickett commented Jul 25, 2024

@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
Copy link
Contributor

  • 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
Copy link
Contributor

Update 11.5.2024

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

@davidmpickett davidmpickett removed their assignment Dec 9, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
crew-sitewide Facilities Facilities products (VAMC, Vet Center, etc) Facility Locator product owned by Facilities team Needs refining Issue status sitewide VA.gov frontend CMS team practice area VAMC CMS managed product owned by Facilities team
Projects
None yet
Development

No branches or pull requests

7 participants