Limit email template access by sender and receiver role

[asmecher]

It's currently possible to create new email templates for mailables in a way that helps editors create their own email-based workflows. However, all mailables are available to all users when selecting a template, which can lead to inappropriate choices.

From e.g. Settings > Workflow > Emails > Add and edit templates > Discussion (Copyediting):

When an assigned Copyeditor goes to create a new discussion in the Copyediting stage, their Choose a predefined message to use dropdown includes Request Copyedit, which is inappropriate.

To resolve this, we should add support for mailables to be designated as appropriate for certain user groups, so that when a user sees a list of possible email templates, they are only given a list that's relevant or appropriate to them. It should be possible to designate user groups when creating/editing an email template within a mailable. This should only be available on certain mailables, as not all will be related to submission workflow.

Update 2024-10-25: Specification

(from @ewhanson)

Initial steps should be to identify which roles should have access to which mailable templates as well as identifying all mailables across all applications and first-party plugins (if any). From an initial assessment of the feature, it doesn't seem like any new UI elements/pages will be necessary, but an additional todo for that work should be added if it's deemed necessary. Any mailables that roles do not have access to should not show up when creating new templates.

Note: Each todo below should be tracked as separate issues. This issue should only be closed once this work package has been finished entirely.

TODOs

• Identify which sender/receiver roles should have access to which mailables
• Implement role check for mailables #10571
• Investigate what extension support is required (i.e. for existing plugins, mailables added via plugins that don't have roles assigned, etc.) #10649
• Provide documentation for pkp/pkp-lib#10403 feature (changes for release notebook, for docs hub, plugin guide, etc.) #10650
• Add e2e tests #10745

[ewhanson]

Hey @taslangraham, I've also assigned the issue for this work package to you. Have a look at the specification and todos above and let me know what you think. We can talk about any specific issues or questions you see in our one-on-one call on Monday.

[taslangraham]

@asmecher

Currently, each Mailable class has two properties: fromRoleIds and toRoleIds. These arrays hold the Role IDs of the groups designated to send and receive each Mailable. These properties could be used to control which templates are accessible and visible to a user.

However, in the issue, you mentioned that

It should be possible to designate user groups when creating/editing an email template within a Mailable.

Given that each Mailable can be restricted to specific groups, is it a case where we should also allow individual templates of a Mailable to be further limited to a subset of these allowed groups?

For example, if a Mailable is accessible to more than one role, should an individual template of this Mailable be configurable to allow access only to a single role?

[asmecher]

Yes, individual templates should be assignable to sender roles. Think of a discussion template; if managers want to use that to orchestrate a workflow between author and editor, there will be a mix of templates each will use to compose messages. It will be confusing to authors if they see editor templates available for their use.

[asmecher]

Some clarification and a mea culpa for the ambiguous language in the initial filing: The user working in settings should be able to designate which user groups (not role IDs) email templates can be sent by and sent to.

[taslangraham]

@Devika008 The image above shows the UI changes that I had made to the Add/Edit Email Template side modal while working on this feature.

Notes/thoughts/ideas/questions:

• The Mark as Unrestricted option takes precedence over any selections made under Limit Access to Specific User Groups when checked. Would it make sense to disable those options automatically or hide the section entirely when Mark as Unrestricted is selected?
• Initially, I used a simple list of checkboxes for selecting user groups, but a long list might feel overwhelming. We could consider using an auto-suggest component or a multi-select dropdown—though I’m not sure if such a component currently exists in our UI.
• Currently, if a user selects a specific user group, saves the form, then later marks the template as unrestricted, both the unrestricted setting and the user group selection remain. However, the unrestricted setting takes precedence. If the user then unchecks the unrestricted option, the previously selected user groups become active again. Do you think this behavior make sense to users from a UI/UX perspective? Should we keep user group selections when Mark as Unrestricted is selected, or would it be better to clear them?

[Devika008]

Hi @taslangraham,

Thank you so much for reaching out regarding this issue.

Regarding the Notes/thoughts/ideas/questions:

1. The Mark as Unrestricted option takes precedence over any selections made under Limit Access to Specific User Groups when checked. Would it make sense to disable those options automatically or hide the section entirely when Mark as Unrestricted is selected?

For a better user experience, I suggest displaying the question "Mark as unrestricted" with two radio button options:

• Option 1: Mark as unrestricted
• Option 2: Limit access to specific user groups
  The list of user groups should only appear after the user selects "Limit access to specific user groups." This keeps the interface clean and avoids unnecessary complexity upfront.

2. Initially, I used a simple list of checkboxes for selecting user groups, but a long list might feel overwhelming. We could consider using an auto-suggest component or a multi-select dropdown—though I’m not sure if such a component currently exists in our UI.

An autosuggest component won’t work well here since it’s difficult to remember all the user groups that might exist.
I don’t believe we currently have a multi-select dropdown in the UI, which would be the ideal solution—but it might take time to develop. I’ll be sharing designs for this as part of the new multilingual form fields.
Until then, we can use a long list of checkboxes, and once the multi-select dropdown is ready, we can replace it for a smoother experience. 😊

3. Currently, if a user selects a specific user group, saves the form, then later marks the template as unrestricted, both the unrestricted setting and the user group selection remain. However, the unrestricted setting takes precedence. If the user then unchecks the unrestricted option, the previously selected user groups become active again. Do you think this behavior make sense to users from a UI/UX perspective? Should we keep user group selections when Mark as Unrestricted is selected, or would it be better to clear them?

With the change mentioned in the first point, this issue won’t occur.

We need to make this an either-or selection, rather than allowing both options to remain active at the same time—otherwise, it can become confusing for the user.
Here’s how I suggest handling it:

• If the user selects "Limit access to a user group", they can check a few user roles.
• Later, if they change their mind and select "Mark as unrestricted", it should override the first selection, granting access to all users.
• However, if they later switch back to "Limit access to a user group", we should restore their previously selected checkboxes, allowing them to keep or modify their earlier choices.
  This approach ensures clarity, prevents unnecessary complexity, and provides a smooth user experience.

[taslangraham]

@ewhanson Here are the final set of PRs for this feature.

Functionality and tests implementation (these include work done for #10571 and #10745):

• ojs: pkp/pkp-lib#10571 Email access feature ojs#4745
• omp: pkp/pkp-lib#10571 Email access feature omp#1899
• ops: pkp/pkp-lib#10571 Email access feature ops#916
• pkp-lib: pkp/pkp-lib/#10571 email access restrictions #11090
• ui-library: pkp/pkp-lib#10571 Email access feature ui-library#559

Docs

• pkp/pkp-lib#10403 Add docs for template access feature [3.6] pkp-docs#1260

[ewhanson]

Awesome work @taslangraham! Feel free to squash and merge!

[taslangraham]

PRs for shared libraries and individual apps has been merged! Thanks for the review and general feedback on this one @ewhanson

[Tribunal33]

Tested and looks good. Automation is great too.

Here are the test scenarios.

1. Test Option Limit Access to specific user groups does block access to user with multiple roles
2. Options for Unrestricted user groups are saved when default options is changed.
3. Reset All Emails back to defaults button still works. Should revert any email with restricted access.
   (All automated below)
4. Test UI layout option is added to Edit Email Templates. Mark as Unrestricted
5. Test UI layout option is added to Edit Email Templates. Limit Access to Specific User Groups
6. Test Option Mark as Unrestricted does not block access to user group
7. Test Option Limit Access to specific user groups does block access to user group
8. Tests that user cannot access restricted template not assigned to their group
9. Tests that user can access unrestricted template not specifically assigned to their group
10. Tests that user can access template assigned to their group