Simplify interface for getting user response from template (#7952)

Signed-off-by: freddidierRTE <[email protected]>

Author: freddidierRTE

config/docker/externalJs/CustomScreenExample.js

@@ -120,7 +120,7 @@
                     const responseCards = [];
                     const responseData = { "choice1": ["on"], "choice2": ["on"], "choice3": ["on"] }
                     cards.forEach((card) => {
-                        responseCards.push({ responseCardData: responseData });
+                        responseCards.push({ data: responseData });
                     });
                     return { valid: true, errorMsg: '', responseCards: responseCards };
                 }
@@ -132,7 +132,7 @@
                     const responseCards = [];
                     const responseData = {}
                     cards.forEach((card) => {
-                        responseCards.push({ responseCardData: responseData });
+                        responseCards.push({ data: responseData });
                     });
                     return { valid: true, errorMsg: '', responseCards: responseCards };
                 }

src/docs/asciidoc/reference_doc/response_cards.adoc

@@ -1,4 +1,4 @@
-// Copyright (c) 2018-2024 RTE (http://www.rte-france.com)
+// Copyright (c) 2018-2025 RTE (http://www.rte-france.com)
 // See AUTHORS.txt
 // This document is subject to the terms of the Creative Commons Attribution 4.0 International license.
 // If a copy of the license was not distributed with this
@@ -121,17 +121,18 @@ which returns an object containing the following fields :
 
 - valid (_boolean_) : true if the user input is valid
 - errorMsg (_string_) : message in case of invalid user input. If valid is true this field is not necessary.
-- responseCardData (_any_) : the user input to send in the data field of the child card. If valid is false this field is not necessary.
-- responseState : name of the response state to use. This field is not mandatory, if it is not set the state defined in
+- responseCard: 
+    * data (_any_) : the user input to send in the data field of the child card.
+    * state : name of the response state to use. This field is not mandatory, if it is not set the state defined in
 `config.json` will be used for the response.
-- publisher (_string_) : the id of the Entity to be used as publisher of the response. This field is not mandatory, if it is not set the publisher will be the user entity, in case the user belongs to a single entity, or it will be choosen by the user between his available entities.  
-- actions (_string array_) : an optional field used to define a set of predetermined actions that will be executed upon receiving the response card. The available actions include:
-      * PROPAGATE_READ_ACK_TO_PARENT_CARD : when receiving the child card, the status of the parent card should be considered as 'unread' and 'not acknowledged' until the user reads or acknowledge it again.
+    * publisher (_string_) : the id of the Entity to be used as publisher of the response. This field is not mandatory, if it is not set the publisher will be the user entity, in case the user belongs to a single entity, or it will be choosen by the user between his available entities.  
+    * actions (_string array_) : an optional field used to define a set of predetermined actions that will be executed upon receiving the response card. The available actions include:
+      ** PROPAGATE_READ_ACK_TO_PARENT_CARD : when receiving the child card, the status of the parent card should be considered as 'unread' and 'not acknowledged' until the user reads or acknowledge it again.
 
 
 This method is to be registered via `opfab.currentCard.registerFunctionToGetUserResponse`, the method will be called by OperatorFabric when the user clicks on the button to send the response.
 
-In the example below, the `getUserResponse` creates a `responseCardData` object by retrieving the user's inputs from the HTML.
+In the example below, the `getUserResponse` creates a `responseCard` object by retrieving the user's inputs from the HTML.
 In addition, if the user chose several options, it overrides the response state defined in the `config.json` with another
 state.
 

src/docs/asciidoc/reference_doc/ui_api.adoc

@@ -721,17 +721,17 @@ FilterModel object has the following fields:
 It is possible to respond to a card from the template by calling the following function (instead of using the "send response" button) : 
 
 ```
-opfab.cards.sendResponseCard(parentCard,responseData).then(...);
+opfab.cards.sendResponseCard(parentCard,responseCard).then(...);
 ```
 The function returns a `Promise<void>`. The promise will be resolved when the response is sent and rejected with an error message if an error occurs.
 
 The `parentCard` parameter is the parent card object (can be obtained from the current card object).
 
