feat: add question name to form answer output

* Resolves #2700

This allows to identify question from within the UI,
as the user can see the name assigned to a question to identify
it when using the submissions in external places like workflows.

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>

Author: susnux

docs/DataStructure.md

@@ -164,19 +164,21 @@ A submission-object describes a single submission by a user to a form.
 
 The actual answers of users on submission.
 
-| Property     | Type    | Restrictions  | Description                                     |
-| ------------ | ------- | ------------- | ----------------------------------------------- |
-| id           | Integer | unique        | An instance-wide unique id of the submission    |
-| submissionId | Integer |               | The id of the submission, the answer belongs to |
-| questionId   | Integer |               | The id of the question, the answer belongs to   |
-| text         | String  | max. 4096 ch. | The actual answer text, the user submitted      |
-
-```
+| Property     | Type    | Restrictions  | Description                                          |
+| ------------ | ------- | ------------- | ---------------------------------------------------- |
+| id           | Integer | unique        | An instance-wide unique id of the submission         |
+| submissionId | Integer |               | The id of the submission, the answer belongs to      |
+| questionId   | Integer |               | The id of the question, the answer belongs to        |
+| questionName | String  |               | The technical name that was assigned to the question |
+| text         | String  | max. 4096 ch. | The actual answer text, the user submitted           |
+
+```json
 {
-  "id": 5,
-  "submissionId": 5,
-  "questionId": 1,
-  "text": "Option 2"
+	"id": 5,
+	"submissionId": 5,
+	"questionId": 1,
+	"questionName": "preference",
+	"text": "Option 2"
 }
 ```
 

lib/Controller/ApiController.php

@@ -1172,10 +1172,24 @@ public function getSubmissions(int $formId, ?string $query = null, ?int $limit =
 			$submissions = $this->submissionService->getSubmissions($formId, $userId, $query, $limit, $offset);
 			$filteredSubmissionsCount = $this->submissionMapper->countSubmissions($formId, $userId, $query);
 		}
-		$questions = $this->formsService->getQuestions($formId);
+		$questions = [];
+		foreach ($this->formsService->getQuestions($formId) as $question) {
+			$questions[$question['id']] = $question;
+		}
+
 
 		// Append Display Names
-		$submissions = array_map(function (array $submission) {
+		$submissions = array_map(function (array $submission) use ($questions) {
+			if (!empty($submission['answers'])) {
+				$submission['answers'] = array_map(function (array $answer) use ($questions) {
+					$name = $questions[$answer['questionId']]['name'];
+					if ($name) {
+						$answer['questionName'] = $name;
+					}
+					return $answer;
+				}, $submission['answers']);
+			}
+
 			if (substr($submission['userId'], 0, 10) === 'anon-user-') {
 				// Anonymous User
 				// TRANSLATORS On Results when listing the single Responses to the form, this text is shown as heading of the Response.
@@ -1202,7 +1216,7 @@ public function getSubmissions(int $formId, ?string $query = null, ?int $limit =
 
 		$response = [
 			'submissions' => $submissions,
-			'questions' => $questions,
+			'questions' => array_values($questions),
 			'filteredSubmissionsCount' => $filteredSubmissionsCount,
 		];
 

lib/ResponseDefinitions.php

@@ -63,6 +63,7 @@
  *   submissionId: int,
  *   fileId: ?int,
  *   questionId: int,
+ *   questionName?: string,
  *   text: string
  * }
  *

openapi.json

@@ -58,6 +58,9 @@
                         "type": "integer",
                         "format": "int64"
                     },
+                    "questionName": {
+                        "type": "string"
+                    },
                     "text": {
                         "type": "string"
                     }

tests/Integration/Api/ApiV3Test.php

@@ -1117,6 +1117,7 @@ public function dataGetSubmissions() {
 									// 'questionId' => Checked dynamically
 									'text' => 'Option 1',
 									'fileId' => null,
+									'questionName' => 'city',
 								]
 							]
 						],
@@ -1137,6 +1138,7 @@ public function dataGetSubmissions() {
 									// 'questionId' => Checked dynamically
 									'text' => 'Option 2',
 									'fileId' => null,
+									'questionName' => 'city'
 								]
 							]
 						],
@@ -1384,10 +1386,12 @@ public function testNewSubmission() {
 					'questionId' => $this->testForms[0]['questions'][1]['id'],
 					'text' => 'Option 1',
 					'fileId' => null,
+					'questionName' => 'city',
 				],
 				[
 					'questionId' => $this->testForms[0]['questions'][2]['id'],
 					'text' => 'test.txt',
+					'questionName' => 'file',
 				],
 			]
 		], $data['submissions'][0]);

tests/Unit/Controller/ApiControllerTest.php

@@ -223,7 +223,7 @@ public function dataGetSubmissions() {
 				'submissions' => [
 					['userId' => 'anon-user-1']
 				],
-				'questions' => [['name' => 'questions']],
+				'questions' => [['id' => 1, 'name' => 'questions']],
 				'expected' => [
 					'submissions' => [
 						[
@@ -233,6 +233,7 @@ public function dataGetSubmissions() {
 					],
 					'questions' => [
 						[
+							'id' => 1,
 							'name' => 'questions',
 							'extraSettings' => new \stdClass(),
 						],
@@ -244,7 +245,7 @@ public function dataGetSubmissions() {
 				'submissions' => [
 					['userId' => 'jdoe']
 				],
-				'questions' => [['name' => 'questions']],
+				'questions' => [['id' => 1, 'name' => 'questions']],
 				'expected' => [
 					'submissions' => [
 						[
@@ -254,6 +255,7 @@ public function dataGetSubmissions() {
 					],
 					'questions' => [
 						[
+							'id' => 1,
 							'name' => 'questions',
 							'extraSettings' => new \stdClass(),
 						],