R&S Editor UX allows multiple Beneficiaries per article

[wesrowe]

Description

User story

AS AN Editor of Resources & Support node
I WANT to be able to add multiple Beneficiary types to an article
SO THAT the R&S page more accurately represents reality.

Background

• Beneficiaries is a Taxonomy: https://prod.cms.va.gov/admin/structure/taxonomy/manage/audience_beneficiaries/overview
  • Also used on Campaign Landing Pages (Why This Matters > Audiences > Beneficiaries), but as an entity reference.
• On Resources & Support, currently, it's used within the "Audience and topics" paragraph type, Example node: https://prod.cms.va.gov/node/53778/edit
• "Audience and topics" paragraph type
  • We can control the cardinality within a Paragraph, so anywhere the Paragraph used will be affected.
  • is used in 6 content types. As of 10/31/23:
    • checklist = 2 nodes, draft
    • media_list_images = 2 nodes, both draft
    • media_list_videos = 2 nodes, both draft
    • step_by_step = 14 nodes, some published -- CAIA are editors.
    • faq_multiple_q_a = CAIA approved making multiple choice
    • q_a = CAIA approved making multiple choice
    • support_resources_detail_page = CAIA approved making multiple choice

Audience & Topics paragraph usage:

Engineering notes

The FE is capable of handling 1 or many tags for R&S pages at this time without modifications. The support_resources_detail_page.drupal.liquid template, which renders the related node types, leverages a common tags.drupal.liquid template for rendering tags, which itself leverages the Liquid filter getTagsList, which handles multiple instances of an audience tag:

getTagsList code

  liquid.filters.getTagsList = fieldTags => {
    const {
      entity: {
        fieldTopics = [],
        fieldAudienceBeneficiares,
        fieldNonBeneficiares,
      },
    } = fieldTags;

    const topics = fieldTopics.map(topic => ({
      ...topic.entity,
      categoryLabel: 'Topics',
    }));

    const audiences = [
      fieldAudienceBeneficiares?.entity,
      fieldNonBeneficiares?.entity,
    ]
      .filter(tag => !!tag)
      .map(audience => ({
        ...audience,
        categoryLabel: 'Audience',
      }));

    const tagList = [...topics, ...audiences];

    return _.sortBy(tagList, 'name');
  };

TBD: find uses of the underlying field (fieldAudienceBeneficiares:field_audience_beneficiares) to ensure there are no other uses of this field outside of the above template.

Stakeholders / Decisions

CAIA has approved allowing multiple selections for CAIA content types.
Facilities We need to review and understand any impact to them with this change.

Next Steps

• @jilladams @FranECross: Check with Facilities team
• FE team: assess impact in FE templates, including CLP and 6 other types listed above

Quality / testing notes

Prefinement tasks

• Audit CMS code for uses of this field
• Audit FE code for uses of this field
  • e.g. also what will happen on the FE?
