SPIKE: Determine VBA Regional Office IA implementation

[xiongjaneg]

Problem Statement

The official names of VBA facilities can be very lengthy. eg:

• Honolulu VA Regional Benefit Office at Spark M. Matsunaga Department of Veterans Affairs Medical Center
• VA Regional Benefit Satellite Office at Samuel S. Stratton Department of Veterans Affairs Medical Center

Previous conversation with CAIA led us to look at ways to shorten VBA facility names so we don't end up with incredibly long URLS / H1s / breadcrumbs for users.

We developed designs for splitting off Shared Location into text associated with the H1 so it wouldn't clog up the H1/URL/Breadcrumb.

VA Regional Benefit Offices

This approach will work very well for VA Regional Benefit Offices which almost always have a unique region as part of their official names.

• Official name: Honolulu VA Regional Benefit Office at Spark M. Matsunaga Department of Veterans Affairs Medical Center
• H1/breadcrumb: Honolulu VA Regional Benefit Office
• URL: va.gov/honolulu-va-regional-benefit-office
• Text associated with H1: Located at Spark M. Matsunaga Department of Veterans Affairs Medical Center

VA Regional Benefit Satellite Offices

However, it won't work as well for VA Regional Benefit Satellite Offices, since they don't currently have any unique identifiers aside from their shared location:

• Official name: VA Regional Benefit Satellite Office at Samuel S. Stratton Department of Veterans Affairs Medical Center
• H1/breadcrumb: VA Regional Benefit Satellite Office
• URL: va.gov/va-regional-benefit-satellite-office ❌
• URL: va.gov/va-regional-benefit-satellite-office-at-samuel-s-stratton-department-of-veterans-affairs-medical-center
• Text associated with H1: Located at Samuel S. Stratton Department of Veterans Affairs Medical Center

We may need to specify a REGION prefix for Satellite Offices. The VBA naming proposal contains extrapolated Regions for all Satellite Offices

• Official name: VA Regional Benefit Satellite Office at Samuel S. Stratton Department of Veterans Affairs Medical Center
• Region: Albany
• H1/breadcrumb: Albany VA Regional Benefit Satellite Office
• URL: va.gov/albany-va-regional-benefit-satellite-office
• Text associated with H1: Located at Samuel S. Stratton Department of Veterans Affairs Medical Center

Edge Cases

Only distinguished by Shared Location

Even with the addition of a region prefix, there are some instances where that might not be enough to differentiate the urls for satellite offices

• Official name: VA Regional Benefit Satellite Office at Maui VA Clinic
• Official name: VA Regional Benefit Satellite Office at Maui Vet Center
• Region: Maui
• URL: va.gov/maui-va-regional-benefit-satellite-office ❌
• URL: va.gov/maui-va-regional-benefit-satellite-office ❌

Do we keep these instances at the long URL of the current official name?

• URL: va.gov/va-regional-benefit-satellite-office-at-maui-va-clinic
• URL: va.gov/va-regional-benefit-satellite-office-at-maui-vet-center

Do we put the shared location up first in the URL?

• URL: va.gov/maui-va-clinic-va-regional-benefit-satellite-office
• URL: va.gov/maui-vet-center-va-regional-benefit-satellite-office

Though that then just begs the question why these aren't structured as sub facilities:

• URL: va.gov/maui-vet-center/va-regional-benefit-satellite-office

Shared Location is actually a Region

• Official name: VA Regional Benefit Satellite Office at Fresno
• H1/breadcrumb: VA Regional Benefit Satellite Office
• Text associated with H1: Located at Fresno ❌

Region may need to include city and state/territory

• VA Regional Benefit Satellite Office at Arlington, TX
• VA Regional Benefit Satellite Office at Fort Buchanan Puerto Rico

Do we need style guidance for military bases?

• VA Regional Benefit Satellite Office at Marine Corps Base Camp Pendleton
• VA Regional Benefit Satellite Office at Naval Submarine Base New London

