@gov-cy/govcy-express-services 1.3.0-alpha.4 → 1.3.0-alpha.6

package/README.md

@@ -33,6 +33,7 @@ The APIs used for submission, temporary save and file uploads are not part of th
   - [🧩 Dynamic services](#-dynamic-services)
     - [Pages](#pages)
     - [Form vs static pages](#form-vs-static-pages)
+    - [Update my details pages](#update-my-details-pages)
     - [Multiple things pages (repeating group of inputs)](#multiple-things-pages-repeating-group-of-inputs)
     - [Review page](#review-page)
     - [Success page](#success-page)
@@ -755,6 +756,8 @@ flowchart LR
 
 Some pages are generated automatically by the project, such as the `review` and `success` pages.
 
+------------------------------------------
+
 #### Pages
 
 Pages defined in the JSON file under the `pages` array, they rendered based on the [govcy-frontend-renderer](https://github.com/gov-cy/govcy-frontend-renderer) library, and they are served by the `/:siteId/:pageUrl` route. The `pageData.nextPage` field is used to determine the next page to render.
@@ -876,6 +879,8 @@ Lets break down the JSON config for this page:
   - `sections` is an array of sections, which is an array of elements. Sections allowed: `beforeMain`, `main`, `afterMain`.
     - `elements` is an array of elements for the said section. Seem more details on the [govcy-frontend-renderer's design elements documentation](https://github.com/gov-cy/govcy-frontend-renderer/blob/main/DESIGN_ELEMENTS.md).
 
+------------------------------------------
+
 #### Form vs static pages
 
 - If the `pageTemplate` includes a `form` element in the `main` section and `button` element, the system will treat it as form and will:
@@ -909,6 +914,147 @@ The [start page](https://gov-cy.github.io/govcy-design-system-docs/patterns/serv
 - Check out the [govcy-frontend-renderer's design elements](https://github.com/gov-cy/govcy-frontend-renderer/blob/main/DESIGN_ELEMENTS.md) for more details on the supported elements and their parameters.
 - Check out the [input validations section](#-input-validations) for more details on how to add validations to the JSON file.
 
+-------------------------------------------
+
+#### Update my details pages
+
+![Update my details seamless](docs/img/express-UMD-Seamless.png)
+
+Update my details pages are pages that can integrate the [Update My Personal Details service](https://update-my-details.service.gov.cy/) to fetch or update a user’s name, email, mobile number, or correspondence address, without breaking the user journey. The implementation of these pages follow the instructuctions described in the [Use ‘Update my personal details’ in Your Service](https://dsf.dmrid.gov.cy/2025/05/20/use-update-my-personal-details-in-your-service/) post.
+
+If the `scope` also includes the `email` element, the system will also use that email address to send the email to the user on submition.
+
+**Update my details - example JSON config**
+```json
+{
+  "pageData": {
+    "url": "index",     // Page URL
+    "layout": "layouts/govcyBase.njk",
+    "mainLayout": "two-third",
+    "nextPage": "next-page" 
+  },
+  "updateMyDetails": {
+    "APIEndpoint": {    // API endpoint for fetching user details from the Update My Details service
+      "url": "CIVIL_REGISTRY_CONTACT_API_URL", // URL
+      "method": "GET",                         // HTTP method
+      "clientKey": "DSF_API_GTW_CLIENT_ID",    // Client key
+      "serviceId": "DSF_API_GTW_SERVICE_ID",   // Service ID
+      "dsfgtwApiKey": "DSF_API_GTW_SECRET"     // DSF GTW API key 
+    },
+    "updateMyDetailsURL": "UPDATE_MY_DETAILS_URL",  // DOMAIN URL for redirecting to the Update My Details service
+  "topElements": [                             // Elements to be displayed on the top of the page
+      {
+        "element": "progressList",
+        "params": {
+          "id": "steps",
+          "current": "4",
+          "total": "4",
+          "showSteps": true
+        }
+      }
+    ],
+    "scope": [                                  // Scope of the form. What elenents to collect
+      "fullName",
+      "email",
+      "mobile",
+      "address"
+    ],
+    "hasBackLink": true                         // Whether the hub page has a back link
+  }
+}
+
+```
+
+Lets break down the JSON config for Update my details:
+
+- **updateMyDetails** are the page's definition for the integration with the Update My Details service.
+  - `updateMyDetails.APIEndpoint` is the API endpoint for fetching user details from the Update My Details service.
+  - `updateMyDetails.updateMyDetailsURL` is the DOMAIN URL for redirecting to the Update My Details service.
+  - `updateMyDetails.scope` is the scope of the form. What elenents to collect. It can be one or more of the following:
+    - `fullName`
+    - `dob`
+    - `email`
+    - `mobile`
+    - `address` 
+  - `updateMyDetails.hasBackLink` is a boolean that indicates whether the hub page has a back link.
+
+
+The above config references the following environment variables that need to be set:
+
+```dotenv
+### Update my details
+CIVIL_REGISTRY_CONTACT_API_URL=http://localhost:3002/get-update-my-details
+DSF_API_GTW_CLIENT_ID=your-DSF-API-gateway-client-id
+DSF_API_GTW_SERVICE_ID=your-DSF-API-gateway-service-id
+DSF_API_GTW_SECRET=your-DSF-API-gateway-secret
+
+UPDATE_MY_DETAILS_URL=https://update-my-details.staging.service.gov.cy # FOR TESTING
+```
+
+The DSF team has developed an API that performs standard eligibility checks against the Civil Registry. More details at [Update-my-details.md](docs/Update-my-details.md)
+
+**Update my details - users' flow**
+
+The update my details behaves like a normal page and it is accessed through the url `:siteId/:pageUrl`. As a best practice you should set this as your `index` page and the first one in your pages array. Depending on the user it can have 3 variants:
+
+**Variant 1: Manual form for non-eligible users (no access to UMD)**
+
+When a user is either: 
+- Not a Cypriot citizen 
+- Or Cypriot citizen under 18 
+
+The user gets a data entry page.
+
+![variant 1 screenshot](docs/img/express-UMD-variant1.png)
+
+**Variant 2: Eligible users (access to UMD) with existing details**
+
+When a user is : 
+- A Cypriot citizen over 18  
+- AND has data in Update my Details 
+
+The users get a page with the data from UMD and asks if its ok to use those data.
+
+![variant 2 screenshot](docs/img/express-UMD-variant2.png)
+
+If the user selects:
+- `YES`: the data are stored in the data layer and continues to the next page (or review page depending where the user came from)
+- `NO`: the users are redirected to the Update my details service in seamless mode. When users finish with that, they are redirected back to the page with variant 2 and are asked again if it's ok to use the updated data.
+
+**Variant 3: Eligible users (access to UMD) without existing details** 
+
+When a user is : 
+- A Cypriot citizen over 18  
+- AND has no data in Update my Details
+
+The users get a continue button that redirects to the Update my details service in seamless mode. 
+
+![variant 3 screenshot](docs/img/express-UMD-variant3.png)
+
+When users finish with that, they are redirected back to the page with variant 2 and are asked if it's ok to use the updated data. 
+
+**Update my details - data storage**
+
+The form data for a `updateMyDetails` page is stored as a normal page as an **object** in the session data layer:
+```json
+{
+  "index": {
+    "formData": 
+    {
+      "fullName": "John Smith",
+      "email": "email@example.com",
+      "mobile": "+35712345678",
+      "address": "123 Some Street\n Nicosia\nCyprus",
+    }
+  }
+}
+```
+
+**Notes on Update my details**
+- There `pageData.title` is not used. Instead the page title is generated by the system.
+
+------------------------------------------
+
 #### Multiple things pages (repeating group of inputs)
 ![Multiple things pages](docs/img/express-mt.png)
 
@@ -1129,6 +1275,8 @@ Form data for a `multipleThings` page is stored as an **array** in the session d
 - `multipleDraft` is used internally to store file's data while the user is adding a new item.
 
 
+------------------------------------------
+
 #### Review page
 
 The `review` page is automatically generated by the project and includes the following sections:
@@ -1145,6 +1293,8 @@ When the user clicks a change link, the user is redirected to the corresponding
 
 When the user clicks the `Submit` button, all the data gathered from the site's forms within this session are validated based on the validation definition in the JSON file, and if they pass they are submitted to the configured API endpoint.
 
+------------------------------------------
+
 #### Success page
 
 The `success` page is automatically generated by the project, is accessible only when a submission is made successfully, and includes the following sections:
@@ -1157,6 +1307,8 @@ Here's an example screenshot of success page
 
 ![Screenshot of success page](docs/img/express-success.png)
 
+--------------------------------
+
 ### 🛡️ Site eligibility checks
 
 The project uses an array of API endpoints to check the eligibility of a service/site. To use this feature, you need to configure the following in your JSON file under the `site` object:
@@ -2479,7 +2631,7 @@ The environment variables are defined in:
    - `.env.production` for production
 
 #### Secret environment variables
-The following secret environment variables are used to configure the server:
+The following secret environment variables are used to configure the server (note the values below are examples, you need to replace them with your own values):
 
 ```dotenv
 # 🔐 Session
@@ -2553,9 +2705,13 @@ TEST_FILE_DELETE_API_URL=http://localhost:3002/fileDelete
 # Eligibility checks (optional test APIs)
 TEST_ELIGIBILITY_1_API_URL=http://localhost:3002/eligibility1
 TEST_ELIGIBILITY_2_API_URL=http://localhost:3002/eligibility2
+
+# Update my details
+CIVIL_REGISTRY_CONTACT_API_URL=http://localhost:3002/get-update-my-details
+UPDATE_MY_DETAILS_URL=https://update-my-details.staging.service.gov.cy
 ```
 #### Non secret environment variables
-The following non-secret environment variables are used to configure the server defined in `.env.development` for local development, `.env.staging` for staging, and `.env.production` for production.:
+The following non-secret environment variables are used to configure the server defined in `.env.development` for local development, `.env.staging` for staging, and `.env.production` for production:
 
 ```dotenv
 #### Matomo web analytics environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gov-cy/govcy-express-services",
-  "version": "1.3.0-alpha.4",
+  "version": "1.3.0-alpha.6",
   "description": "An Express-based system that dynamically renders services using @gov-cy/govcy-frontend-renderer and posts data to a submission API.",
   "author": "DMRID - DSF Team",
   "license": "MIT",

package/src/middleware/govcyFileUpload.mjs

@@ -4,6 +4,7 @@ import { successResponse, errorResponse } from '../utils/govcyApiResponse.mjs';
 import { ALLOWED_MULTER_FILE_SIZE_MB } from "../utils/govcyConstants.mjs";
 import { handleFileUpload } from "../utils/govcyHandleFiles.mjs";
 
+/* c8 ignore start */
 // Configure multer to store the file in memory (not disk) and limit the size to 10MB
 const upload = multer({
     storage: multer.memoryStorage(),
@@ -46,4 +47,5 @@ export const govcyFileUpload = [
 
         return res.json(successResponse(result.data));
     }
-];
+];
+/* c8 ignore end */

package/src/middleware/govcyUpdateMyDetails.mjs

@@ -14,7 +14,7 @@ import { getEnvVariable, getEnvVariableBool, isProdOrStaging } from "../utils/go
 import * as govcyResources from "../resources/govcyResources.mjs";
 import * as dataLayer from "../utils/govcyDataLayer.mjs";
 import { logger } from '../utils/govcyLogger.mjs';
-import { handleMiddlewareError } from "../utils/govcyUtils.mjs";
+import { handleMiddlewareError, dateStringISOtoDMY } from "../utils/govcyUtils.mjs";
 import { govcyApiRequest } from "../utils/govcyApiRequest.mjs";
 import { isUnder18, isValidCypriotCitizen, validateFormElements } from "../utils/govcyValidator.mjs";
 import { populateFormData, getFormData } from "../utils/govcyFormHandling.mjs";
@@ -128,8 +128,21 @@ export async function govcyUpdateMyDetailsHandler(req, res, next, page, serviceC
                     // Special case for address
                     if (element === "address") {
                         key = "addressInfo";
-                        value = response.Data?.addressInfo?.[0]?.addressText || "";
-                    }
+                        //if response.Data.addressInfo is an array
+                        if (response.Data.addressInfo && Array.isArray(response.Data.addressInfo)) {
+                            value = response.Data?.addressInfo?.[0]?.addressText || "";
+                        } 
+                        // else if response.Data.addressInfoUnstructured is not null and is an array
+                        else if (response.Data.addressInfoUnstructured && Array.isArray(response.Data.addressInfoUnstructured)) {
+                            value = response.Data?.addressInfoUnstructured?.[0]?.addressText || "";
+                        }
+                        // else if response.Data.poBoxAddress is not null and is not an array
+                        else if (response.Data.poBoxAddress && Array.isArray(response.Data.poBoxAddress)) {
+                            value = response.Data?.poBoxAddress?.[0]?.poBoxText || "";
+                        } else {
+                            value = "";
+                        }
+                    } 
 
                     // Check if the key exists
                     if (!Object.prototype.hasOwnProperty.call(response.Data || {}, key)) {
@@ -162,6 +175,9 @@ export async function govcyUpdateMyDetailsHandler(req, res, next, page, serviceC
             }
         }
 
+        // Deep copy pageTemplate to avoid modifying the original
+        const pageTemplateCopy = JSON.parse(JSON.stringify(pageTemplate));
+
         // if the page variant is 1 or 2 which means it has a form
         if (pageVariant === 1 || pageVariant === 2) {
             // Handle form data
@@ -181,7 +197,7 @@ export async function govcyUpdateMyDetailsHandler(req, res, next, page, serviceC
 
 
             populateFormData(
-                pageTemplate.sections[0].elements[0].params.elements,
+                pageTemplateCopy.sections[0].elements[0].params.elements,
                 theData,
                 validationErrors,
                 req.session,
@@ -194,18 +210,18 @@ export async function govcyUpdateMyDetailsHandler(req, res, next, page, serviceC
 
             // if there are validation errors, add an error summary
             if (validationErrors?.errorSummary?.length > 0) {
-                pageTemplate.sections[0].elements[0].params.elements.unshift(govcyResources.errorSummary(validationErrors.errorSummary));
+                pageTemplateCopy.sections[0].elements[0].params.elements.unshift(govcyResources.errorSummary(validationErrors.errorSummary));
             }
         }
 
         // Add topElements if provided
         if (Array.isArray(umdConfig.topElements)) {
-            pageTemplate.sections[0].elements[0].params.elements.unshift(...umdConfig.topElements);
+            pageTemplateCopy.sections[0].elements[0].params.elements.unshift(...umdConfig.topElements);
         }
 
         //if hasBackLink == true add section beforeMain with backlink element
         if (umdConfig?.hasBackLink == true) {
-            pageTemplate.sections.unshift({
+            pageTemplateCopy.sections.unshift({
                 name: "beforeMain",
                 elements: [
                     {
@@ -226,7 +242,7 @@ export async function govcyUpdateMyDetailsHandler(req, res, next, page, serviceC
                     mainLayout: page?.pageData?.mainLayout || "two-third"
                 }
             },
-            pageTemplate: pageTemplate
+            pageTemplate: pageTemplateCopy
         };
 
         logger.debug("Processed `govcyUpdateMyDetailsHandler` page data:", req.processedPage, req);
@@ -372,8 +388,21 @@ export function govcyUpdateMyDetailsPostHandler() {
                         // Special case for address
                         if (element === "address") {
                             key = "addressInfo";
-                            value = response.Data?.addressInfo?.[0]?.addressText || "";
-                        }
+                            //if response.Data.addressInfo is an array
+                            if (response.Data.addressInfo && Array.isArray(response.Data.addressInfo)) {
+                                value = response.Data?.addressInfo?.[0]?.addressText || "";
+                            } 
+                            // else if response.Data.addressInfoUnstructured is not null and is an array
+                            else if (response.Data.addressInfoUnstructured && Array.isArray(response.Data.addressInfoUnstructured)) {
+                                value = response.Data?.addressInfoUnstructured?.[0]?.addressText || "";
+                            }
+                            // else if response.Data.poBoxAddress is not null and is not an array
+                            else if (response.Data.poBoxAddress && Array.isArray(response.Data.poBoxAddress)) {
+                                value = response.Data?.poBoxAddress?.[0]?.poBoxText || "";
+                            } else {
+                                value = "";
+                            }
+                        } 
 
                         // Check if the key exists
                         if (!Object.prototype.hasOwnProperty.call(response.Data || {}, key)) {
@@ -387,8 +416,18 @@ export function govcyUpdateMyDetailsPostHandler() {
                             hasData = false;
                             userDetails[element] = "";
                         } else {
-                            // Set the value
-                            userDetails[element] = value;
+                            if (element === "dob") {
+                                key = "dob";
+                                // value = response.Data?.[key] || "";
+                                // Store different for ${element}_day, ${element}_month, ${element}_year
+                                const [year, month, day] = value.split("-").map(Number);
+                                userDetails[`${element}_day`] = day;
+                                userDetails[`${element}_month`] = month;
+                                userDetails[`${element}_year`] = year;
+                            } else {
+                                // Set the value as it is 
+                                userDetails[element] = value;
+                            }
                         }
                     }
 
@@ -567,6 +606,12 @@ function createUmdHasDataPageTemplate(siteId, lang, page, req, userDetails) {
     }
     //for each element in the scope array
     umdConfig?.scope.forEach(element => {
+        let value = userDetails?.[element] || "";
+
+        //if element is dob
+        if (element === "dob") {
+            value = dateStringISOtoDMY(value);
+        }
         // add the key and value to the summaryList
         summaryList.params.items.push({
             key: govcyResources.staticResources.text.updateMyDetailsScopes[element],
@@ -576,7 +621,7 @@ function createUmdHasDataPageTemplate(siteId, lang, page, req, userDetails) {
                     params: {
                         type: "span",
                         classes: "govcy-whitespace-pre-line",
-                        text: govcyResources.getSameMultilingualObject(null, userDetails[element])
+                        text: govcyResources.getSameMultilingualObject(null, value)
                     }
                 }
             ]
@@ -744,3 +789,4 @@ export function constructUpdateMyDetailsRedirect(req, userId, umdBaseURL, return
     // Construct redirect URL
     return `${umdBaseURL}/ReturnUrl/SetReturnUrl?Url=${encodedReturnUrl}&UserProfileId=${encodedUserId}&lang=${lang}`;
 }
+

package/src/resources/govcyResources.mjs

@@ -239,7 +239,7 @@ export const staticResources = {
         updateMyDetailsScopes : {
             fullName : 
             {
-                el: "Ονοματεπωνυμο",
+                el: "Ονοματεπώνυμο",
                 en: "Full name",
                 tr: "Full name"
             }, 
@@ -261,6 +261,12 @@ export const staticResources = {
                 en: "Mailing address",
                 tr: "Mailing address"
             },
+            dob : 
+            {
+                el: "Ημερομηνία γέννησης",
+                en: "Date of birth",
+                tr: "Date of birth"
+            },
         }
     },
     //remderer sections
@@ -312,7 +318,7 @@ export const staticResources = {
                     name: "useTheseDetails",
                     legend: {
                         el: "Να χρησιμοποιήσουμε αυτά τα στοιχεία;",
-                        en: "Should we use these elements?"
+                        en: "Should we use these details?"
                     },
                     items: [
                         {
@@ -329,6 +335,11 @@ export const staticResources = {
                                 el: "Όχι, θα αλλάξω αυτά τα στοιχεία",
                                 en: "No, I will change these details",
                                 tr: ""
+                            },
+                            hint: {
+                                el: "Μπορείτε να αλλάξετε μόνο τα στοιχεία επικοινωνίας",
+                                en: "You can only change your contact details",
+                                tr: ""
                             }
                         }
                     ],
@@ -603,6 +614,68 @@ export const staticResources = {
                         }
                     }
                 ]
+            }, 
+            "dob" : {
+                element: "dateInput",
+                params: {
+                id: "dob",
+                name: "dob",
+                legend: {
+                    el: "Ημερομηνία γέννησης",
+                    en: "Date of birth"
+                },
+                isPageHeading: false,
+                hint: {
+                    el: "Για παράδειγμα, 13 8 2001",
+                    en: "For example, 13 8 2001"
+                }
+                },
+                validations: [
+                {
+                    check: "required",
+                    params: {
+                    checkValue: "",
+                    message: {
+                        el: "Εισαγάγετε την ημερομηνία γέννησης",
+                        en: "Enter the date of birth",
+                        tr: ""
+                    }
+                    }
+                },
+                {
+                    check: "valid",
+                    params: {
+                    checkValue: "dateISO",
+                    message: {
+                        el: "Η ημερομηνία γέννησης πρέπει να είναι σωστή ημερομηνία",
+                        en: "The date of birth must be an valid date",
+                        tr: ""
+                    }
+                    }
+                },
+                {
+                    check: "minValueDate",
+                    params: {
+                    checkValue: "1900-01-01",
+                    message: {
+                        el: "Η ημερομηνία γέννησης πρέπει να είναι μετά από τις 1/1/1990",
+                        en: "The date of birth must be after 1/1/1900",
+                        tr: ""
+                    }
+                    }
+                },
+                {
+                    check: "valid",
+                    params: {
+                    checkValue: "maxCurrentDate",
+                    message: {
+                        el: "Η ημερομηνία γέννησης δεν πρέπει να είναι στο μέλλον",
+                        en: "The date of birth must not be in the future",
+                        tr: ""
+                    }
+                    }
+                }
+                ]
             }
         },
         govcyFormsJs: {

package/src/utils/govcyUtils.mjs

@@ -10,4 +10,16 @@ export function handleMiddlewareError(message, status, next) {
     const error = new Error(message);
     error.status = status;
     return next(error);
+}
+
+/**
+ * Helper function to format a date in the format D/M/YYYY.
+ * 
+ * @param {string} dateString - The date string in the format YYYY-MM-DD.
+ * @returns {string} The formatted date in the format D/M/YYYY.
+ */
+export function dateStringISOtoDMY(dateString) {
+  if (typeof dateString !== "string" || !dateString.trim()) return "";
+  const [year, month, day] = dateString.trim().split("-");
+  return `${parseInt(day)}/${parseInt(month)}/${year}`;
 }