SOW: Email Notifications

[jillpe]

Summary

SOW

The goal is to implement email notifications for some activities/trigers in the Hyku application. That include:

• Notifications to submitter and approver for activity related to mediated deposit, which currently produce notifications within the app but not pushed out to email. These including:
  • Work submitted awaiting review
  • Work reviewed and accepted
  • Work reviewed and sent back with comment
  • Work revised and resubmitted for review
• Notifications to authors related to views and downloads of their works.

SoftServ will hook into the workflow callbacks to trigger notifications and set up notifications to trigger emails. The primary goal of this work is the implementation of email notifications related to mediated deposit. In SoftServ’s preliminary assessment the work to trigger email notifications for other activities and expand this requirement to meet the request from PALNI and PALCI to provide email notifications for views and downloads would not have a significant affect on scope and should be accomplishable within these sprints.

SoftServ allocates one 1-week sprint (apprx. 90 hours) including two senior engineers, project management, and QA resources to accomplish these goals.

See the below "Implementation Way Finding" for guidance on the submitter activity

TASKS

• Implement Batch Email Notifications #1019
  • Email Notifications UI #1022
  • Set up MailDev for Staging #1023
• Implement Depositor Notifications #1020

Acceptance Criteria

• Email notifications to submitter and approver for activity related to mediated deposit are set up and include: (see below)
  • Work submitted awaiting review
  • Work reviewed and accepted
  • Work reviewed and sent back with comment
  • Work revised and resubmitted for review
• Email notifications to authors related to views and downloads of their works are set up
  • (Jeremy here: the notifications of this bullet point are not handled in the "Implementation Way Finding" and require a different approach.)

Note

This work is not perfectly defined at the time of the SOW. The scope of the email notifications around author/work activity has the risk of ballooning. The spirit of this from Pitt was: We need email notifications for mediated deposit, and would like to include Pals' requirements if possible. Before we finalize this work, we should define options with Pitt, share scope concerns, estimate what is manageable within this sprint, and have Pitt/Pals prioritize accordingly armed with that knowledge.

Similar work was done for DOT: https://assaydepot.slack.com/archives/C0311DNF3MG/p1713215197011169

May be helpful: https://samvera.github.io/email_notifications.html or https://github.com/samvera/hyrax/wiki/Notifications-and-Messages

MAIL DEV setup: https://playbook-staging.notch8.com/en/devops/maildev

[ndroark]

Does this/should this include configuration options for user to turn off email notifications?

[jeremyf]

@ndroark my assumption is that the estimate did not include the option of Users managing those notifications. It's also envisioned as "each time something changes there will be one email sent". There's no concept of a digest of "Here's what happened today".

[jeremyf]

Implementation Wayfinding

There are two approaches for how we could send notifications:

1. (Favored) Configure Mailboxer to start sending emails when notifications happen within Hyrax. @orangewolf can point the way on this.
2. (Disregard) Add methods objects to the workflow the actions that change state

Method Objects

For the “state changing actions” (e.g. when items are approved), we can register a Sipity::Method. A registered method is called via Hyrax::Workflow::ActionTakenService.handle_action_taken.

In the Mediated Deposit Workflow we specify that when someone takes the “deposit” action that we’ll call the Hyrax::Workflow::GrantReadToDepositor method (and “Hyrax::Workflow::DeactivateObject”).

Given this, we then need to consider how to add those “methods” to the correct actions. There are two approaches:

1. Create a new workflow, which is a copy of an existing workflow. We’d then need to change the workflow for all objects in the repository. I do not recommend this, but it may be requested.
2. Copy the existing workflow JSON file into PALs’ knapsack. We would then amend that copy to include the correct methods. Once amended, we would need to reload that workflow; via Hyrax::Workflow::WorkflowImporter.load_workflow_for.

There is more to explore on how to load workflows, but I’m less familiar with that. I do think that reloading a workflow is non-destructive; that is you can call the load workflows and it will add the methods to the named workflows.

[ShanaLMoore]

We can use Hyku up to start development on this, while pals knapsack is still underway.

[kirkkwang]

