Send review notifications to service contacts

.github/workflows/test.yml

@@ -22,9 +22,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - localgov-version: '2.x'
-            drupal-version: '~9.4'
-            php-version: '8.1'
           - localgov-version: '3.x'
             drupal-version: '~10.0'
             php-version: '8.1'
@@ -106,9 +103,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - localgov-version: '2.x'
-            drupal-version: '~9.4'
-            php-version: '8.1'
           - localgov-version: '3.x'
             drupal-version: '~10.0'
             php-version: '8.1'
@@ -142,9 +136,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - localgov-version: '2.x'
-            drupal-version: '~9.4'
-            php-version: '8.1'
           - localgov-version: '3.x'
             drupal-version: '~10.0'
             php-version: '8.1'
@@ -177,9 +168,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - localgov-version: '2.x'
-            drupal-version: '~9.4'
-            php-version: '8.1'
           - localgov-version: '3.x'
             drupal-version: '~10.0'
             php-version: '8.1'

composer.json

@@ -9,6 +9,7 @@
         "drupal/diff": "^1.0",
         "drupal/responsive_preview": "^2.0",
         "drupal/scheduled_transitions": "^2.1",
+        "drupal/symfony_mailer": "^1.4",
         "localgovdrupal/localgov_core": "^2.12"
     }
 }

modules/localgov_review_date/src/Entity/ReviewDate.php