Next steps

We need to make a decision on the exact way VBA Regional Offices and Satellite office will be named on the website & the technical implementations across all places the data is stored (Sandy's DB, Drupal, Lighthouse)

• Are we keeping the word regional in the name of all satellite offices? Even though it it dilutes the distinction between regional and satellite offices?

Documents

• IA spec from CAIA
• VBA naming schema
• Sharepoint VBA naming proposal
• Working mural
• Sketch file
• CAIA ticket
• Previous ticket

Acceptance Criteria - Sprint 103 (5 points)

• [x] Document proposal for splitting current official name field into parts
• [x] Proposal should cover H1s, Breadcrumbs, URLs, Drupal Sections, etc

Acceptance Criteria - Sprint 104 (8 points)

• [x] Proposal should cover technical implementation in Drupal, Sandy's DB, and Facilities API
• [x] Review proposal with Engineering, Product, and CAIA (if needed)
• [x] Once proposal is approved, update Naming Schema and update any follow up tickets
• [ ] Submit Collab Cycle Analytics request per https://github.com/department-of-veterans-affairs/va.gov-team/issues/46029 Max will finish VBA analytics ticket, add any comments to the collab cycle analytics request, and then tag Jane to submit the request.

[davidmpickett]

Notes from quick convo @mmiddaugh and I had this week:

• Short names proposal might not be best thing to broach with VBA national stakeholders immediately while reengaging them in project
• Need to find a time to talk about technical options with engineering. Can we use something for URL and Breadcrumbs while having something different for H1? What concerns does that raise?

[davidmpickett]

Updates from 16th minute discussion in scrum today:

• Short names proposal might not be best thing to broach with VBA national stakeholders immediately while reengaging them in project

@mmiddaugh reported that the first reengagement meeting with VBA stakeholders went really well, so maybe there's still a chance that we would have trust and buy in from them to work on this

• Need to find a time to talk about technical options with engineering. Can we use something for URL and Breadcrumbs while having something different for H1? What concerns does that raise?

From Steve - It is possible to have 2 fields on a node, and have those fields power different aspects of the iA (breadcrumb/URL) and another field that is the H1 (node title). If we are going to have 2 different strings, they should be 2 different fields, vs. trying to programmatically process a single field to get 2 different strings.

cc @jilladams for visibility

[davidmpickett]

Noting that @thejordanwood created designs to account for complex VBA names: https://www.sketch.com/s/891d33ae-152d-471c-ab5d-9aedf89cf6ff

[davidmpickett]

VBA naming proposal jan 17.xlsx Static copy of Sharepoint doc for ease of access

[xiongjaneg]

Other notes from Oct. 31 16th minute: Another aspect: distinction between H1 / breadcrumbs.

Can a short slug for URL / longer full title H1 be a thing?

IA governance would need to sign off BUT: a name is a name, so they can’t really speak to that. IA has supported shorter URLs if possible.

Technical problem re: whether / how we can pull off:

Full H1 Shorter URL Specified breadcrumb All breadcrumbs are in Drupal, so this is in Drupal camp to resolve.

[davidmpickett]

Updated static copy of spreadsheet. Now with better colors and sorting! VBA naming proposal jan 18.xlsx

[mmiddaugh]

Imagine a future state in which a benefit location co-located within a medical facility or Vet Center could be listed as a service location within the service accordion on the VAMC or Vet Center page. Example: VA Regional Benefit Satellite Office (at Des Moines VA Medical Center) is listed as a service location for Returning service member care on Des Moines VA Medical Center. Is there anything we could/should do now from a content model/data structure perspective to set us up better for that future?

[davidmpickett]

Imagine a future state in which a benefit location co-located within a medical facility or Vet Center could be listed as a service location within the service accordion on the VAMC or Vet Center page. Example: VA Regional Benefit Satellite Office (at Des Moines VA Medical Center) is listed as a service location for Returning service member care on Des Moines VA Medical Center. Is there anything we could/should do now from a content model/data structure perspective to set us up better for that future?

This is pretty much the opposite of how the content model is currently structured and there may be a point in the future where we basically need restructure everything to make Service Locations the focal point rather than Facilities. (I like to think about it like when you realize a sock is inside out and you need to pull it through itself to hide the seams. It still works as a sock either way, but one way is slightly more comfortable and stylish.)

Current

• Facility A
  • Facility Service 1
  • Service Location a
  • Facility Service 2
  • Service Location b
• Facility B
  • Facility Service 3
    • Service location c

Right now Service Locations are Paragraph Types rather than Content Types. This means that a Service Location doesn't really exist on it's own independent of the Facility Service it is attached to. It makes is very hard for a Facility Service (Returning service member care at Des Moines VA Medical Center) to reference a Service Location attached to a different Facility Service at a different facility (Returning service member care at VA Regional Benefit Satellite Office at Des Moines VA Medical Center).

We do have a field on VBA Facilities for Shared VHA Location that could theoretically allow queries to go up, over, and down to pull this information from a Service Location. This is definitely something we want to preserve, but we aren't currently using it to power anything.

I do think that there is a future where we create a "Reusable Service Location" Content Type similar to how Public Websites has a distinction between Reusable Q&As (Content Type) and Page-specific Q&As (Paragraph Type).

• Facility A
  • Facility Service 1
  • Facility-specific Service Location a
  • Reference to Reusable Service Location C
• Facility B
  • Facility Service 2
  • Reference to Reusable Service Location C
• Reusable Service Location C

Another possibility is that we update Service Location fields like hours and address to have "Choose a different facility to reference" instead of only referencing the facility that they are nested under.

[davidmpickett]

Is there anything we could/should do now from a content model/data structure perspective to set us up better for that future?

@mmiddaugh I realize I just said a lot of words without actually answering your question😅 Here's a succinct actual response:

This future is exactly one of the reasons we are putting so much time and energy into having VAMCs and VBA both Service Location. By storing the most vital and reusable elements in the exact same format it will make cross-pollination possible. By contrast, Vet Centers don't currently use Service Locations on their Facility Services, so a future where a VBA Service Location is shown on a Vet Center Service is further off.

[xiongjaneg]

Dave has another ticket address the long names with "and" vs. "at." That ticket will follow this spike.

Yes, #11628

[davidmpickett]

We need to make a decision on the exact way VBA Regional Offices and Satellite office will be named on the website & the technical implementations across all places the data is stored (Sandy's DB, Drupal, Lighthouse)

Are we keeping the word regional in the name of all satellite offices? Even though it it dilutes the distinction between regional and satellite offices?

Chatted with @mmiddaugh about proposing the official label of satellite offices

• From: VA Regional Benefit Satellite Office
• To: VA Satellite Benefit Office

She will discuss with VBA stakeholders

[davidmpickett]

VBA naming proposal has been updated with columns for URLs

[davidmpickett]

Mural: https://app.mural.co/t/departmentofveteransaffairs9999/m/departmentofveteransaffairs9999/1707266192237/97f7666116d3fa72ccfe4b136a23a7f1e948432b?sender=u9c899abc4fe36c9a698b1647

[davidmpickett]

End of sprint update - 5 points completed. 8 points remaining for next sprint. I will also need some of that capacity to come from Drupal & Front End. @xiongjaneg we can chat more in our sync tomorrow

[davidmpickett]

Meeting to discuss initial draft of plan with engineers scheduled for 2/14

[davidmpickett]

VBA naming proposal - feb 14 2024.xlsx Static copy of the sharepoint spreadsheet for convenience

[davidmpickett]

Agenda for 2/14

• Introduction to problem space and important documents - (5 min)
  • This github ticket
  • Working mural
  • Naming proposal spreadsheet (sharepoint = source of truth) (static copy for convenience)
  • Facilities naming schema
• Overview of the problem - (10 min)
• Shared location details & migration proposal - (10 min)
• Office type details - (10 min)
• Geographic region - (10 min)
• Condensed name - migration options - (10 min)

[jilladams]

Updated ACs in this ticket based on Dave's end of sprint 103 update. @davidmpickett I'd like to try to follow the UX paradigm we've used on other UX tickets, to spell out what we can commit to per sprint in terms of ACs / points. I think that'll help us get a grip on whether we're overplanning for you.

[davidmpickett]

Thread 1 - Implement "shared location"

Based on conversations on 2/14 and subsequent discovery, I am proposing implementing Shared Location as the first thread of the renaming effort.

Ticket 1 - Sandy's DB clean up

• Product / Content
• initial quick findings in slack
• Audit the fields Non-VA location official name, Shared VHA location, and Official name
• Update the fields Non-VA location official name and Shared VHA location to match reality / official name
  • Only one of these two fields should be populated
• Do not update official name unless it contains ontologically inaccurate information. This is primarily an additive audit, so we shouldn't be removing any information.
  • Shared VHA facility has a new name not reflected in official name = don't change official name
  • "Shared location" in official name is actually a geographic region (e.g. Sacramento) = don't change official name
  • There is data in either Non-VA location official name, Shared VHA location that is not reflected in official name = don't change official name
  • We learn that a facility that currently says it has a shared location is actually a standalone building = maybe change official name, but it's not vital for the sake of this ticket
  • Once the data is cleaned up Ticket 2 is unblocked

Ticket 2 - Run periodic VBA migration into Drupal

• Drupal engineering
• Blocked by ticket 1
• VBA Facilities VBA Database Migration
• Doesn't technically block other tickets from starting, but will be important to run so that we can properly review before launch

Ticket 3 - Update VBA FE query & template

• FE engineering
• Not blocked by tickets 1 or 2 because these fields are already in Drupal
• Display "Located at " [shared location] as text associated with H1
• For Shared VHA location - get the title of the referenced node (will be a VAMC or Vet Center) = [shared location]
• For 'Non-VA location official name' - it's a text string = [shared location]
• If both fields populated, use Shared VHA location and ignore non-VA official name
• Since we haven't clipped the official name yet, this will have [shared location] information twice. Once in H1 and now in the new associated text
• Keep this in an integration branch until we snip the official names

Ticket 4 - Talk with Lighthouse about supporting these fields 

• Product / Drupal engineering
• Not blocked by any previous tickets
• Will Lighthouse use Drupal as it's Source of Truth? Or will it use Sandy's DB? What makes sense short term and long term?
• Blocks ticket 5

Ticket 5 - Update Facility Locator search results

• FE engineering
• Blocked by ticket 4 I think
• Once fields are available in Facilities API, use the same logic as the VBA regional office page to pull a [shared location] text string
• Once again will result in double information
• Keep it secret, keep it safe in an integration branch

Ticket 6 - Update Facility Locator auto-generated pages?

• FE engineering
• Blocked by ticket 4
• Do we control these pages?
• Is it worth the time to update these templates to have associated text?

Ticket 7 - Update Sandy's DB to shorten the official names

• Product
• Blocked by all previous tickets
• Confirm that shared location is showing up in correct FE locations (in integration branch environment) before removing it from the official name of Regional Offices in the database
• Don't change official name for Satellite Offices until Thread 2 is complete.

Ticket 8 - Merge integration branch

• FE / Drupal / Product
• Blocked by all previous tickets
• Order of operations will be detailed in this ticket once created
• Drupal may also want to have #11628 in place before merge
• End result is that lots of names are shorter on FE and in Drupal

[davidmpickett]

Thread 2 - Adding "Geographic Regions" to Satellite Offices

We need to specify a geographic region prefix for Satellite Offices. The VBA naming proposal contains extrapolated Regions for all Satellite Offices.

Ticket 1 - Confirm "geographic region" approach with VBA

• Product
• Michelle to chat with stakeholders and confirm the overall approach
• Share proposed geographic regions for confirmation
• For the 10 locations that are only distinguished by shared location 1) confirm they are all active locations 2) decide on how to differentiate any remaining conflicts
• Could be pared down from the full list of ALL regional offices and satellite offices to just the ones for MVP if we need to narrow focus
• Blocks ticket 3

