Discovery: Learn how the notifications framework works & map plan for Q4 notifications work

[jilladams]

User story: Full Width Banners

AS AN Editor
I WANT to select the initial period for display of my full-width banner, up to 7 days
SO THAT site visitors always get a relevant experience.

AS A VA owner
I WANT aging banners to expire
SO THAT site visitors always get a relevant experience.

User story: Homepage blocks

AS A Home Page Editor
I WANT to be notified when my content is old
SO THAT site visitors always get a relevant experience.

Q4 intentions

Create notifications for:

• Full width banners (content type): Dave has requested that we set an expiration date for these nodes, default to 7 days from creation, but provide a date picker Editors can use to set a different sooner date. And, that the CMS sends emails relative to the date an Editor sets as the end date, on the following timing:

  • 2 days in advance of the specified date.
  • Day of expiration
  • When content is auto-archived

• Homepage promo blocks. (Blocks are not a content type): We don't know what constitutes old, but at some frequency (monthly?)

• Top Pages Menu (does not currently use Editorial workflow)

The current mechanism for Notifications is default monthly send.
The full width banners requirements suggest one-off emails on a specified timeframe, rather than monthly. This is potentially the biggest leap in the framework that will need to be made.

CMS team created a Notifications framework that is currently being used to send notices to VAMC and Vet Center editors. We need to understand how it works today, in order to understand what work may be needed to use it for our Q4 intentions.

• Product brief.
• Documentation

Previous implementations / SMEs

VAMC notifications: Edmund created the framework and managed first usage for VAMCs.

Facilities: Vet Center notifications: Steve Wirt made the email template responsive, and managed use for Vet Centers.

• Ticket: Implement Vet Center Notification email #14816
• PR: VACMS-14816 Add Vet Center outdated content email #15232

ACs

8 points timebox to check in re: more time needed.

• Notifications documentation is reviewed in detail.
• Gap analysis for Full Width Banner is documented in ticket comments and/or new tickets, for how the framework meets / doesn't meet needs for our Q4 intentions
• Gap analysis for Home Page Blocks is documented in ticket comments and/or new tickets, for how the framework meets / doesn't meet needs for our Q4 intentions
• Meet with Swirt to discuss knowns / limitations, if/as needed
• Fran to schedule review with Dave (include Jill)

[jilladams]

Notes

• Email recipients: Notifications framework currently sends to the "last modified by" Editor.
• Erika noted that Notifications framework uses Flags. We need to work out the exact use, and whether Blocks / Menus can be flagged, or if framework will need to be expanded to some other trigger.
• Notifications engine is based on annual content refresh ("web content should be reviewed by web editors once per year", product brief), and batches monthly emails to the "last modified by" Editor on content approaching the one-year since update mark.
• As far as we know, Notifications system only handles Nodes (not blocks, menus, taxonomy terms, etc)

Full width banners:

Requirements we've heard from Dave:

• adding a date mechanism to FWB form, with a default expiration date 7 days after today.
• Editors can modify that date to extend it.
• Content will be auto-archived as of the specified date.
• Notifications will send
  • 2 days in advance of the specified date.
  • Day of
  • When content is auto-archived
• Once archived, we don't want to allow FWBs to be unarchived, or re-used
  • Because: Banners are dismissable, so people who have dismissed won't get the recent update.

We will need to build:

• Date mechanism on the FWB node form
• Auto-archiving mechanism -- Current Notifications framework doesn't modify nodes; only sends emails about them. Auto-archiving may exist in the CMS somewhere? If not, would be new and ours to build / manage (will require CMS Collab Cycle touchpoints).
  • We need to be mindful of governance flow for what happens if something gets auto-archived that shouldn't have been / needs to be re-published or re-created.
• Expand Notifications framework to send emails driven by dates on the nodes. (Currently it only sends monthly.)
  • This framework will be used by the ever-expanding group of CMS teams, so we don't want to hardcode the rules that drive when Notifications send (if not on the monthly cadence). Ideally, this should be a configuration option in the CMS somewhere.
  • Dave's suggestion: can we expand the framework to do this process daily? (Flag content daily based on upcoming expiration, then send daily notices.)
