feat(forms): add external notification recipients

Signed-off-by: Robert <robert@local>

Author: Robert

docs/API_v3.md

@@ -171,6 +171,7 @@ Returns the full-depth object of the requested form (without submissions).
   "submitMultiple": true,
   "allowEditSubmissions": false,
   "notifyOwnerOnSubmission": false,
+  "notificationRecipients": ["team@example.com"],
   "showExpiration": false,
   "canSubmit": true,
   "state": 0,
@@ -277,6 +278,7 @@ Update a single or multiple properties of a form-object. Concerns **only** the F
     - To link a file for submissions, the _keyValuePairs_ need to contain the keys `path` and `fileFormat`
     - To unlink a file for submissions, the _keyValuePairs_ need to contain the keys `fileId` and `fileFormat` need to contain the value `null`
     - `notifyOwnerOnSubmission` must be a boolean.
+    - `notificationRecipients` must be an array of valid email addresses.
 - Response: **Status-Code OK**, as well as the id of the updated form.
 
 ```

docs/DataStructure.md

@@ -22,6 +22,7 @@ This document describes the Object-Structure, that is used within the Forms App
 | ownerId              | String                               |                                         | The nextcloud userId of the form owner                                                                                           |
 | submissionMessage    | String                               | max. 2048 ch.                           | Optional custom message, with Markdown support, to be shown to users when the form is submitted (default is used if set to null) |
 | notifyOwnerOnSubmission | Boolean                           |                                         | If the form owner should receive an email notification with a response summary for each new submission                           |
+| notificationRecipients | Array of Strings                   |                                         | Additional email recipients to notify for each new submission, independent of `notifyOwnerOnSubmission`                         |
 | created              | unix timestamp                       |                                         | When the form has been created                                                                                                   |
 | access               | [Access-Object](#access-object)      |                                         | Describing access-settings of the form                                                                                           |
 | expires              | unix-timestamp                       |                                         | When the form should expire. Timestamp `0` indicates _never_                                                                     |
@@ -68,7 +69,8 @@ This document describes the Object-Structure, that is used within the Forms App
   "submissions": [],
   "submissionCount": 0,
   "submissionMessage": "string",
-  "notifyOwnerOnSubmission": false
+  "notifyOwnerOnSubmission": false,
+  "notificationRecipients": ["team@example.com"]
 }
 ```
 

lib/Controller/ApiController.php

@@ -53,6 +53,7 @@
 use OCP\IUser;
 use OCP\IUserManager;
 use OCP\IUserSession;
+use OCP\Mail\IMailer;
 
 use Psr\Log\LoggerInterface;
 