• Review findings with PO/PM to confirm we should make this change
• Verify plan with CAIA
• Verify plan with Facilities team
  • Facilities team response: No evidence of the Audience & Topics paragraph type being referenced by any Facility content types (see screenshot in comment below R&S Editor UX allows multiple Beneficiaries per article #13188 (comment)

Acceptance criteria

• For all 6 affected content types: Content editors see Beneficiary choices as checkboxes
  • Editors are able to choose 1 or more checkboxes as the audience target
  • Previously selected radio button will have its checkbox auto-checked
• Ensure that this field has adequate automated tests & existing unit tests are updated
• PR should be marked DO NOT MERGE and ticket moved to Complete Pending Integration until FE work is complete
• KB article is updated not needed, comment

[wesrowe]

Needed to refine:

• What changes are required on FE? Does template use the Beneficiaries field?
• CMS design: are we switching to checkboxes (from radio buttons?)

Next step: @wesrowe to ask Danielle whether she minds the side effect wherever it appears.

Possible discovery: SQL queries to find out specifically where this appears so that we can provide that detail to Danielle.

[wesrowe]

Wes slacked Danielle.

Daniel provided other content types that would be impacted by this change:

Danielle is okay with enabling multiple beneficiaries on these types, with the caveat that relevant help text could be nice.

I think this is okay, but would love
@Mikki Northuis
's thoughts as well. I do wonder if we could add some helper text to help guide folks a bit so they don't always choose a bunch of beneficiaries by default.

(Waiting for Mikki's response.)

[wesrowe]

Mikki replied: She's okay with the change. She speculated these types are all R&S, and cautioned that she might be concerned if any are used in Facilities products. PW to-do: can we audit or otherwise rule out that Facilities editors see any of these content types?

[jilladams]

Related weird old ticket to consider re: Facilities / how other administrations may think about this: #5732

[jilladams]

We know CLPs include this list, as Why This Matters > Audiences > Beneficiaries. https://prod.cms.va.gov/node/add/campaign_landing_page

[jilladams]

Content types that would be impacted:

• checklist = 2 nodes, draft
• media_list_images = 2 nodes, both draft
• media_list_videos = 2 nodes, both draft
• step_by_step = 2 nodes, both draft
• faq_multiple_q_a = CAIA approved making multiple choice
• q_a = CAIA approved making multiple choice
• support_resources_detail_page = CAIA approved making multiple choice

Next steps

• Decide if we want to isolate this to R&S only or go ahead modifying for all these content types. In order to decide:
  • Need to understand FE impact.
    • Do all of these have FE templates? (video list, image list, etc)
    • What will happen if the FE templates receive multiple Beneficiaries?
• Need to clarify with Facilities what Editor impact, and change management required.

[jilladams]

Reached out to Facilities team: https://dsva.slack.com/archives/C0FQSS30V/p1698880051537049

[FranECross]

@dsasser @randimays @chriskim2311 Response from Facilities: No evidence of the Audience & Topics paragraph type being referenced by any Facility content types

[randimays]

Here are the findings for how the front end will be affected / need to be changed by making Beneficiary Tags a multi-select.

[FranECross]

@FranECross @jilladams Need to find the KB(s) that need to be updated.

[jilladams]

@FranECross @dsasser I took a look for KBs. No KB updates needed (striking through that AC), but we do need a ticket for videos. Notes below.

KBs

• at https://prod.cms.va.gov/help, searched for "beneficiary" and "beneficiaries" and got 2 Resources & Support hits:
  • https://prod.cms.va.gov/help/resources-and-support -- high level index page, no changes needed.
  • https://prod.cms.va.gov/help/resources-and-support/a-guide-to-resources-and-support-content-types -- No direct references to this field, so no direct edits needed.

Github docs

The 2nd KB above links out to several R&S Github docs which also don't include specifics about Beneficiary field and don't need updates:

• https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/content/resources-and-support-author-pilot/process.md
• https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/teams/vsa/teams/sitewide-content/checklists/content-checklist.md
• https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/content/content-patterns-and-standards/faqs.md

Videos:

The 2nd KB above links to 6 training videos. It's not reasonable to include updating these videos in this ticket, but we should probably make a backlog ticket to update them.

• FAQs: shows at 5:19 - https://www.youtube.com/watch?v=fkYrLG1F6uo&ab_channel=VACMSTraining (23 views in 1yr)
• R&S Detail page: field shows at 8:23 - https://www.youtube.com/watch?v=JL2IHsrm21M&ab_channel=VACMSTraining (10 views in 1yr)
• Step by Step: field shows at 8:17 - https://www.youtube.com/watch?v=aVTnsFE4-dM&ab_channel=VACMSTraining (21 views in 1yr)
• Checklist: shows this field at 6:26 - https://www.youtube.com/watch?v=jHr4jkHWldE&ab_channel=VACMSTraining (35 views in 1yr)
• Image list: field shows at 6:58 - https://www.youtube.com/watch?v=PB_rwyXhIMg&ab_channel=VACMSTraining(1 view in 1yr)
• Video list: field shows at 8:40 - https://www.youtube.com/watch?v=TsNaUy4LGUI&ab_channel=VACMSTraining (1 view in 1yr)

FAQs & R&S are actively used. Step by Step is in use but not as heavily. The other 3 content types are barely used. I think we could triage the videos in that way as well.

[FranECross]

@jilladams Thanks so much for this amazing detail. I'll create a ticket for updating the videos and will link to the epic.

[dsasser]

@FranECross @jilladams

Some questions:

1. Does this ticket pertain only to the 'Beneficiaries'? Or should the 'Non-Beneficiaries' also become checkboxes?
   

2. There are no existing tests at all for the Resources and Support content type. Adding them doesn't affect the effort, since we pointed at a 5 to account for unknown testing lift. However...

3. There is a mechanism controlling the total amount of "Tags" (the sum of all topics and beneficiaries/non-beneficiaries), which limits the total amount to 4. However, it either isn't behaving correctly, or needs modified help text. Modifying the help text might be possible in this ticket, providing all necessary stakeholders can weigh in within the sprint boundary, but perhaps we should carve out a separate ticket to unpack the expected behavior if we think it might need to be updated.

[FranECross]

@dsasser Thanks for all this info! I'll carve off one or two more tickets as you suggest so that the originally asked for change is within the sprint boundary, and that'll give me time to check on what to do with the Topics and Non-beneficiaries. Can this be in it's own branch so that we can hold back on releasing it until I can unpack the other requirements, etc.? Thanks again for all your work on this! cc @jilladams

[FranECross]

@jilladams Do you know which stakeholders I could reach out to in order to find out:

• do they also need non-beneficiaries as multi-select
• do editors typically select more than one Topic, or can we instead change the help text and leave it as is (where depending on how many beneficiaries are chosen, possibly only one topic is allowed), or do we need to allow for 1 to 4 topics regardless of how many beneficiaries are chosen.

Thanks in advance!

[FranECross]

@dsasser Regarding updated the videos, here is the new ticket created: #16239 cc @jilladams

[jilladams]

CAIA are the stakeholders here so a question in the #sitewide-content-accessibility-ia channel ( i think I got the order right) is a good starting place. You can tag Danielle and Randi Hecht, who have I think been involved here.

[dsasser]

Can this be in it's own branch so that we can hold back on releasing it until I can unpack the other requirements, etc.?

Yes I can do that.

[FranECross]

Questions posted in sitewide-content-accessibility-ia channel and Randi Hecht/Danielle T tagged, with cc to Daniel and Jill.

https://dsva.slack.com/archives/C01K37HRUAH/p1701292198711309

[dsasser]

Status Update 12/1/23

Work is done and approved, but we cannot merge until the FE work is ready.

[jilladams]

@dsasser clarifying: do CAIA's answers re: Topics / Audience changes block this? Or we could ship with what we've done and fast follow with any additional changes needed for that?

[dsasser]

@dsasser clarifying: do CAIA's answers re: Topics / Audience changes block this? Or we could ship with what we've done and fast follow with any additional changes needed for that?

Good question, I neglected to indicate that prior. The questions are non-blocking for this issue.

[FranECross]

Thanks, @jilladams and @dsasser . I'll follow up again on the questions and we can ship in the meantime. 🎉

[FranECross]

Followed up on original Slack message today: https://dsva.slack.com/archives/C01K37HRUAH/p1701705550448669?thread_ts=1701292198.711309&cid=C01K37HRUAH

[FranECross]

@dsasser We've heard back from Mikki/Danielle...

1. Non-beneficiaries: leaving as radio button selection is fine (from Mikki: these are not really utilized in the experience at this time and not intended to be used in the near future. No work on this is necessary. In addition, those groups are more mutually exclusive, and I would say that the radio button is more accurate for those options.)
2. For Topics, do you @dsasser have a feel for how much work it would take to allow the user to select 1-4 topics, regardless of the number of Beneficiaries chosen? Mikki's comment is below:

• Topics - the options available are far from complete and are not helpful at this time. In order for these to be helpful 1) you should be able to select more than 1 and 2) we need a much more comprehensive list and likely a hierarchy of topics. If the work to allow selecting more than 1 is extensive, then this could be postponed for now. cc @jilladams

