feat(forms): attach submission PDFs to notification emails

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,
+  "attachSubmissionPdf": false,
   "notificationRecipients": ["team@example.com"],
   "showExpiration": false,
   "canSubmit": true,
@@ -278,6 +279,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.
+    - `attachSubmissionPdf` 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                           |
+| attachSubmissionPdf  | Boolean                              |                                         | If notification emails should include a PDF attachment with the submitted responses                                              |
 | 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                                                                                           |
@@ -70,6 +71,7 @@ This document describes the Object-Structure, that is used within the Forms App
   "submissionCount": 0,
   "submissionMessage": "string",
   "notifyOwnerOnSubmission": false,
+  "attachSubmissionPdf": false,
   "notificationRecipients": ["team@example.com"]
 }
 ```

lib/Controller/ApiController.php

@@ -185,6 +185,7 @@ public function newForm(?int $fromId = null): DataResponse {
 			$form->setIsAnonymous(false);
 			$form->setNotifyOwnerOnSubmission(false);
 			$form->setState(Constants::FORM_STATE_ACTIVE);
+			$form->setAttachSubmissionPdf(false);
 			$form->setNotificationRecipients([]);
 
 			$this->formMapper->insert($form);
@@ -216,6 +217,7 @@ public function newForm(?int $fromId = null): DataResponse {
 			$formData['isAnonymous'] = false;
 			$formData['notifyOwnerOnSubmission'] = false;
 			$formData['state'] = Constants::FORM_STATE_ACTIVE;
+			$formData['attachSubmissionPdf'] = false;
 			$formData['notificationRecipients'] = [];
 
 			$form = Form::fromParams($formData);
@@ -331,6 +333,10 @@ public function updateForm(int $formId, array $keyValuePairs): DataResponse {
 			throw new OCSBadRequestException('notifyOwnerOnSubmission must be a boolean');
 		}
 
+		if (isset($keyValuePairs['attachSubmissionPdf']) && !is_bool($keyValuePairs['attachSubmissionPdf'])) {
+			throw new OCSBadRequestException('attachSubmissionPdf must be a boolean');
+		}
+
 		if (array_key_exists('notificationRecipients', $keyValuePairs)) {
 			$keyValuePairs['notificationRecipients'] = $this->normalizeNotificationRecipients($keyValuePairs['notificationRecipients']);
 		}

lib/Db/Form.php

@@ -45,6 +45,8 @@
  * @method void setSubmissionMessage(string|null $value)
  * @method bool getNotifyOwnerOnSubmission()
  * @method void setNotifyOwnerOnSubmission(bool $value)
+ * @method bool getAttachSubmissionPdf()
+ * @method void setAttachSubmissionPdf(bool $value)
  * @method string|null getNotificationRecipientsJson()
  * @method void setNotificationRecipientsJson(?string $value)
  * @method int getState()
@@ -74,6 +76,7 @@ class Form extends Entity {
 	protected $showExpiration;
 	protected $submissionMessage;
 	protected $notifyOwnerOnSubmission;
+	protected $attachSubmissionPdf;
 	protected $notificationRecipientsJson;
 	protected $lastUpdated;
 	protected $state;
@@ -92,6 +95,7 @@ public function __construct() {
 		$this->addType('allowEditSubmissions', 'boolean');
 		$this->addType('showExpiration', 'boolean');
 		$this->addType('notifyOwnerOnSubmission', 'boolean');
+		$this->addType('attachSubmissionPdf', 'boolean');
 		$this->addType('lastUpdated', 'integer');
 		$this->addType('state', 'integer');
 		$this->addType('lockedBy', 'string');
@@ -199,6 +203,7 @@ public function setNotificationRecipients(array $recipients): void {
 	 *   lastUpdated: int,
 	 *   submissionMessage: ?string,
 	 *   notifyOwnerOnSubmission: bool,
+	 *   attachSubmissionPdf: bool,
 	 *   notificationRecipients: list<string>,
 	 *   state: 0|1|2,
 	 *   lockedBy: ?string,
@@ -225,6 +230,7 @@ public function read() {
 			'lastUpdated' => (int)$this->getLastUpdated(),
 			'submissionMessage' => $this->getSubmissionMessage(),
 			'notifyOwnerOnSubmission' => (bool)$this->getNotifyOwnerOnSubmission(),
+			'attachSubmissionPdf' => (bool)$this->getAttachSubmissionPdf(),
 			'notificationRecipients' => $this->getNotificationRecipients(),
 			'state' => $this->getState(),
 			'lockedBy' => $this->getLockedBy(),

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->setAttachSubmissionPdf($formData['attachSubmissionPdf'] ?? false);
 				$form->setNotificationRecipients($formData['notificationRecipients'] ?? []);
 
 				$this->formMapper->insert($form);

lib/Listener/OwnerNotificationListener.php

@@ -68,6 +68,7 @@ public function handle(Event $event): void {
 		}
 
 		$answerSummaries = [];
+		$pdfAnswerEntries = [];
 		try {
 			$answers = $this->answerMapper->findBySubmission($submission->getId());
 		} catch (DoesNotExistException $e) {
@@ -87,6 +88,12 @@ public function handle(Event $event): void {
 
 			$questionType = $question->getType();
 			$answerText = trim($answer->getText() ?? '');
+			if ($answerText !== '') {
+				$pdfAnswerEntries[] = [
+					'question' => $question->getText(),
+					'answer' => $answerText,
+				];
+			}
 			if (
 				$answerText !== ''
 				&& in_array($questionType, [Constants::ANSWER_TYPE_SHORT, Constants::ANSWER_TYPE_LONG], true)
@@ -103,6 +110,7 @@ public function handle(Event $event): void {
 			$submission,
 			array_values($normalizedRecipients),
 			$answerSummaries,
+			$pdfAnswerEntries,
 		);
 	}
 }

lib/Migration/Version050300Date20260228190000.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Forms\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+class Version050300Date20260228190000 extends SimpleMigrationStep {
+
+	/**
+	 * @param IOutput $output
+	 * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+
+		$formsTable = $schema->getTable('forms_v2_forms');
+		if (!$formsTable->hasColumn('attach_submission_pdf')) {
+			$formsTable->addColumn('attach_submission_pdf', Types::BOOLEAN, [
+				'notnull' => false,
+				'default' => false,
+			]);
+		}
+
+		return $schema;
+	}
+}

lib/ResponseDefinitions.php

@@ -142,6 +142,7 @@
  *   submissionCount?: int,
  *   submissionMessage: ?string,
  *   notifyOwnerOnSubmission: bool,
+ *   attachSubmissionPdf: bool,
  *   notificationRecipients: list<string>,
  * }
  *

lib/Service/OwnerNotificationMailService.php

@@ -22,15 +22,17 @@ public function __construct(
 		private IMailer $mailer,
 		private IL10N $l10n,
 		private IURLGenerator $urlGenerator,
+		private SubmissionPdfService $submissionPdfService,
 		private LoggerInterface $logger,
 	) {
 	}
 
 	/**
 	 * @param list<string> $recipients
 	 * @param array<int, array{question: string, answer: string}> $answerSummaries
+	 * @param array<int, array{question: string, answer: string}> $pdfAnswerEntries
 	 */
-	public function send(Form $form, Submission $submission, array $recipients, array $answerSummaries = []): void {
+	public function send(Form $form, Submission $submission, array $recipients, array $answerSummaries = [], array $pdfAnswerEntries = []): void {
 		$validRecipients = array_values(array_unique(array_filter($recipients, fn (string $recipient): bool => $this->mailer->validateMailAddress($recipient))));
 		if ($validRecipients === []) {
 			return;
@@ -77,6 +79,16 @@ public function send(Form $form, Submission $submission, array $recipients, arra
 			$message->setSubject($subject);
 			$message->setTo($validRecipients);
 			$message->useTemplate($emailTemplate);
+			if ($form->getAttachSubmissionPdf()) {
+				$entriesForPdf = $pdfAnswerEntries !== [] ? $pdfAnswerEntries : $answerSummaries;
+				$message->attach(
+					$this->mailer->createAttachment(
+						$this->submissionPdfService->createPdf($form, $submission, $entriesForPdf),
+						$this->submissionPdfService->createFilename($form, $submission),
+						'application/pdf',
+					),
+				);
+			}
 
 			$this->mailer->send($message);
 		} catch (\Throwable $e) {