PLU-408: FormSG new local address field (#859)

## Feature
FormSG is releasing a new local address field
<img width="858" alt="Screenshot 2025-02-11 at 10 16 02 PM"
src="https://github.com/user-attachments/assets/35bd2954-0c61-48a1-98bf-bcb64b5e930a"
/>

**Features**:

- Handle address field inputs and create the respective variables
- FormSG local address inputs are received as answer arrays in Plumber
in the following order:
  1. Block number
  2. Street name
  3. Building name (optional)
  4. Level number (optional)
  5. Unit number (optional)
  6. Postal code
- Level number and unit number are combined into a single variable 'Unit
number'
- FormSG has validation that both Level number and Unit number must be
filled if either field is filled

## Before & After Screenshots

**BEFORE**:
NA.

**AFTER**:
![Screenshot 2025-02-11 at 10 23
21 PM](https://github.com/user-attachments/assets/f06e347c-0aed-4e36-91ae-eefe1a0fc2f5)

Variables are available for use even if data was not provided in test
submission
<img width="862" alt="Screenshot 2025-02-12 at 6 52 55 PM"
src="https://github.com/user-attachments/assets/a0a8878d-5491-4ded-af41-257caea0cba2"
/>
<img width="835" alt="Screenshot 2025-02-12 at 6 54 35 PM"
src="https://github.com/user-attachments/assets/48d678a3-6a32-4e2f-b706-53c73acac974"
/>


Mock data is generated for all fields
<img width="855" alt="Screenshot 2025-02-12 at 6 56 27 PM"
src="https://github.com/user-attachments/assets/44f142b9-b8a9-4e20-99b6-2fb5676d23d8"
/>
<img width="854" alt="Screenshot 2025-02-12 at 6 56 41 PM"
src="https://github.com/user-attachments/assets/3c160bd0-b8f2-4a2e-b650-6495ae892294"
/>



## Tests

- [x] All other FormSG fields are parsed correctly, just like before
this new field was introduced
- [x] Address fields are parsed in the correct order, with variables
available for use even if field was empty during test submission
- [x] All FormSG functionalities are working after formsg-sdk upgrade
(connecting new form, receiving new form submissions on existing forms)

## Deploy Notes
- FormSG is targeting to release the local address field on Thu,
13-Feb-2025. Plumber can release this feature anytime as it is not
dependent on their release.

Author: kevinkim-ogp

package-lock.json

@@ -34,7 +34,7 @@
     "@bull-board/express": "5.17.0",
     "@graphql-tools/schema": "10.0.0",
     "@launchdarkly/node-server-sdk": "9.0.4",
-    "@opengovsg/formsg-sdk": "0.11.0",
+    "@opengovsg/formsg-sdk": "0.13.0",
     "@opengovsg/sgid-client": "2.1.0",
     "@plumber/types": "file:../types",
     "@taskforcesh/bullmq-pro": "7.7.1",

packages/backend/package.json

@@ -535,4 +535,59 @@ describe('decrypt form response', () => {
       expect(mocks.getSdk).toBeCalledWith('staging')
     })
   })
+
+  describe('local address field', () => {
+    it('should handle local address fields', async () => {
+      $.flow.hasFileProcessingActions = false
+      mocks.cryptoDecrypt.mockReturnValueOnce({
+        responses: [
+          {
+            _id: 'addressFieldComplete',
+            fieldType: 'address',
+            question: 'What is your address?',
+            answerArray: [
+              '51',
+              'BRAS BASAH ROAD',
+              'Lazada One',
+              '08',
+              '888',
+              '189554',
+            ],
+          },
+          {
+            _id: 'addressFieldPartial',
+            fieldType: 'address',
+            question: 'What is your address?',
+            answerArray: ['51', 'BRAS BASAH ROAD', '', '', '', '189554'],
+          },
+        ],
+      })
+
+      await expect(decryptFormResponse($)).resolves.toEqual(true)
+      expect($.request.body).toEqual(
+        expect.objectContaining({
+          fields: {
+            addressFieldComplete: {
+              fieldType: 'address',
+              question: 'What is your address?',
+              answerArray: [
+                '51',
+                'BRAS BASAH ROAD',
+                'Lazada One',
+                '#08-888',
+                '189554',
+              ],
+              order: 1,
+            },
+            addressFieldPartial: {
+              fieldType: 'address',
+              question: 'What is your address?',
+              answerArray: ['51', 'BRAS BASAH ROAD', '', '', '189554'],
+              order: 2,
+            },
+          },
+        }),
+      )
+    })
+  })
 })

