feat(forms): add respondent confirmation emails

Signed-off-by: Robert <61327381+QuiteBitter@users.noreply.github.com>

Author: QuiteBitter

docs/API_v3.md

@@ -436,7 +436,9 @@ Update a single or multiple properties of a question-object.
   | Parameter | Type | Description |
   |-----------|---------|-------------|
   | _keyValuePairs_ | Array | Array of key-value pairs to update |
-- Restrictions: It is **not allowed** to update one of the following key-value pairs: _id, formId, order_.
+- Restrictions:
+    - It is **not allowed** to update one of the following key-value pairs: _id, formId, order_.
+    - `extraSettings.confirmationRecipient` can only be enabled for short questions with `extraSettings.validationType` set to `email`.
 - Response: **Status-Code OK**, as well as the id of the updated question.
 
 ```
@@ -901,6 +903,7 @@ Store Submission to Database
     - An **array** of values as value --> Even for short Text Answers, wrapped into Array.
     - For Question-Types with pre-defined answers (`multiple`, `multiple_unique`, `dropdown`), the array contains the corresponding option-IDs.
     - For File-Uploads, the array contains the objects with key `uploadedFileId` (value from Upload a file endpoint).
+    - To send a respondent confirmation email, set the corresponding short question to `validationType = email` and `confirmationRecipient = true`.
 
 ```
   {

docs/DataStructure.md

@@ -240,6 +240,7 @@ Optional extra settings for some [Question Types](#question-types)
 | `optionsLimitMin`       | `multiple`                            | Integer          | -                                           | Minimum number of options that must be selected                             |
 | `validationType`        | `short`                               | string           | `null, 'phone', 'email', 'regex', 'number'` | Custom validation for checking a submission                                 |
 | `validationRegex`       | `short`                               | string           | regular expression                          | if `validationType` is 'regex' this defines the regular expression to apply |
+| `confirmationRecipient` | `short`                               | Boolean          | `true/false`                                | Marks an email question as recipient for respondent confirmation emails      |
 | `allowedFileTypes`      | `file`                                | Array of strings | `'image', 'x-office/document'`              | Allowed file types for file upload                                          |
 | `allowedFileExtensions` | `file`                                | Array of strings | `'jpg', 'png'`                              | Allowed file extensions for file upload                                     |
 | `maxAllowedFilesCount`  | `file`                                | Integer          | -                                           | Maximum number of files that can be uploaded, 0 means no limit              |

lib/AppInfo/Application.php

@@ -11,8 +11,10 @@
 
 use OCA\Analytics\Datasource\DatasourceEvent;
 use OCA\Forms\Capabilities;
+use OCA\Forms\Events\FormSubmittedEvent;
 use OCA\Forms\FormsMigrator;
 use OCA\Forms\Listener\AnalyticsDatasourceListener;
+use OCA\Forms\Listener\ConfirmationEmailListener;
 use OCA\Forms\Listener\UserDeletedListener;
 use OCA\Forms\Middleware\ThrottleFormAccessMiddleware;
 use OCA\Forms\Search\SearchProvider;
@@ -43,6 +45,7 @@ public function register(IRegistrationContext $context): void {
 
 		$context->registerCapability(Capabilities::class);
 		$context->registerEventListener(UserDeletedEvent::class, UserDeletedListener::class);
+		$context->registerEventListener(FormSubmittedEvent::class, ConfirmationEmailListener::class);
 		$context->registerEventListener(DatasourceEvent::class, AnalyticsDatasourceListener::class);
 		$context->registerMiddleware(ThrottleFormAccessMiddleware::class);
 		$context->registerSearchProvider(SearchProvider::class);

lib/Constants.php

@@ -149,6 +149,7 @@ class Constants {
 	public const EXTRA_SETTINGS_SHORT = [
 		'validationType' => ['string'],
 		'validationRegex' => ['string'],
+		'confirmationRecipient' => ['boolean'],
 	];
 
 	public const EXTRA_SETTINGS_FILE = [

lib/Controller/ApiController.php

@@ -22,6 +22,7 @@
 use OCA\Forms\Db\SubmissionMapper;
 use OCA\Forms\Db\UploadedFile;
 use OCA\Forms\Db\UploadedFileMapper;
+use OCA\Forms\Events\FormSubmittedEvent;
 use OCA\Forms\Exception\NoSuchFormException;
 use OCA\Forms\ResponseDefinitions;
 use OCA\Forms\Service\ConfigService;
@@ -546,6 +547,10 @@ public function newQuestion(int $formId, ?string $type = null, ?string $subtype
 			$questionData = $sourceQuestion->read();
 			unset($questionData['id']);
 			$questionData['order'] = end($allQuestions)->getOrder() + 1;
+			if (is_array($questionData['extraSettings'] ?? null)
+				&& ($questionData['extraSettings']['confirmationRecipient'] ?? false) === true) {
+				$questionData['extraSettings']['confirmationRecipient'] = false;
+			}
 
 			$newQuestion = Question::fromParams($questionData);
 			$this->questionMapper->insert($newQuestion);
@@ -648,6 +653,12 @@ public function updateQuestion(int $formId, int $questionId, array $keyValuePair
 		if (key_exists('extraSettings', $keyValuePairs) && !$this->formsService->areExtraSettingsValid($keyValuePairs['extraSettings'], $question->getType())) {
 			throw new OCSBadRequestException('Invalid extraSettings, will not update.');
 		}
+		$this->assertSingleConfirmationRecipientQuestion(
+			$formId,
+			$questionId,
+			$question->getType(),
+			is_array($keyValuePairs['extraSettings'] ?? null) ? $keyValuePairs['extraSettings'] : null,
+		);
 
 		// Create QuestionEntity with given Params & Id.
 		$question = Question::fromParams($keyValuePairs);
@@ -1405,7 +1416,7 @@ public function newSubmission(int $formId, array $answers, string $shareHash = '
 		$this->formMapper->update($form);
 
 		//Create Activity
-		$this->formsService->notifyNewSubmission($form, $submission);
+		$this->formsService->notifyNewSubmission($form, $submission, FormSubmittedEvent::TRIGGER_CREATED);
 
 		if ($form->getFileId() !== null) {
 			$this->jobList->add(SyncSubmissionsWithLinkedFileJob::class, ['form_id' => $form->getId()]);
@@ -1487,7 +1498,7 @@ public function updateSubmission(int $formId, int $submissionId, array $answers)
 		}
 
 		//Create Activity
-		$this->formsService->notifyNewSubmission($form, $submission);
+		$this->formsService->notifyNewSubmission($form, $submission, FormSubmittedEvent::TRIGGER_UPDATED);
 
 		return new DataResponse($submissionId);
 	}
@@ -1827,6 +1838,32 @@ private function checkAccessUpdate(array $keyValuePairs): void {
 		}
 	}
 
+	/**
+	 * Ensure only one short-email question can be used as confirmation recipient in a form.
+	 *
+	 * @param array<string, mixed>|null $extraSettings
+	 */
+	private function assertSingleConfirmationRecipientQuestion(int $formId, int $questionId, string $questionType, ?array $extraSettings): void {
+		if ($questionType !== Constants::ANSWER_TYPE_SHORT || !is_array($extraSettings) || ($extraSettings['confirmationRecipient'] ?? false) !== true) {
+			return;
+		}
+
+		$formQuestions = $this->questionMapper->findByForm($formId);
+		foreach ($formQuestions as $formQuestion) {
+			if ($formQuestion->getId() === $questionId) {
+				continue;
+			}
+
+			$existingSettings = $formQuestion->getExtraSettings();
+			$isExistingConfirmationRecipient = $formQuestion->getType() === Constants::ANSWER_TYPE_SHORT
+				&& ($existingSettings['validationType'] ?? null) === 'email'
+				&& ($existingSettings['confirmationRecipient'] ?? false) === true;
+			if ($isExistingConfirmationRecipient) {
+				throw new OCSBadRequestException('Only one confirmation recipient question is allowed per form');
+			}
+		}
+	}
+
 	/**
 	 * Checks if the current user is allowed to archive/unarchive the form
 	 */

lib/Events/FormSubmittedEvent.php

@@ -11,17 +11,34 @@
 use OCA\Forms\Db\Submission;
 
 class FormSubmittedEvent extends AbstractFormEvent {
+	public const TRIGGER_CREATED = 'created';
+	public const TRIGGER_UPDATED = 'updated';
+
 	public function __construct(
 		Form $form,
 		private Submission $submission,
+		private string $trigger = self::TRIGGER_CREATED,
 	) {
 		parent::__construct($form);
 	}
 
+	public function getSubmission(): Submission {
+		return $this->submission;
+	}
+
+	public function getTrigger(): string {
+		return $this->trigger;
+	}
+
+	public function isNewSubmission(): bool {
+		return $this->trigger === self::TRIGGER_CREATED;
+	}
+
 	public function getWebhookSerializable(): array {
 		return [
 			'form' => $this->form->read(),
 			'submission' => $this->submission->read(),
+			'trigger' => $this->trigger,
 		];
 	}
 }

lib/Listener/ConfirmationEmailListener.php

@@ -0,0 +1,106 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Forms\Listener;
+
+use OCA\Forms\Constants;
+use OCA\Forms\Db\AnswerMapper;
+use OCA\Forms\Db\QuestionMapper;
+use OCA\Forms\Events\FormSubmittedEvent;
+use OCA\Forms\Service\ConfirmationMailService;
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\EventDispatcher\Event;
+use OCP\EventDispatcher\IEventListener;
+use Psr\Log\LoggerInterface;
+
+/**
+ * @implements IEventListener<FormSubmittedEvent>
+ */
+class ConfirmationEmailListener implements IEventListener {
+	public function __construct(
+		private ConfirmationMailService $confirmationMailService,
+		private AnswerMapper $answerMapper,
+		private QuestionMapper $questionMapper,
+		private LoggerInterface $logger,
+	) {
+	}
+
+	public function handle(Event $event): void {
+		if (!($event instanceof FormSubmittedEvent)) {
+			return;
+		}
+		if (!$event->isNewSubmission()) {
+			return;
+		}
+
+		$submission = $event->getSubmission();
+		$form = $event->getForm();
+
+		$emailAddress = null;
+		$answerSummaries = [];
+		try {
+			$answers = $this->answerMapper->findBySubmission($submission->getId());
+		} catch (DoesNotExistException $e) {
+			return;
+		}
+		$hasAmbiguousRecipients = false;
+
+		foreach ($answers as $answer) {
+			try {
+				$question = $this->questionMapper->findById($answer->getQuestionId());
+			} catch (DoesNotExistException $e) {
+				$this->logger->warning('Question missing while preparing confirmation mail', [
+					'formId' => $form->getId(),
+					'submissionId' => $submission->getId(),
+					'questionId' => $answer->getQuestionId(),
+				]);
+				continue;
+			}
+
+			$questionType = $question->getType();
+			$answerText = trim($answer->getText() ?? '');
+
+			$extraSettings = $question->getExtraSettings();
+			$isEmailQuestion = $questionType === Constants::ANSWER_TYPE_SHORT
+				&& (($extraSettings['validationType'] ?? null) === 'email');
+			$isConfirmationRecipient = ($extraSettings['confirmationRecipient'] ?? false) === true;
+
+			if ($answerText !== '' && $isEmailQuestion && $isConfirmationRecipient) {
+				if ($emailAddress !== null && !hash_equals($emailAddress, $answerText)) {
+					$hasAmbiguousRecipients = true;
+					break;
+				}
+				$emailAddress = $answerText;
+			}
+
+			if (
+				$answerText !== ''
+				&& in_array($questionType, [Constants::ANSWER_TYPE_SHORT, Constants::ANSWER_TYPE_LONG], true)
+			) {
+				$answerSummaries[] = [
+					'question' => $question->getText(),
+					'answer' => $answerText,
+				];
+			}
+		}
+		if ($hasAmbiguousRecipients) {
+			$this->logger->warning('Skipping confirmation mail because multiple confirmation recipient questions were answered', [
+				'formId' => $form->getId(),
+				'submissionId' => $submission->getId(),
+			]);
+			return;
+		}
+
+		if ($emailAddress === null) {
+			return;
+		}
+
+		$this->confirmationMailService->send($form, $submission, $emailAddress, $answerSummaries);
+	}
+}

lib/ResponseDefinitions.php

@@ -40,6 +40,7 @@
  *   timeRange?: bool,
  *   validationRegex?: string,
  *   validationType?: string,
+ *   confirmationRecipient?: bool,
  *   questionType?: string,
  * }
  *
@@ -110,7 +111,6 @@
  *   state: int,
  *   lockedBy: ?string,
  *   lockedUntil: ?int,
- *   maxSubmissions: ?int,
  * }
  *
  * @psalm-type FormsForm = array{
@@ -126,7 +126,6 @@
  *   fileId: ?int,
  *   filePath?: ?string,
  *   isAnonymous: bool,
- *   isMaxSubmissionsReached: bool,
  *   lastUpdated: int,
  *   submitMultiple: bool,
  *   allowEditSubmissions: bool,
@@ -137,7 +136,6 @@
  *   state: 0|1|2,
  *   lockedBy: ?string,
  *   lockedUntil: ?int,
- *   maxSubmissions: ?int,
  *   shares: list<FormsShare>,
  *   submissionCount?: int,
  *   submissionMessage: ?string,