-The `responseData` object has the following fields:
+The `responseCard` object has the following fields:
 
-- `responseCardData`: The data field to include in the response card.
+- `data`: The data field to include in the response card.
 - `actions`: The actions field value for the response card. This field is optional.
-- `responseState`: The state field value for the response card. This field is optional (default value is defined in the state process definition).
+- `state`: The state field value for the response card. This field is optional (default value is defined in the state process definition).
 - `publisher`: The publisher field value for the response card. This field is optional (default value is the first current user entity that is allowed to respond).
 
 

src/docs/asciidoc/reference_doc/ui_customization.adoc

@@ -435,7 +435,7 @@ To do this, add a `responseButtons` array to the custom screen object. Each butt
 - `getUserResponses: A function that takes an array of cards as a parameter and returns an object containing the following fields:
   - `valid`: A boolean indicating if the action is valid.
   - `errorMsg`: An error message to display if the action is not valid.
-  - `responseCards`: An array of response cards to send with the following structure with a `responseCardData` field containing the response card data field.
+  - `responseCards`: An array of response cards to send with a `data` field containing the response card data field.
 
 
 
@@ -456,7 +456,7 @@ const customScreenExample = {
                     const responseCards = [];
                     const responseData = { "choice1": ["on"], "choice2": ["on"], "choice3": ["on"] }
                     cards.forEach((card) => {
-                        responseCards.push({ responseCardData: responseData });
+                        responseCards.push({ data: responseData });
                     });
                     return { valid: true, errorMsg: '', responseCards: responseCards };
                 }
@@ -468,7 +468,7 @@ const customScreenExample = {
                     const responseCards = [];
                     const responseData = {}
                     cards.forEach((card) => {
-                        responseCards.push({ responseCardData: responseData });
+                        responseCards.push({ data: responseData });
                     });
                     return { valid: true, errorMsg: '', responseCards: responseCards };
                 }

src/docs/asciidoc/resources/migration_guide_to_4.7.adoc

@@ -11,3 +11,41 @@
 
 A new setting to activate or not the templating of emails has been added in the settings screen of the user.
 This setting can be hidden in the configuration file of the web-ui by the field "settings.settingsScreen.hiddenSettings" by adding the value "disableCardContentInEmails".
+
+
+== Response card 
+
+The object that should be returned by the method registered via `opfab.currentCard.registerFunctionToGetUserResponse` is to be changed.
+
+Previously, the object was structured as follows:
+
+----
+{
+    valid: true/false,
+    errorMsg: string,
+    responseCardData: string,
+    responseState: string,
+    publisher: string,
+    actions: [string]
+}
+----
+
+Now, all elements related to the response card are encapsulated within a `responseCard` object:
+
+----
+{
+    valid: true/false,
+    errorMsg: string,
+    responseCard: {
+        data: string,
+        state: string,
+        publisher: string,
+        actions: [string]
+    }
+}
+----
+
+Note that the `responseState` field has been renamed to `state`.
+
+The old structure will be supported as a fallback for a limited time, it is recommended to update your code to use the new structure.
+`

src/test/resources/bundles/conferenceAndITIncidentExample/template/incidentInProgress.handlebars

@@ -1,4 +1,4 @@
-<!-- Copyright (c) 2020-2023, RTE (http://www.rte-france.com)              -->
+<!-- Copyright (c) 2020-2025, RTE (http://www.rte-france.com)              -->
 <!-- See AUTHORS.txt                                                       -->
 <!-- This Source Code Form is subject to the terms of the Mozilla Public   -->
 <!-- License, v. 2.0. If a copy of the MPL was not distributed with this   -->
@@ -148,7 +148,7 @@
 
                 return {
                     valid: true,
-                    responseCardData: responseCardData
+                    responseCardData: responseCardData // keep the deprecated way for testing only
                 };
             });
         }

src/test/resources/bundles/defaultProcess_V1/template/question.handlebars