Step 1, verify which of the actions generate notifications
Step 2, enable emails for notifications

Test emails with Mail Dev (check playbook)

Look into flooding the emails with Mailboxer, so the recipient isn’t getting flood with emails like every time a work gets viewed or downloaded

[ndroark]

I'm concerned about there not being either 1) summary options or 2) an off-button for these notification emails. Am I correct that if a user does a bulk import, for instance, of fifty works, then every user in that tenant who has approval permission for that admin set will receive an email for each work deposited? It feels like we might be building a UX WMD

[aahurford]

Consideration for: Email notifications to authors related to views and downloads of their works are set up

Mediated deposit often dictates that the submitter is not the same person as the author. We would need to figure out a way to add the contact of the author to the workflow.

[ShanaLMoore]

DEV NOTES

https://github.com/search?q=repo%3Asamvera%2Fhyrax%20AbstractMessageService&type=code. Anything inheriting the AbstractMessageService class should trigger a notification.

also ref: https://github.com/search?q=repo%3Asamvera%2Fhyrax%20AbstractNotification&type=code AbstractNotification class

How does this file come into play? This seems to be associated with all the specific workflows that trigger notifications.

Email how to wiki:
https://samvera.github.io/email_notifications.html

playbook: https://playbook-staging.notch8.com/en/devops/maildev

After following the wiki and playbook article, when I create a work I could see mailbox send an email in the server logs:

mailboxer gem

• Hyrax User is set up to be the message-able object

[laritakr]

How does this file come into play? This seems to be associated with all the specific workflows that trigger notifications.

Workflows are loaded via Hyrax's workflow.rake into appropriate database tables.
workflow_importer.rb does the work.
The Sipity entity relationship diagram is here

In the diagram, the ones outlined in yellow are the notification tables, and you can see they link to workflow actions.

[ShanaLMoore]

NOTIFICATION IMPLEMENTATION BRAINSTORM

Confirm that the desired actions are included in the workflow.json.

• if not, we'll need to add them. maybe ref: SOW: Email Notifications #1005 (comment)

⚠️ Check the mailboxer repo (ask Justin) to see if a batch email solution already exists. Look in the forks, issues, etc. ⚠️

If not...

• Hourly example: create a job to send an email, wait an hr. before sending the email, see if there are another other related jobs and add that content to it. this avoids using a scheduled job.
• Or, once an hr check for any pending emails, send as one email. get body of each notifications, order them, header ie: 'you have 8 new notifications'
• add email flag to mailboxer to keep track of what has been sent
• add as a re-occurring job per tenant: ref embargo and lease jobs for examples
• we need an UI option to turn off email notifications at a user level(which should mark any existing ones as sent)
  • hrly (too spammy), daily, weekly, monthly or off options

AUTHOR ANALYTIC IMPLEMENTATION BRAINSTORM

use google analytics?
does it track on a per work/collection basis? GA4 is broken. How does the counter metrics work?
Bad idea - to create a notification per each download/view event
How do we know who the author is + their contact details
hook into registered event 'file.downloaded'

ACTION ITEM - schedule meeting with pals to chat

ask about frequency

nthly

[ShanaLMoore]

@messags: https://github.com/samvera/hyrax/blob/42eccf44e698b9f625dc2a33b3715b0aafef5ffd/app/controllers/hyrax/notifications_controller.rb#L11

notifications partial:
https://github.com/samvera/hyrax/blob/42eccf44e698b9f625dc2a33b3715b0aafef5ffd/app/views/hyrax/notifications/_notifications.html.erb

[ShanaLMoore]

#1019 (comment)

@laritakr has a potential analytics based solution that her previous university implemented

Is Pals using dois on their works?

We used Altmetrics at ND…

The PR’s to implement are here: https://github.com/ndlib/curate_nd/pulls?q=Altmetrics+

re: altmetrics… if they care about downloads, then assigning a doi to the resource kinda makes sense anyway. And altmetrics allows you to view metrics for a doi

[ShanaLMoore]

What populates the views and downloads of the profile page? 🤔

I'm guessing nothing... But it might be a place to consider tying in some statistics info instead of doing another email report.