@@ -154,7 +154,7 @@ public function hasEntity(): bool {
   /**
    * {@inheritdoc}
    */
-  public function getEntity(): EntityInterface {
+  public function getEntity(): EntityInterface|NULL {
     return $this->get('entity')->entity;
   }
 

modules/localgov_review_date/src/Entity/ReviewDateInterface.php

@@ -73,10 +73,10 @@ public function getCreatedTime(): int;
   /**
    * Gets the entity that has been reviewed.
    *
-   * @return \Drupal\Core\Entity\EntityInterface
+   * @return \Drupal\Core\Entity\EntityInterface|null
    *   The content entity that has been reviewed.
    */
-  public function getEntity(): EntityInterface;
+  public function getEntity(): EntityInterface|NULL;
 
   /**
    * Gets the langcode for the entity review date.

modules/localgov_workflows_notifications/README.md

@@ -0,0 +1,82 @@
+# Localgov Workflow Notifications
+
+This module is designed to send notifications to service contacts when content moderation
+states change. It currently only implements email notifications when content passes its needs
+review date, but it should be easy to implement email notifications on other events.
+
+## Warning
+
+This module enables the [Symfony Mailer](https://www.drupal.org/project/symfony_mailer/)
+module which will take over email sending for the site. It's important to test the sites
+email settings after install to ensure they work for your environment. This is particularly
+important if the site already uses a contrib module to handle email sending as the Symfony
+Mailer module will take over from this. Modules that can cause issues:
+
+* [Mail System](https://www.drupal.org/project/mailsystem)
+* [Sendgrid Integration](https://www.drupal.org/project/sendgrid_integration)
+* [SMTP Authentication Support](https://www.drupal.org/project/smtp)
+
+## Setup
+
+The server must be able to send emails and cron must be running frequently.
+
+For email sending to work you'll need to set the default Symfony Mailer transport for your
+environment here: /admin/config/system/mailer/transport. In the settings there's also an
+option to send test emails so you can check your settings work.
+
+Emails are sent when either Drupal cron is run or the `localgov_workflows_notifications_email`
+queue is processed. It is recommended that Drupal cron runs at least every 10 minutes and uses
+an external trigger to run. For more information on setting up an external cron job see
+<https://www.drupal.org/node/23714>.
+
+## Structure
+
+There are 3 main components to the module; service contact management, notification creation
+and email sending.
+
+### Service contacts
+
+The module defines a service contact entity. A service contact is either an existing Drupal
+user or an external user with a name and email address.
+
+One or more service contacts can be associated with a piece of content. In theory this can
+be any content entity, but the widget to associate service contacts with content currently
+only works with nodes.
+
+### Notifications
+
+Any notifications added to the email queue will be sent at the next cron run.
+
+Needs review notifications are sent every X days for content with a needs review date that
+has passed in that time and hasn't already been reviewed. The frequency for this can be
+set at /admin/config/workflow/localgov-workflows-notifications.
+
+### Email sending
+
+This module uses the Drupal [Symfony Mailer](https://www.drupal.org/project/symfony_mailer/)
+module to send emails. This module provides a flexible way to send emails.
+
+To send emails you'll need to ensure the correct mailer transport has been configured at
+/admin/config/system/mailer/transport.
+
+The content of the notification can be changed by editing the body of the LocalGov Workflows
+Notifications policy at /admin/config/system/mailer/policy/localgov_workflows_notifications.
+
+If you want more control on the email content you can define your own Twig templates and
+inject CSS into the email. More information can be found in the
+[Synfony Mailer documentation](https://www.drupal.org/docs/contributed-modules/drupal-symfony-mailer/getting-started)
+on drupal.org.
+
+Two mailer transports are defined; Lando and Mailhog. The Lando transport is for use when
+developing in Lando and Mailhog can be used when using a mail catcher, like Mailhog, on a
+testing server. They can be deleted if not needed. To enable one adding the following to
+your `settings.local.php` file:
+
+```php
+$config['symfony_mailer.settings']['default_transport'] = 'lando';
+```
+
+## Adding a new notification type
+
+1. Create a trigger / cron job to add content to the `localgov_workflows_notifications_email` queue with your new type name.
+2. Optionally, create a new Symfony Mailer policy for this type.

modules/localgov_workflows_notifications/config/install/localgov_workflows_notifications.settings.yml

@@ -0,0 +1,2 @@
+email_enabled: true
+email_frequency: 1.0

modules/localgov_workflows_notifications/config/install/symfony_mailer.mailer_policy.localgov_workflows_notifications.needs_review.yml

@@ -0,0 +1,15 @@
+langcode: en
+status: true
+dependencies:
+  module:
+    - localgov_workflows_notifications
+id: localgov_workflows_notifications.needs_review
+configuration:
+  email_body:
+    content:
+      value: "<p>Dear {{ service_contact.getName() }},</p>\r\n<p>The following content needs reviewing:</p>\r\n<ul>\r\n{% for entity in entities %}\r\n  <li><a href=\"{{ path('entity.node.canonical', {'node': entity.id}) }}\">{{ entity.label }}</li>\r\n{% endfor %}\r\n</ul>\r\n"
+      format: email_html
+  email_subject:
+    value: 'Content needing review on the [site:name] site'
+  email_theme:
+    theme: _default

modules/localgov_workflows_notifications/config/install/system.action.localgov_service_contact_delete_action.yml

@@ -0,0 +1,10 @@
+langcode: en
+status: true
+dependencies:
+  module:
+    - localgov_workflows_notifications
+id: localgov_service_contact_delete_action
+label: 'Delete service contacts'
+type: localgov_service_contact
+plugin: entity:delete_action:localgov_service_contact
+configuration: {  }

modules/localgov_workflows_notifications/config/install/system.action.localgov_service_contact_save_action.yml

@@ -0,0 +1,10 @@
+langcode: en
+status: true
+dependencies:
+  module:
+    - localgov_workflows_notifications
+id: localgov_service_contact_save_action
+label: 'Save service contacts'
+type: localgov_service_contact
+plugin: entity:save_action:localgov_service_contact
+configuration: {  }

modules/localgov_workflows_notifications/config/optional/symfony_mailer.mailer_transport.lando.yml

@@ -0,0 +1,17 @@
+langcode: en
+status: true
+dependencies: {  }
+id: lando
+label: Lando
+plugin: smtp
+configuration:
+  user: ''
+  pass: ''
+  host: mailhog
+  port: 1025
+  query:
+    verify_peer: false
+    local_domain: ''
+    restart_threshold: null
+    restart_threshold_sleep: null
+    ping_threshold: null

modules/localgov_workflows_notifications/config/optional/symfony_mailer.mailer_transport.mailhog.yml

@@ -0,0 +1,17 @@
+langcode: en
+status: true
+dependencies: {  }
+id: mailhog
+label: Mailhog
+plugin: smtp
+configuration:
+  user: ''
+  pass: ''
+  host: 127.0.0.1
+  port: 1025
+  query:
+    verify_peer: false
+    local_domain: ''
+    restart_threshold: null
+    restart_threshold_sleep: null
+    ping_threshold: null

modules/localgov_workflows_notifications/config/schema/localgov_review_notifications.schema.yml

@@ -0,0 +1,7 @@
+field.value.service_contacts:
+  type: mapping
+  label: Default value
+  mapping:
+    value:
+      type: label
+      label: Value

modules/localgov_workflows_notifications/config/schema/localgov_workflows_notifications.schema.yml

@@ -0,0 +1,11 @@
+# Schema for the configuration files of the LocalGov Workflows Notifications module.
+localgov_workflows_notifications.settings:
+  type: config_object
+  label: 'LocalGov Workflows Notifications settings'
+  mapping:
+    email_enabled:
+      type: boolean
+      label: 'Enable email notifications'
+    email_frequency:
+      type: float
+      label: 'Email frequency in days'

modules/localgov_workflows_notifications/localgov_workflows_notifications.info.yml

@@ -0,0 +1,9 @@
+name: 'LocalGov Workflows Notifications'
+type: module
+description: 'Send notifications to service contacts when content needs reviewing.'
+package: LocalGov Drupal
+core_version_requirement: ^9 || ^10
+dependencies:
+  - localgov_workflows:localgov_workflows
+  - symfony_mailer:symfony_mailer
+configure: localgov_workflows_notifications.settings

modules/localgov_workflows_notifications/localgov_workflows_notifications.install

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * @file
+ * Install functions for the LocalGov Review Notifications module.
+ */
+
+/**
+ * Implements hook_install().
+ */
+function localgov_workflows_notifications_install($is_syncing) {
+
+  // Display a message if a conflicting mail module is enabled.
+  $conflicts = [
+    'sendgrid' => 'Sendgrid',
+    'smtp' => 'SMTP',
+    'mailsystem' => 'Mail System',
+  ];
+  foreach ($conflicts as $module => $title) {
+    if (\Drupal::moduleHandler()->moduleExists($module)) {
+      \Drupal::logger('localgov_workflows_notifications')->warning(
+        'The @title module is installed and this is incompatible with the Symfony Mailer module which has just been enabled. Please disable the conflicting module and review the sites email settings.',
+        ['@title' => $title]);
+      \Drupal::messenger()->addWarning(t(
+        'The @title module is installed and this is incompatible with the Symfony Mailer module which has just been enabled. Please disable the conflicting module and review the sites email settings.',
+        ['@title' => $title]));
+    }
+  }
+}

modules/localgov_workflows_notifications/localgov_workflows_notifications.links.action.yml

@@ -0,0 +1,5 @@
+localgov_service_contact.add_form:
+  title: 'Add service contact'
+  route_name: entity.localgov_service_contact.add_form
+  appears_on:
+    - entity.localgov_service_contact.collection

modules/localgov_workflows_notifications/localgov_workflows_notifications.links.contextual.yml

@@ -0,0 +1,10 @@
+entity.localgov_service_contact.edit_form:
+  route_name: entity.localgov_service_contact.edit_form
+  group: localgov_service_contact
+  title: 'Edit'
+
+entity.localgov_service_contact.delete_form:
+  route_name: entity.localgov_service_contact.delete_form
+  group: localgov_service_contact
+  title: 'Delete'
+  weight: 10

modules/localgov_workflows_notifications/localgov_workflows_notifications.links.menu.yml

@@ -0,0 +1,12 @@
+entity.localgov_service_contact.collection:
+  title: 'Service contacts'
+  description: 'List of service contacts.'
+  route_name: entity.localgov_service_contact.collection
+  parent: system.admin_content
+
+localgov_workflows_notifications.settings:
+  title: 'LocalGov workflow notifications'
+  description: 'Administer LocalGov workflow notifications'
+  parent: system.admin_config_workflow
+  route_name: localgov_workflows_notifications.settings
+  weight: 10

modules/localgov_workflows_notifications/localgov_workflows_notifications.links.task.yml

@@ -0,0 +1,18 @@
+entity.localgov_service_contact.view:
+  title: 'View'
+  route_name: entity.localgov_service_contact.canonical
+  base_route: entity.localgov_service_contact.canonical
+entity.localgov_service_contact.edit_form:
+  title: 'Edit'
+  route_name: entity.localgov_service_contact.edit_form
+  base_route: entity.localgov_service_contact.canonical
+entity.localgov_service_contact.delete_form:
+  title: 'Delete'
+  route_name: entity.localgov_service_contact.delete_form
+  base_route: entity.localgov_service_contact.canonical
+  weight: 10
+entity.localgov_service_contact.collection:
+  title: 'Service contacts'
+  route_name: entity.localgov_service_contact.collection
+  base_route: system.admin_content
+  weight: 10