@@ -96,12 +96,14 @@
 
             const result = {
                 valid: true,
-                responseCardData: responseCardData
+                responseCard:{
+                    data: responseCardData
+                } 
             };
 
             // If the user chose several options, we decide to move the process to a specific state, for example to ask a follow-up question (what's their preferred option).
             const choiceRequiresFollowUp = Object.entries(responseCardData).length > 1;
-            if (choiceRequiresFollowUp) result['responseState'] = 'multipleOptionsResponseState';
+            if (choiceRequiresFollowUp) result.responseCard['state'] = 'multipleOptionsResponseState';
 
             return result;
 
@@ -162,15 +164,15 @@
             (key in responseCardData) ? responseCardData[key].push(value) : responseCardData[key] = [value];
         }
 
-        const result = {
-            responseCardData: responseCardData
-        };
+        const responseCard= {
+                data: responseCardData
+            }
 
         // If the user chose several options, we decide to move the process to a specific state, for example to ask a follow-up question (what's their preferred option).
         const choiceRequiresFollowUp = Object.entries(responseCardData).length > 1;
-        if (choiceRequiresFollowUp) result['responseState'] = 'multipleOptionsResponseState';
+        if (choiceRequiresFollowUp) responseCard['state'] = 'multipleOptionsResponseState';
 
 
-        opfab.cards.sendResponseCard(opfab.currentCard.getCard(), result);
+        opfab.cards.sendResponseCard(opfab.currentCard.getCard(), responseCard);
     }
 </script>

src/test/resources/bundles/messageOrQuestionExample/template/confirmation.handlebars

