pkp/pkp-lib#10403 Add docs for template access feature

Author: taslangraham

dev/documentation/en/email-templates.md

@@ -105,3 +105,59 @@ These templates can not be edited or deleted. However, each context can override
 Only the overriden templates will be deleted when a context is deleted or has its email templates reset. The default data will remain.
 
 When using the email templates repository, no extra consideration is required to fetch the correct email template. The repository's `delete` method will only delete custom data.
+
+## Template access restrictions
+
+Version 3.6 of OJS, OMP, and OPS allows Admins and managers to restrict email templates to specific user groups within a Context. By default, templates are open to all user groups, similar to previous versions.
+
+Before displaying an email template to a user, you should check if the template is accessible to that user's user group.
+
+```php
+use APP\facades\Repo;
+
+$emailTemplate = Repo::emailTemplate()->getByKey($contextId, $emailTemplateKey());
+
+return Repo::emailTemplate()->isTemplateAccessibleToUser($user, $emailTemplate, $contextId) ? $emailTemplate : null;
+```
+
+You can also assign user groups to a template.
+
+```php
+Repo::emailTemplate()->setEmailTemplateAccess($emailTemplate, $contextId, $userGroupIds);
+```
+
+*Note: the values passed in `$userGroupIds` will overwrite the existing groups assigned to the template.*
+
+You can make a template unrestricted, thus opened to all user groups.
+
+```php
+$isUnrestricted = true;
+
+Repo::emailTemplate()->setEmailTemplateAccess($emailTemplate, $contextId, null, $isUnrestricted);
+```
+
+If you have a list of templates, you can filter it to include only those accessible to the user.
+
+```php
+$collector = Repo::emailTemplate()->getCollector($contextId)->getMany();
+
+$emailTemplates = Repo::emailTemplate()->filterTemplatesByUserAccess($collector, $user, $contextId);
+```
+
+### Configuring Email Template Access in emailTemplates.xml
+
+When describing the data for email templates in `emailTemplates.xml`, you can specify if a template should be unrestricted by default using the `isUnrestricted` attribute.
+
+```xml
+<email key="EXAMPLE_TEMPLATE" name="mailable.example.name" subject="emails.example.subject" body="emails.example.body" isUnrestricted="1"/>
+```
+
+In the above example, the email template is marked as unrestricted - available to all user groups. You can also mark a template as restricted by using `isUnrestricted="0"`. Restricted templates will only become accessible after being assigned to a user group or marked as unrestricted.
+
+If the `isUnrestricted` attribute is omitted, the template will be treated as unrestricted by default.
+
+```xml
+<email key="EXAMPLE_TEMPLATE" name="mailable.example.name" subject="emails.example.subject" body="emails.example.body" />
+```
+
+The email template in the above template will be marked as unrestricted when installed.

learning-ojs/en/settings-workflow.md

@@ -254,6 +254,23 @@ To add a template, click **Edit**, followed by **Add Template**.
 
 ![OJS 3.4 emails templates.](./assets/learning-ojs3.4-jm-settings-workflow-multi-email-templates.png)
 
+#### Email template access
+
+You can restrict access to templates by user group. By default, all user groups have access to the default templates.
+
+1. Go to Workflow Settings > Emails > Add and Edit templates
+2. Click **Edit** on the template you want to modify.
+3. For the **Mark as unrestricted** option, select **Limit access to specific user groups**.
+4. Select the user group(s) that should have access.
+5. When you’re finished, click Save.
+
+You can also mark an email template as unrestricted.
+1. Go to Workflow Settings > Emails > Add and Edit templates
+2. Click **Edit** on the template you want to modify.
+3. For the **Mark as unrestricted** option, select **Mark as unrestricted** to the make the template available to all user groups.
+4. When you’re finished, click Save.
+
+*Note: You can only change the access for templates that are related to the submission workflow.*
 
 #### Filters