Merge pull request #14 from DEFRA/fix/DF-648-repeater-columns

Ensures uniqueness of repeater columns, Updated docs

Author: jbarnsley10

docs/SHAREPOINT_SETUP.md

@@ -11,9 +11,9 @@ In order for a submission to get written to a Sharepoint list, the following is
 - the values of formId, siteId, listId, and status (live or draft) must exist in the forms-sharepoint-listener config
 
 - the Sharepoint list (denoted by siteId and listId) must contain ALL columns from the source form
-  - the Sharepoint list column names must match the short description from each question
+  - the Sharepoint list column names must match the short description from each question **(and the naming is case-sensitive)**
 
-  - the short descriptions from the form must all be unique
+  - the short descriptions from the form must all be unique (within the first 32 characters if spaces are removed)
 
   - the Sharepoint list column datatypes must match according to the ‘Datatype mappings’ table below
 
@@ -39,6 +39,8 @@ If your form uses repeater pages, you need to setup the appropriate Sharepoint l
 
 - Field area 3
 
+**Note** - there is a limit of 32 characters on the ‘internal’ column name (the name used to lookup the column) so any repeater short descriptions should be no more than 32 characters when the repeat number is added and spaces are removed e.g. ‘My repeater field 25’ (if my max repeaters is 25) which strips to ‘Myrepeaterfield25’ should be no longer than 32 characters.
+
 ## Configuration structure
 
 The service configuration (set by the development team or CDP) consists of zero or more rows of the following structure:
@@ -65,6 +67,12 @@ A valid config value which allow two different forms to write to two different S
 {"mappings":[{"formId":"695e4ec0e57ae17190adacba","siteId":"071a12a4-5ed0-4a08-bbf6-93a762e89bdb","listId":"0695483b-f344-419f-bc93-ee8aeee1b788","status":"draft"},{"formId":"696104cfab2e01c384cf6382","siteId":"071a12a4-5ed0-4a08-bbf6-93a762e89bdb","listId":"69c339f4-5c06-42ab-89f9-7db121c61fc3","status":"live"}]}
 ```
 
+## Renaming a Sharepoint column
+
+Although you can rename a Sharepoint column name (for example if you change a question’s short description), the original ‘internal’ Sharepoint column name remains. All you are doing by renaming the Sharepoint column is changing the display name.
+
+So if you need to change a Sharepoint column name to match a question’s short description, you will have to add a new column with the correct name, copy over any data from the original column, then delete the original column.
+
 ## Determining the siteId and listId of a Sharepoint list
 
 Normally a Sharepoint list is referred to by a url containing its site name and list name e.g. https://defradev.sharepoint.com/teams/TEAM164UAT/Lists/TestList1/AllItems.aspx

src/service/__stubs__/forms.js

@@ -245,7 +245,7 @@ export const definitionForSharepointTest = buildDefinition({
         },
         schema: {
           min: 1,
-          max: 5
+          max: 15
         }
       }
     },

src/service/sharepoint.js

@@ -209,12 +209,22 @@ export async function saveToSharepointList(message) {
 
     if (hasRepeater(component.page.pageDef)) {
       const repeaterName = component.page.pageDef.repeat.options.name
+      const maxRepeaterItems = /** @type {number} */ (
+        component.page.pageDef.repeat.schema.max
+      )
       const hasRepeaterData = repeaterName in data.repeaters
       const items = hasRepeaterData ? data.repeaters[repeaterName] : []
 
       for (let index = 0; index < items.length; index++) {
         const value = getValue(items[index], key, component)
-        const componentKey = `${getSharepointFieldName(component)}${index + 1}`
+        const baseComponentKey = getSharepointFieldName(component)
+        if (baseComponentKey.length + `${maxRepeaterItems}`.length > 32) {
+          throw new Error(
+            `Repeater columns plus number index cannot be longer than 32 characters (with spaces stripped) - shortDesc: ${baseComponentKey}${maxRepeaterItems} formId: ${formId}`
+          )
+        }
+
+        const componentKey = `${baseComponentKey}${index + 1}`
 
         fields.set(componentKey, value)
       }

src/service/sharepoint.test.js

@@ -98,6 +98,19 @@ line 3`,
         }
       })
     })
+
+    it('should throw if repeater name will blow limits', async () => {
+      const definition = structuredClone(definitionForSharepointTest)
+      const page = /** @type {PageQuestion} */ (definition.pages[2])
+      const component = /** @type {TextFieldComponent} */ (page.components[0])
+      component.shortDescription = 'Repeater Name That Is Too Long Herexx'
+      jest.mocked(getFormDefinition).mockResolvedValue(definition)
+      const message = structuredClone(messageForSharepointTest)
+      message.meta.formId = 'my-form-id'
+      await expect(() => saveToSharepointList(message)).rejects.toThrow(
+        'Repeater columns plus number index cannot be longer than 32 characters (with spaces stripped) - shortDesc: RepeaterNameThatIsTooLongHerexx15 formId: my-form-id'
+      )
+    })
   })
 
   describe('escapeFieldName', () => {
@@ -143,3 +156,7 @@ line 3`,
     })
   })
 })
+
+/**
+ * @import { PageQuestion, TextFieldComponent } from '@defra/forms-model'
+ */