@@ -69,6 +70,8 @@
  * @psalm-import-type FormsUploadedFile from ResponseDefinitions
  */
 class ApiController extends OCSController {
+	private const MAX_NOTIFICATION_RECIPIENTS = 20;
+
 	private ?IUser $currentUser;
 
 	public function __construct(
@@ -91,6 +94,7 @@ public function __construct(
 		private UploadedFileMapper $uploadedFileMapper,
 		private IMimeTypeDetector $mimeTypeDetector,
 		private IJobList $jobList,
+		private IMailer $mailer,
 	) {
 		parent::__construct($appName, $request);
 		$this->currentUser = $userSession->getUser();
@@ -181,6 +185,7 @@ public function newForm(?int $fromId = null): DataResponse {
 			$form->setIsAnonymous(false);
 			$form->setNotifyOwnerOnSubmission(false);
 			$form->setState(Constants::FORM_STATE_ACTIVE);
+			$form->setNotificationRecipients([]);
 
 			$this->formMapper->insert($form);
 		} else {
@@ -211,6 +216,7 @@ public function newForm(?int $fromId = null): DataResponse {
 			$formData['isAnonymous'] = false;
 			$formData['notifyOwnerOnSubmission'] = false;
 			$formData['state'] = Constants::FORM_STATE_ACTIVE;
+			$formData['notificationRecipients'] = [];
 
 			$form = Form::fromParams($formData);
 			$this->formMapper->insert($form);
@@ -325,6 +331,10 @@ public function updateForm(int $formId, array $keyValuePairs): DataResponse {
 			throw new OCSBadRequestException('notifyOwnerOnSubmission must be a boolean');
 		}
 
+		if (array_key_exists('notificationRecipients', $keyValuePairs)) {
+			$keyValuePairs['notificationRecipients'] = $this->normalizeNotificationRecipients($keyValuePairs['notificationRecipients']);
+		}
+
 		// Process file linking
 		if (isset($keyValuePairs['path']) && isset($keyValuePairs['fileFormat'])) {
 			$file = $this->submissionService->writeFileToCloud($form, $keyValuePairs['path'], $keyValuePairs['fileFormat']);
@@ -1836,6 +1846,42 @@ private function checkAccessUpdate(array $keyValuePairs): void {
 		}
 	}
 
+	/**
+	 * @param mixed $notificationRecipients
+	 * @return list<string>
+	 */
+	private function normalizeNotificationRecipients(mixed $notificationRecipients): array {
+		if (!is_array($notificationRecipients)) {
+			throw new OCSBadRequestException('notificationRecipients must be an array');
+		}
+
+		$normalizedRecipients = [];
+		foreach ($notificationRecipients as $recipient) {
+			if (!is_string($recipient)) {
+				throw new OCSBadRequestException('notificationRecipients must be an array of strings');
+			}
+
+			$trimmedRecipient = trim($recipient);
+			if ($trimmedRecipient === '') {
+				continue;
+			}
+
+			if (!$this->mailer->validateMailAddress($trimmedRecipient)) {
+				throw new OCSBadRequestException('notificationRecipients contains an invalid email address');
+			}
+
+			$recipientKey = strtolower($trimmedRecipient);
+			if (!isset($normalizedRecipients[$recipientKey])) {
+				$normalizedRecipients[$recipientKey] = $trimmedRecipient;
+			}
+		}
+
+		if (count($normalizedRecipients) > self::MAX_NOTIFICATION_RECIPIENTS) {
+			throw new OCSBadRequestException('Too many notificationRecipients');
+		}
+
+		return array_values($normalizedRecipients);
+	}
 	/**
 	 * Checks if the current user is allowed to archive/unarchive the form
 	 */

lib/Db/Form.php

@@ -45,6 +45,8 @@
  * @method void setSubmissionMessage(string|null $value)
  * @method bool getNotifyOwnerOnSubmission()
  * @method void setNotifyOwnerOnSubmission(bool $value)
+ * @method string|null getNotificationRecipientsJson()
+ * @method void setNotificationRecipientsJson(?string $value)
  * @method int getState()
  * @psalm-method 0|1|2 getState()
  * @method void setState(int|null $value)
@@ -72,6 +74,7 @@ class Form extends Entity {
 	protected $showExpiration;
 	protected $submissionMessage;
 	protected $notifyOwnerOnSubmission;
+	protected $notificationRecipientsJson;
 	protected $lastUpdated;
 	protected $state;
 	protected $lockedBy;
@@ -146,6 +149,37 @@ public function setAccess(array $access): void {
 		$this->setAccessEnum($value);
 	}
 
+	/**
+	 * @return list<string>
+	 */
+	public function getNotificationRecipients(): array {
+		$encodedRecipients = $this->getNotificationRecipientsJson();
+		if ($encodedRecipients === null || $encodedRecipients === '') {
+			return [];
+		}
+
+		$decodedRecipients = json_decode($encodedRecipients, true, 512, JSON_THROW_ON_ERROR);
+		if (!is_array($decodedRecipients)) {
+			return [];
+		}
+
+		return array_values(array_filter(array_map(static fn (mixed $recipient): string => trim((string)$recipient), $decodedRecipients), static fn (string $recipient): bool => $recipient !== ''));
+	}
+
+	/**
+	 * @param list<string> $recipients
+	 */
+	public function setNotificationRecipients(array $recipients): void {
+		$normalizedRecipients = array_values(array_filter(array_map(static fn (string $recipient): string => trim($recipient), $recipients), static fn (string $recipient): bool => $recipient !== ''));
+
+		if ($normalizedRecipients === []) {
+			$this->setNotificationRecipientsJson(null);
+			return;
+		}
+
+		$this->setNotificationRecipientsJson(json_encode($normalizedRecipients, JSON_THROW_ON_ERROR));
+	}
+
 	/**
 	 * @return array{
 	 *   id: int,
@@ -165,6 +199,7 @@ public function setAccess(array $access): void {
 	 *   lastUpdated: int,
 	 *   submissionMessage: ?string,
 	 *   notifyOwnerOnSubmission: bool,
+	 *   notificationRecipients: list<string>,
 	 *   state: 0|1|2,
 	 *   lockedBy: ?string,
 	 *   lockedUntil: ?int,
@@ -190,6 +225,7 @@ public function read() {
 			'lastUpdated' => (int)$this->getLastUpdated(),
 			'submissionMessage' => $this->getSubmissionMessage(),
 			'notifyOwnerOnSubmission' => (bool)$this->getNotifyOwnerOnSubmission(),
+			'notificationRecipients' => $this->getNotificationRecipients(),
 			'state' => $this->getState(),
 			'lockedBy' => $this->getLockedBy(),
 			'lockedUntil' => $this->getLockedUntil(),

lib/FormsMigrator.php

@@ -149,6 +149,7 @@ public function import(IUser $user, IImportSource $importSource, OutputInterface
 				$form->setAllowEditSubmissions($formData['allowEditSubmissions']);
 				$form->setShowExpiration($formData['showExpiration']);
 				$form->setNotifyOwnerOnSubmission($formData['notifyOwnerOnSubmission'] ?? false);
+				$form->setNotificationRecipients($formData['notificationRecipients'] ?? []);
 
 				$this->formMapper->insert($form);
 

lib/Listener/OwnerNotificationListener.php

@@ -42,14 +42,28 @@ public function handle(Event $event): void {
 		}
 
 		$form = $event->getForm();
-		if (!$form->getNotifyOwnerOnSubmission()) {
-			return;
+		$submission = $event->getSubmission();
+		$recipients = $form->getNotificationRecipients();
+
+		if ($form->getNotifyOwnerOnSubmission()) {
+			$owner = $this->userManager->get($form->getOwnerId());
+			$ownerMail = $owner?->getEMailAddress();
+			if (is_string($ownerMail) && trim($ownerMail) !== '') {
+				$recipients[] = trim($ownerMail);
+			}
 		}
 
-		$submission = $event->getSubmission();
-		$owner = $this->userManager->get($form->getOwnerId());
-		$ownerMail = trim((string)$owner?->getEMailAddress());
-		if ($ownerMail === '') {
+		$normalizedRecipients = [];
+		foreach ($recipients as $recipient) {
+			$trimmedRecipient = trim($recipient);
+			if ($trimmedRecipient === '') {
+				continue;
+			}
+
+			$normalizedRecipients[strtolower($trimmedRecipient)] = $trimmedRecipient;
+		}
+
+		if ($normalizedRecipients === []) {
 			return;
 		}
 
@@ -87,7 +101,7 @@ public function handle(Event $event): void {
 		$this->ownerNotificationMailService->send(
 			$form,
 			$submission,
-			[$ownerMail],
+			array_values($normalizedRecipients),
 			$answerSummaries,
 		);
 	}

lib/Migration/Version050300Date20260228170000.php

@@ -35,6 +35,13 @@ public function changeSchema(IOutput $output, Closure $schemaClosure, array $opt
 			]);
 		}
 
+		if (!$formsTable->hasColumn('notification_recipients_json')) {
+			$formsTable->addColumn('notification_recipients_json', Types::TEXT, [
+				'notnull' => false,
+				'default' => null,
+			]);
+		}
+
 		return $schema;
 	}
 }

lib/ResponseDefinitions.php

@@ -142,6 +142,7 @@
  *   submissionCount?: int,
  *   submissionMessage: ?string,
  *   notifyOwnerOnSubmission: bool,
+ *   notificationRecipients: list<string>,
  * }
  *
  * @psalm-type FormsUploadedFile = array{

lib/Service/FormsService.php

@@ -285,6 +285,7 @@ public function getPublicForm(Form $form): array {
 		unset($formData['filePath']);
 		unset($formData['fileFormat']);
 		unset($formData['notifyOwnerOnSubmission']);
+		unset($formData['notificationRecipients']);
 
 		return $formData;
 	}

openapi.json

@@ -120,7 +120,8 @@
                     "maxSubmissions",
                     "shares",
                     "submissionMessage",
-                    "notifyOwnerOnSubmission"
+                    "notifyOwnerOnSubmission",
+                    "notificationRecipients"
                 ],
                 "properties": {
                     "id": {
@@ -236,6 +237,12 @@
                     },
                     "notifyOwnerOnSubmission": {
                         "type": "boolean"
+                    },
+                    "notificationRecipients": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
                     }
                 }
             },