• Email content for all 3 flavors:
  • 2 days in advance
  • Day of
  • On auto-archive

Questions:

• For Full width banners: Editors are typically CAIA, for the 14 banners that have been created
  • Need to clarify Dave's vision here, to confirm we are only talking about Full Width banners, and not also Facilities content types (e.g. VAMC System Banner alerts, etc).
    • VAMCs are out of scope
    • Some of these banners have been reused for multiple updates.
• When should notifications send? (How far in advance of the specified node date deadline)
  • 2 days before expiration
  • Expiring today
  • When auto-archived

Blocks

We need to build:

• Notifications framework: expand it to handle blocks
• Email content

Questions:

• I (Jill) created/modified the 2 homepage blocks, so would be the one to receive notifications until another Editor modifies them. Who should be receiving the emails?
  • Benefit promo - CAIA will be owners.
  • News promo - OPIA will be owners.
• How frequently should the blocks be updated / should emails send? (Notifications framework is based on annual updates.)
  • Benefit promo - monthly
  • News promo - DaveC to follow up with Josh Tuscher, start with monthly

Menus

Requirements: Top pages menu (https://prod.cms.va.gov/admin/structure/menu/manage/popular-on-va-gov), should be periodically refreshed.

We need to build:

(If emails):

• Editorial workflow into Menu Items - may not be possible at Menu level, might be possible to add to Menu Items
• Notifications framework: expand it to handle menus

Questions:

• Are emails the right mechanism? Should we instead consider automating this section to be a widget that displays most-visited pages? (Instead of a Drupal menu.) We've discussed this possibility before, no backlog ticket that I can find).
• If emails:
  • How frequently should this menu be updated / should emails send?
  • For menus: unclear, without Editorial Workflow, but I believe a Public Websites team member created this menu and would receive these emails until another Editor modifies it.

[jilladams]

Menus: DaveC removed from Q4 scope.

[jilladams]

From planning: there is some risk in S95 that this ticket will begin and not end, tbd outcomes on #15641. DaveC has signed off.

[jilladams]

#13529 is unblocked for Nat'l Events Calendar work, and has been injected into sprint, which pushes this ticket lower in priority. It will not close within sprint, and we'll assess how much work remains by end of sprint, depending on how Events work shakes out.

[FranECross]

@dsasser @chri5tia Jill and I edited the ticket for clarity. Will you please review and let us know if you have any questions? cc @jilladams

[jilladams]

@FranECross @dsasser @chri5tia I'm realizing now that this comment: #15533 (comment), contains additional notes that weren't integrated in the ticket body before.

This discovery is specific to the Notifications framework. Fran, when we talked earlier, I mentioned that there are some other specific things Dave is interested in re: enforcing governance (auto expiring nodes, not allowing Full width banners to be re-published, etc.) I don't know if those should or shouldn't be included in this discovery.

• If included: we need to update ticket body again to be explicit about that, based on the notes in the comment I linked above.
• If excluded: we need a separate ticket to cover those pieces.

Daniel and Christia plan to co-work on this ticket tomorrow, and we have BE refinement at 3:30 tomorrow. I propose we kick off BE refinement by talking about this ticket, and clean up any danglers as needed.

[FranECross]

@jilladams Thanks for this additional information! I'm onboard with your proposal to chat about this ticket during BE refinement. Thank you! cc @dsasser @chri5tia

[dsasser]

@jilladams @FranECross thank you both for clarifying the scope and details of this discovery.

Some questions:

When content is auto-archived

How long after creation should the FWB be archived? If it is archived the same day it expires, we would be sending 2 emails on the same day for a given FWB.

Who should be receiving the email notifications? The current framework doesn't use the author of the content, but the owner of the Section.

Does editing a FWB cause the 7 day window to reset automatically?

provide a date picker Editors can use to set a different sooner date

Does this mean that the user is unable to set a future date greater than 7 days?

Regarding expiring FWB: do we want to do any FE work to ensure the banner is not displayed after the specified expiration date.

[FranECross]

@dsasser Thanks so much for the excellent questions! We'll be discussing this story in BE refinement today (10/31), and I may need to take some questions back to Dave for clarification to ensure we're following what he'd envisioned. cc @jilladams

[chri5tia]

Questions:

• Are emails the right mechanism? Should we instead consider automating this section to be a widget that displays most-visited pages? (Instead of a Drupal menu.) We've discussed this possibility before, no backlog ticket that I can find).

It doesn't feel like an email notification is the right system. Users/section owners are getting emails for outdated nodes once a month which is supposed to take them to a view of outdated content (nodes). An outdated block would get overlooked or mixed up with outdated nodes that the view is on. There are so few nodes that there might be an easier way or if we do this we would need to build a new view and a new custom module. I am still thinking of alternative ideas.

• If emails:
• How frequently should this menu be updated / should emails send?
• For menus: unclear, without Editorial Workflow, but I believe a Public Websites team member created this menu and would receive these emails until another Editor modifies it.

I need to look into this further and need more understanding about the the menu piece.

This discovery is specific to the Notifications framework. Fran, when we talked earlier, I mentioned that there are some other specific things Dave is interested in re: enforcing governance (auto expiring nodes, not allowing Full width banners to be re-published, etc.) I don't know if those should or shouldn't be included in this discovery.

• Discovery for creating a new feature that allows content to be permanently archived (re-publish being disallowed) should be it's own ticket.
• Auto-archiving discovery should be it's own ticket.
• Both of the above may easily be multi-sprint new functionality to the site.
• This ticket should strictly focus on notifying users or section owners when a full-width banner is 7 days old, for the sake of smoothness.

Some Notes

• notifications "framework" does not use flags
• it currently only works with nodes
• it is currently built to send once per month emails for those nodes
• a new custom module would be needed

Some questions

• I am clear about the use case for blocks/full width banners but not sure I understand the menus. We don't want to say that menus expire since are functional parts of the site and not content and links should be removed automatically once the content is archived, right? Need more insight into the use case or expectation for menus.

Engineering thoughts/questions

• I wonder how our existing system compares with this experimental module, which we don't seem to be using: https://www.drupal.org/project/outdated_content
• for auto-archiving, we can look at this D7 module for ideas: https://www.drupal.org/project/autoarch

[dsasser]

@chri5tia re your comment:

I need to look into this further and need more understanding about the the menu piece.

There is no menu requirement. This requirement was removed a few days ago. The active ticket description defines the current state of the ask.

a new custom module would be needed

That is speculative. We could add any additional work to the existing va_gov_notifications module.

I wonder how our existing system compares with this experimental module, which we don't seem to be using: https://www.drupal.org/project/outdated_content

This module works only with nodes, so it is a non-starter for our needs.

for auto-archiving, we can look at this D7 module for ideas: https://www.drupal.org/project/autoarch

I've discussed with the team if auto-archiving is currently in place, and it is not. However, the Scheduler module, along with the Scheduler content moderation integration modules are probably the best place to start, since they have widely used D8 versions, and Swirt and myself have used them in the past for this purpose.

[dsasser]

@jilladams @FranECross

Per these questions:

If included: we need to update ticket body again to be explicit about that, based on the notes in the comment I linked above.
If excluded: we need a separate ticket to cover those pieces.

And considering Christia's note above, we have identified these as future discovery and implementation tasks which should be carved into separate tickets.

[chri5tia]

@dsasser Thanks for clarifying about the menu. Scheduler module is a nice suggestion.

That is speculative. We could add any additional work to the existing va_gov_notifications module.

I meant "new module" as in new custom module functionality that doesn't use the existing module functionality. Whether it's there or somewhere else is out the scope of what I intended to communicate.

[jilladams]

Draft plan: I updated to add 2 things: https://docs.google.com/document/d/1h7oCFheAVZ8rhlmyE37GZYfGpE5rKS15lNIBIFgn5P4/edit?pli=1

1. A section that speaks to auto archiving, just compiling the notes from comments.
2. A section of unanswered questions, also from comments.

@dsasser can you review those sections and just make sure I didn't misstate anything, or if some of the questions have been answered, move them as needed?

@FranECross we could use a new discovery ticket to cover research around the auto-archiving concepts here. If we can get that up and pre-fined, we could pull it into next sprint.

I think we need to have a big conversation with Dave around this. Not certain if that should start with Product only, or include Daniel. @FranECross would be interested in your thoughts based on our conversations thus far / Daniel's doc.

[dsasser]

Discovery Findings

VACMS-15533_ Discovery notifications framework.pdf

Text-based findings for searchability

VACMS-15533 https://github.com//issues/15533 Gap Analysis: Can the existing notifications framework handle needs for PW Q4 goals? In short, no. The framework isn’t meant to be modified much for purposes other than to meet the needs of 6102. Overall, we have two options:

1. Expand the framework to be more flexible with types of notifications, cadences, and entity types - a very large lift (more than 2 sprints)
2. Implement a new framework which meets our criteria - a large lift (at least 2 sprints)

Requirement
Gap/FC/Other
Notes
Sending email
✅ FC
The notification system can send emails with (mostly) any content, driven by the existing mail sub-system and related templates.
Additional/differing mail delivery frequencies

(2 days in advance of the specified date, day of expiration, when content is auto-archived)
❌ GAP
Framework meant to send once per month only. Additional frequencies would require both backend code, and additional Jenkins job(s).
Expiration of content outside of the 6102 directive.

(7 day default expiration for Full Width Banners (Full Width Alert [banner]))
❌ GAP
The framework is meant for monthly notifications for content which has expired, according to the rules the framework dictates. No mechanism for defining a different expiration exists. Additionally, if we were to incorporate additional expiration types and timeframes, we could likely compromise the original intent of the existing framework to comply with 6102.
Works with Blocks
❌ GAP
Not a feature of the existing framework.
Aging banner expiration
❌ GAP
Existing framework only works with content expiration determined by the ‘field_last_saved_by_an_editor’ value.
Auto-Archiving
❌ GAP
Not a feature of the existing framework
Permanent Archiving
❌ GAP
Not a feature of the existing framework.
Editors can define a custom expiration date.
❌ GAP
Not a feature of the existing framework.
Configuration for when notifications are sent.
❌ GAP
There is no such configuration available in the current framework. The current monthly rule exists only in code.

---

Discovery Notes

Expand the framework to work with blocks.

When running the monthly process, the existing framework looks for content that is “expired”, or, hasn’t been updated in a year or more. The query involved, getOutdatedContentForSection():

• Returns only Node content.
• Only returns nodes that:
  • Are published
  • Are not exempted by type
  • Have a field_last_saved_by_an_editor timestamp a year or more old
  • Match the provided Section (using field_administration)

If we were to add blocks to the existing framework, we would need to:

• Add the ‘field_last_saved_by_an_editor’ to each block type.
  • And populate this field with a value using an update/similar hook.
  • And add a form alter to populate this field OR update the existing alter to expand to any entity type with this field.
• Update the getOutdatedContentForSection to also query for blocks. This would need to be a second query which would then need to append its results to the existing query (entity queries run against a single entity type). Making this more complicated than nodes is the mix of various field names for the same function on blocks–the section is either in the field_owner or field_administration fields.

However, because of the cadence and type of emails we expect to be sending (2 days in advance, day of, on auto-archive) for PW needs, we could not add the three email cadences to the existing framework without also impacting the existing delivery cadence for expired content.

Block count by type:

Concerns and Questions
If a block belongs to the same Section as a node, what would be the default outcome of that for the recipient?

How would the UX work with different entity types in a single email? The existing framework sends a link to a dashboard within the email (it doesn’t send the expired content to the user, as the length of a given email might be too much for an email system to handle).
Portions of the existing framework assumes Nodes. There could be parts of the workflow that could be drastically/unavoidably affected by adding Blocks, unless we sidecar blocks as a secondary/alternative workflow.
Date mechanism on the Full Width Banners node form
Adding a date field to a single node/other entity is trivial.
Expand Notifications framework to send emails driven by dates on nodes.
To support this, we would need to either:

• Enhance the current framework to be more flexible
• Create a secondary framework that doesn’t impact 6102

Both of these options would be a large lift.

Clarifying Notes from Ticket:
Email recipients: Notifications framework currently sends to the "last modified by" Editor.

❌ The ‘last modified by’/’author’ of the content is never used. The emails are sent to section members who have expiring content:

From Edmund:

• emails are sent to section members. So we check to see if a section's content is outdated and then notify the members of that section that it is outdated. We do not look at the author at all. We did this because people can move/leave and/or new people can join a section.
• …

Erika noted that the Notifications framework uses Flags. We need to work out the exact use, and whether Blocks / Menus can be flagged, or if the framework will need to be expanded to some other trigger.

❌ The notifications framework does not use flags.

✅ Only content (nodes) is currently supported. Supporting Blocks is a possibility, but has concerns for overlap with the existing process. Namely, there is no existing mechanism to splinter disparate entity types for unique notifications and delivery schedules.

Notifications engine is based on annual content refresh ("web content should be reviewed by web editors once per year", product brief), and batches monthly emails to the "last modified by" Editor on content approaching the one-year since update mark.

✅ The framework queries for content that is older than 1 year, based on the value of the ‘last saved by editor’ field mentioned earlier.

As far as we know, Notifications system only handles Nodes (not blocks, menus, taxonomy terms, etc)

✅ The framework only works with Nodes today. Adding additional entity types to the existing framework would be a large lift.

Auto-archiving content
This is a separate topic from the bigger picture Notifications framework, but addressed here due to the ticket definition.

This project will require CMS Collab Cycle.
Auto-archiving mechanism doesn’t exist in the CMS today. Will require its own discovery and lift.
Permanently archiving content that cannot be re-published is a new paradigm. Will require its own discovery / lift.
These should be ticketed for separate discovery.

Remaining questions:

• How long after creation should the FWB be archived? If it is archived the same day it expires, we would be sending 2 emails on the same day for a given FWB.
• Does editing a FWB cause the 7 day window to reset automatically?
• Is 7 days a hard minimum, and date picker will not allow user to set a future date greater than 7 days?
• Regarding expiring FWB: do we want to do any FE work to ensure the banner is not displayed after the specified expiration date.
  • Yes. FE should not display banners after the expiration date.

[FranECross]

@jilladams I think chatting with Dave sounds great. I think having Daniel present to provide intel on why things are a heavy-lift if Dave wants details during the meeting. Here's a first draft of AC for a new story around Notifications & Auto-archiving for both banners and blocks of info, split out into two separate sections. Feedback is always welcome.

Auto archiving and notifications for banners_blocks.pdf

cc @dsasser

[jilladams]

From scrum this morning: @FranECross will go ahead and cut the new Discovery tickets with the proposed ACs from comment above.

[jilladams]

@dsasser FYI that we discussed findings a little with Dave today. From that conversation:

• Dave's vision is for an extensible, reusable framework, so that others can benefit from the work being done in the ecosystem. Potential future uses: VBA, IIR teams, etc.
• Dave encouraged us to think of this as work toward building that system, that we will then apply to our use cases. e.g. the framework first, then Full width banners, then blocks. He's aware that's an investment.
• Goals include: to make it possible for a product team to configure a needed notification, for an entity type, specify a number of notifications that should be sent relative to a date for that entity type, based on some criteria, and the content of those notifications. There is more product work to do here to pin down the requirements for this framework more generally. @FranECross will help us work with Dave to define that.
• Re: whether we extend Notifications or create a new framework: we can make a proposal based on what we've considered, and CMS Collab Cycle will be stakeholders in the decision.
• Re: regression-proofing work to date if we expand the existing system: we should be mindful of existing test coverage or gaps.
• Re: sending 3 emails for FWB expirations, we raised the concern around 3 notifications (n days before expiration; day of expiration; when expired) feeling like spam. Dave would like us to make this configurable for product teams to specify cadence, even if we don't go that route specifically, to send 3 notifications, for FWB.

Next steps here:

• We will prioritize the archiving-related tickets into Sprint 98+
• Fran will draft an initiative brief to help capture direction / problems we are trying to solve. We'll review that with Dave.
• We need to figure out with CMS team what a CMS Collab Cycle touchpoint should look like, and how much of a plan / proposal we need to have worked out before that meeting. @FranECross this is something we will need to work with Berni on.

For this ticket's purposes, we can close, but: will leave that to @FranECross in case we need to further discuss anything here first.