[dsasser]

@FranECross

I'm not sure where the idea that only one Topic can be selected arose, but it is possible to select 4 Topics at this time. Since there are only 4 of them, I'm not sure we have any work to do on that front until more possible Topics are added (if ever they are).

[FranECross]

It's in reference to your note and screenshots way above (pasted below) indicating that it doesn't seem to be working correctly....

There is a mechanism controlling the total amount of "Tags" (the sum of all topics and beneficiaries/non-beneficiaries), which limits the total amount to 4. However, it either isn't behaving correctly, or needs modified help text. Modifying the help text might be possible in this ticket, providing all necessary stakeholders can weigh in within the sprint boundary, but perhaps we should carve out a separate ticket to unpack the expected behavior if we think it might need to be updated.

[dsasser]

Apologies for the confusion @FranECross. The current behavior works by counting the total number of Tags, including Topics and Beneficiaries, with the intent to cap the total to 4. Once the editor makes a total of 4 selections, the Tags field is locked for further editing (I had forgotten this was the case, hence my confusion). In other words, it doesn't matter if Topics is 1 or more, but once a total of 4 is reached, Topics is locked.

If we don't care to lock the user to 4 selections any longer, I propose we:

1. Change the help text, removing the maximum of 4 statement.
2. Updating the code to not restrict/lock out the Topics field at all.

This is a small lift, probably a 2.

I hope that helps, and again, apologies that didn't recall that Topics were being restricted to 1 in the screenshot above leading to the understanding that a user cannot select more than that.

[FranECross]

No worries at all, @dsasser ! This is great info, and I'll create a secondary ticket to do as you suggest in 1 & 2 above. Thanks again!

[jilladams]

Noting: FE change shipped that will handle either shape of data (single, or unlimited cardinality). CMS PR merged, will deploy tomorrow. We'll likely need CAIA's help for a prod verification, POC tbd.

[FranECross]

@jilladams thanks for the follow up on this with Dave and here! Here's a slack thread where Mikki, Danielle and R Hecht offered feedback on the multiple beneficiaries. I'll be creating follow up tickets (thought I had already) to completely remove the restriction on how many tags/beneficiaries can be added (the code has them currently lumped together in counting). https://dsva.slack.com/archives/C01K37HRUAH/p1701292198711309

[jilladams]

This change is live in prod. We can edit prod nodes without CAIA to confirm, so closing, and we can address any add'l follow up via the next steps ticket Fran is going to file.

[FranECross]

Ticket created #16574