Ticket 2 - Reuse name field or create new field

• Product / Drupal Engineering / Lighthouse
• Determine the best approach for changing names
• Option 1 - Create "Condensed name" as new field in Sandy's DB
• Option 2 - Overwrite official name in Sandy's DB to condensed name
• Option 3 - Create condensed name as new field in Drupal (on 2/14 this seems like a no go, but keeping it on the list for now)
• If we go with option 1 or 3, are we inserting geographic regions into condensed name or official name?
• We briefly chatted about these paths on 2/14, but it was at the tail end of a long meeting.
• Might block ticket 3
• Might make ticket 7 in thread 1 unnecessary

Ticket 3 - Update names in Sandy's DB (or Drupal?)

• Product / Drupal Engineering
• Blocked by ticket 1 & Maybe 2
• Once geographic regions are approved, add them into the names that need it (all satellite offices + Manilla)
• This ticket may or may not happen at the same time at Ticket 7 in Thread 1.

[davidmpickett]

@mmiddaugh based on our conversation today, I started a draft of an Analytics Request with URLs for the Regional Offices that are part of the MVP and have a name that won't change (all of them except Honolulu and Anchorage). That seems like a good batch to focus on for staging review and more analytic request can come later in the process.

@xiongjaneg or @jilladams, I could use some help with filling out the other aspects of that Analytics Request.