packages/backend/src/apps/formsg/__tests__/auth/decrypt-form-response.test.ts

@@ -7,6 +7,7 @@ import {
 
 import { beforeEach, describe, expect, it } from 'vitest'
 
+import { ADDRESS_LABELS } from '../../common/constants'
 import trigger from '../../triggers/new-submission'
 
 describe('new submission trigger', () => {
@@ -290,6 +291,24 @@ describe('new submission trigger for answer array fields', () => {
             order: 3,
             answerArray: ['weird', 'strange'],
           },
+          addressFieldComplete: {
+            question: 'What is your address?',
+            fieldType: 'address',
+            order: 4,
+            answerArray: [
+              '51',
+              'BRAS BASAH ROAD',
+              'Lazada One',
+              '#08-888',
+              '189554',
+            ],
+          },
+          addressFieldPartial: {
+            question: 'What is your address?',
+            fieldType: 'address',
+            order: 5,
+            answerArray: ['51', 'BRAS BASAH ROAD', '', '', '189554'], // Some empty fields
+          },
         },
       },
     } as unknown as IExecutionStep
@@ -343,5 +362,25 @@ describe('new submission trigger for answer array fields', () => {
       const metadata = await trigger.getDataOutMetadata(executionStep)
       expect(metadata.fields.textFieldId3.answerArray).toBeUndefined()
     })
+
+    it('Address type: includes all address fields', async () => {
+      const metadata = await trigger.getDataOutMetadata(executionStep)
+      const addressMetadata = metadata.fields.addressFieldComplete
+        .answerArray as IDataOutMetadatum[]
+
+      expect(addressMetadata).toHaveLength(5)
+      ADDRESS_LABELS.forEach((label, index) => {
+        expect(addressMetadata[index].label).toEqual(`Response 4, ${label}`)
+      })
+    })
+
+    it('Address type: includes all metadata for empty address fields', async () => {
+      const metadata = await trigger.getDataOutMetadata(executionStep)
+      const addressMetadata = metadata.fields.addressFieldPartial
+        .answerArray as IDataOutMetadatum[]
+      ADDRESS_LABELS.forEach((label, index) => {
+        expect(addressMetadata[index].label).toEqual(`Response 5, ${label}`)
+      })
+    })
   })
 })

packages/backend/src/apps/formsg/__tests__/triggers/new-submission.test.ts

@@ -16,6 +16,19 @@ import storeAttachmentInS3 from './helpers/store-attachment-in-s3'
 
 const NRIC_VERIFIED_FIELDS = new Set(['sgidUinFin', 'uinFin'])
 