@@ -1,4 +1,4 @@
-<!-- Copyright (c) 2022-2024, RTE (http://www.rte-france.com)              -->
+<!-- Copyright (c) 2022-2025, RTE (http://www.rte-france.com)              -->
 <!-- See AUTHORS.txt                                                       -->
 <!-- This Source Code Form is subject to the terms of the Mozilla Public   -->
 <!-- License, v. 2.0. If a copy of the MPL was not distributed with this   -->
@@ -89,7 +89,7 @@
                         confirm: confirm,
                         message: message
                     };
-                return {
+                return { //keep deprecated format for testing only
                     valid: true,
                     publisher : publisher,
                     responseCardData: responseCardData,
@@ -128,4 +128,4 @@
 
 </script>
 
-</p>
+</p>

ui/main/src/app/api/cards.api.ts

@@ -18,8 +18,8 @@ export function initCardsAPI() {
         getCards: function (cardsFilters) {
             return firstValueFrom(CardsService.fetchFilteredCards(cardsFilters));
         },
-        sendResponseCard: function (parentCard, responseData) {
-            return CardResponseService.sendResponse(parentCard, responseData);
+        sendResponseCard: function (parentCard, responseCard) {
+            return CardResponseService.sendResponse(parentCard, responseCard);
         }
     };
 }

ui/main/src/app/builtInTemplates/message-or-question-list/card/message-or-question-listCardTemplateView.spec.ts

@@ -43,16 +43,16 @@ describe('MessageOrQuestionList Card template', () => {
         view.listenToInputFieldVisibility((visible) => (inputFieldVisibility = visible));
         expect(inputFieldVisibility).toBeFalse();
     });
-    it('GIVEN input is "my response" and "Yes" WHEN get user response THEN responseCardData.comment is "my_response", responseCardData.agreement is "Yes" and response is valid', () => {
+    it('GIVEN input is "my response" and "Yes" WHEN get user response THEN responseCard.data.comment is "my_response", responseCard.data.agreement is "Yes" and response is valid', () => {
         // Simulate input "my response"
         view.setFunctionToGetResponseInput(() => {
             return [true, 'my response'];
         });
 
         const userResponse = CardTemplateGateway.getUserResponseFromTemplate(undefined);
         expect(userResponse.valid).toBeTrue();
-        expect(userResponse.responseCardData.comment).toEqual('my response');
-        expect(userResponse.responseCardData.agreement).toEqual(true);
+        expect(userResponse.responseCard.data.comment).toEqual('my response');
+        expect(userResponse.responseCard.data.agreement).toEqual(true);
     });
 
     it('Given a question card WHEN user card is locked THEN response input is hidden', () => {

ui/main/src/app/builtInTemplates/message-or-question-list/card/message-or-question-listCardTemplateView.ts

@@ -1,4 +1,4 @@
-/* Copyright (c) 2023-2024, RTE (http://www.rte-france.com)
+/* Copyright (c) 2023-2025, RTE (http://www.rte-france.com)
  * See AUTHORS.txt
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -29,7 +29,7 @@ export class MessageOrQuestionListCardTemplateView {
     public setFunctionToGetResponseInput(getResponseInput: Function) {
         opfab.currentCard.registerFunctionToGetUserResponse(() => {
             const response = getResponseInput();
-            return {valid: true, responseCardData: {agreement: response[0], comment: response[1]}};
+            return {valid: true, responseCard: {data: {agreement: response[0], comment: response[1]}}};
         });
     }
 

ui/main/src/app/builtInTemplates/question/card/questionCardTemplateView.spec.ts

@@ -72,13 +72,13 @@ describe('Question Card template', () => {
         expect(inputFieldVisibility).toBeTrue();
     });
 
-    it('GIVEN input is "my response" WHEN get user response THEN responseCardData.responses[0].response is] "my_response" and response is valid', () => {
+    it('GIVEN input is "my response" WHEN get user response THEN responseCard.data.responses[0].response is] "my_response" and response is valid', () => {
         // Simulate input "my response"
         view.setFunctionToGetResponseInput(() => 'my response', false);
 
         const userResponse = CardTemplateGateway.getUserResponseFromTemplate(undefined);
         expect(userResponse.valid).toBeTrue();
-        expect(userResponse.responseCardData.responses[0].response).toEqual('my response');
+        expect(userResponse.responseCard.data.responses[0].response).toEqual('my response');
     });
 
     it('GIVEN 2 child cards WHEN listen to child card THEN received 2 response', () => {
@@ -131,12 +131,12 @@ describe('Question Card template', () => {
         const userResponse = CardTemplateGateway.getUserResponseFromTemplate('entity1');
 
         expect(userResponse.valid).toBeTrue();
-        expect(userResponse.responseCardData.responses[0].response).toEqual('response_entity1');
-        expect(userResponse.responseCardData.responses[0].responseDate).toEqual(
+        expect(userResponse.responseCard.data.responses[0].response).toEqual('response_entity1');
+        expect(userResponse.responseCard.data.responses[0].responseDate).toEqual(
             new Date('2024-06-01T09:15:00').getTime()
         );
-        expect(userResponse.responseCardData.responses[1].response).toEqual('my 2nd response');
-        expect(userResponse.responseCardData.responses[1].responseDate).toEqual(
+        expect(userResponse.responseCard.data.responses[1].response).toEqual('my 2nd response');
+        expect(userResponse.responseCard.data.responses[1].responseDate).toEqual(
             new Date('2024-06-01T09:24:00').getTime()
         );
     });
@@ -160,9 +160,7 @@ describe('Question Card template', () => {
         const userResponse = CardTemplateGateway.getUserResponseFromTemplate('entity1');
 
         expect(userResponse.valid).toBeTrue();
-        expect(userResponse.responseCardData.responses.length).toEqual(1);
-        expect(userResponse.responseCardData.responses[0].response).toEqual('my 2nd response');
-        expect(userResponse.responseCardData.responses[0].responseDate).toEqual(
+        expect(userResponse.responseCard.data.responses[0].responseDate).toEqual(
             new Date('2024-06-01T09:24:00').getTime()
         );
     });

ui/main/src/app/builtInTemplates/question/card/questionCardTemplateView.ts

@@ -1,4 +1,4 @@
-/* Copyright (c) 2023-2024, RTE (http://www.rte-france.com)
+/* Copyright (c) 2023-2025, RTE (http://www.rte-france.com)
  * See AUTHORS.txt
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -40,7 +40,7 @@ export class QuestionCardTemplateView {
                 response: response
             });
 
-            return {valid: true, responseCardData: {responses: responseHistory}};
+            return {valid: true, responseCard: {data: {responses: responseHistory}}};
         });
     }