https://github.com/department-of-veterans-affairs/va.gov-team/issues/76780

[davidmpickett]

I have a pull request for updating the naming schema documentation. https://github.com/department-of-veterans-affairs/va.gov-team/pull/76781

[mmiddaugh]

For the engineering conversation, there are four locations which have shared vha locations which are not reflected in the name

Current name	vha shared location id	vha shared location name
White River Junction VA Regional Benefit Office	vha_405	White River Junction VA Medical Center
Cheyenne VA Regional Benefit Office	vha_442	Cheyenne VA Medical Center
Muskogee VA Regional Benefit Office	vha_623	Jack C. Montgomery Department of Veterans Affairs Medical Center
San Diego VA Regional Benefit Office	vha_664BY	Kearny Mesa VA Clinic

and a few examples with non-VA shared locations which are not reflected in the name (one is an MVP location) Current name	non-VA shared location name
Cleveland VA Regional Benefit Office	Patrick V. McNamara Federal Building
Detroit VA Regional Benefit Office	Anthony J Celebrezze Federal Building
St Paul VA Regional Benefit Office	Henry Whipple Federal Building
Albuquerque VA Regional Benefit Office	Dennis Chavez Federal Building

The rule about having either a shared non-VA location or a shared VA location but not both is not accurate: Manila VA Regional Benefit Office at U.S. Embassy in Manila is associated with a non-VA building (U.S. Embassy in Manila) as well as a shared VHA location (VA Manila Outpatient Clinic). Both are true: the Clinic is on the Embassy campus.

Questions

• How might we ensure the names of shared VA locations are accurate?
  • Database currently has 10 locations with shared vha locations which have had name changes and the official name still uses previous name
  • One location has the shared location name for a completely different facility than the name affiliated with the shared vha ID

[davidmpickett]

@jilladams @xiongjaneg Re the last AC

Submit Collab Cycle Analytics request per Collaboration Cycle for Sitewide Facilities VBA Regional Offices va.gov-team#46029

• I created a draft: https://github.com/department-of-veterans-affairs/va.gov-team/issues/76780
• Might make sense for @maxx1128 to finish and submit as part of #16311

[jilladams]

Closing based on notes in comments and the follow tickets that are created / queued. If anyone has concerns please feel free to flag.