+function processLocalAddress(answerArray: string[]): string[] {
+  const answer = [...answerArray]
+
+  // Combine level number and unit number if both exist
+  const levelNumber = answer[3]
+  const unitNumber = answer[4]
+  answer[3] = levelNumber && unitNumber ? `#${levelNumber}-${unitNumber}` : ''
+  // Remove element at index 4 since we've combined it with element 3
+  answer.splice(4, 1)
+
+  return answer
+}
+
 /**
  * Filters NRIC if an NRIC filter was configured for the pipe.
  *
@@ -119,6 +132,10 @@ export async function decryptFormResponse(
         )
       }
 
+      if (rest.fieldType === 'address') {
+        rest.answerArray = processLocalAddress(rest.answerArray as string[])
+      }
+
       // Note: the order may not be sequential; fields (e.g. NRIC) can be
       // omitted from the output.
       // Note: FormSG uses dot notation for field ids for MyInfo children

packages/backend/src/apps/formsg/auth/decrypt-form-response.ts

@@ -1 +1,22 @@
 export const FORM_ID_LENGTH = 24
+
+/**
+ * NOTE: this must be updated if there are any changes to the address fields
+ * Currently following the same field names as FormSG
+ */
+export const ADDRESS_LABELS = [
+  'Block number',
+  'Street name',
+  'Building name',
+  // this combines level number and unit number
+  'Unit number',
+  'Postal code',
+]
+
+// Reference form response for local address
+// ---
+// {
+//   question: 'Local address',
+//   fieldType: 'address',
+//   answerArray: [ '51', 'BRAS BASAH ROAD', 'Lazada One', '8', '8888', '189554' ]
+// }

packages/backend/src/apps/formsg/common/constants.ts

@@ -10,6 +10,8 @@ import {
 import logger from '@/helpers/logger'
 import { parseS3Id } from '@/helpers/s3'
 
+import { ADDRESS_LABELS } from '../../common/constants'
+
 function buildQuestionMetadatum(fieldData: IJSONObject): IDataOutMetadatum {
   const question: IDataOutMetadatum = {
     type: 'text',
@@ -57,8 +59,20 @@ function isAnswerArrayValid(fieldData: IJSONObject): boolean {
   if (!fieldData.answerArray) {
     return false
   }
-  // strict check for only table and checkbox variables
-  return fieldData.fieldType === 'table' || fieldData.fieldType === 'checkbox'
+  // strict check for only table, checkbox and address variables
+  const answerArrayFields = ['table', 'checkbox', 'address']
+  return answerArrayFields.includes(fieldData.fieldType as string)
+}
+
+function buildAnswerArrayForAddress(fieldData: IJSONObject): IDataOutMetadata {
+  const { order } = fieldData
+
+  // NOTE: we return all labels as there are some optional fields in FormSG
+  return ADDRESS_LABELS.map((label, index) => ({
+    type: 'text',
+    label: `Response ${order}, ${label}`,
+    order: order ? `${order}.${index + 1}` : null,
+  }))
 }
 
 function buildAnswerArrayForCheckbox(
@@ -108,6 +122,8 @@ function buildAnswerArrayMetadatum(
       return buildAnswerArrayForCheckbox(fieldData)
     case 'table':
       return buildAnswerArrayForTable(fieldData)
+    case 'address':
+      return buildAnswerArrayForAddress(fieldData)
     default:
       logger.warn(`Answer array unknown fieldtype: ${fieldType}`, {
         fieldType,

packages/backend/src/apps/formsg/triggers/new-submission/get-data-out-metadata.ts

@@ -64,6 +64,10 @@ function generateVerifiedSubmitterInfoData(
   return {}
 }
 
+function generateMockAddressData(): string[] {
+  return ['51', 'BRAS BASAH ROAD', 'Lazada One', '#08-888', '189554']
+}
+
 function generateMockPaymentData(products: Partial<PaymentProduct>[]) {
   // if there are no payment products, default to a mocked one
   const firstProduct: Partial<PaymentProduct> =
@@ -114,6 +118,11 @@ async function getMockData($: IGlobalVariable) {
           }
         }
 
+        if (data.responses[formFields[i]._id].fieldType === 'address') {
+          data.responses[formFields[i]._id].answerArray =
+            generateMockAddressData()
+        }
+
         if (data.responses[formFields[i]._id].fieldType === 'attachment') {
           data.responses[formFields[i]._id].answer = MOCK_ATTACHMENT_FILE_PATH
         }