Add legal mechanism to Record vaccinations and Records sections (#495)

This adds legal mechanism into the streamlined journey.

It also adds legal mechanisms to the vaccines section as checkbox option
you can select. This then reduces the number of options shown when
recording a vaccination, or if you only select a single option then it
skips the question entirely.


## Record vaccinations

<img width="761" height="552" alt="Screenshot 2025-10-21 at 13 42 49"
src="https://github.com/user-attachments/assets/476f95ed-dedb-41b8-88fa-c26bcf3f4346"
/>

## Check answers summary

<img width="782" height="698" alt="Screenshot 2025-10-21 at 13 43 31"
src="https://github.com/user-attachments/assets/fbdb5785-62a6-405c-a62a-2a2046b51f2b"
/>

## Records section

<img width="692" height="695" alt="Screenshot 2025-10-21 at 13 57 09"
src="https://github.com/user-attachments/assets/35cfa19c-820d-4778-a155-eba3fb69e2b6"
/>

---------

Co-authored-by: Anna-Sutton <[email protected]>

Author: frankieroberto

app/data/session-data-defaults.js

@@ -17,6 +17,27 @@ module.exports = {
   currentOrganisationId: "RW3",
   currentRegionId: "Y62",
   vaccinationsRecorded: [],
+  legalMechanisms: [
+    {
+      value: "National protocol",
+      text: "National protocol"
+    },
+    {
+      value: "Patient group direction",
+      text: "Patient group direction (PGD)"
+    },
+    {
+      value: "Patient specific direction",
+      text: "Patient specific direction (PSD)"
+    },
+    {
+      value: "Written instruction",
+      text: "Written instruction",
+      hint: {
+        text: "Occupational health only"
+      }
+    }
+  ],
   data: [
     "Patients", "Staff", "Site or delivery team", "Assessment and consent", "Vaccination"
   ],

app/routes/helpers.js

@@ -6,6 +6,8 @@ module.exports = router => {
     const data = req.session.data
     const currentOrganisation = res.locals.currentOrganisation
 
+    const allLegalMechanisms = data.legalMechanisms.map((legalMechaism) => legalMechaism.value)
+
     let vaccineStock = data.vaccineStock
 
     const organisationVaccines = currentOrganisation.vaccines
@@ -55,6 +57,7 @@ module.exports = router => {
           id: generatedVaccineId,
           vaccine: vaccine.name,
           vaccineProduct: vaccineProduct.name,
+          legalMechanisms: allLegalMechanisms,
           siteId: siteId,
           batches: batches
         })
@@ -103,6 +106,8 @@ module.exports = router => {
       const randomVaccineProduct = randomItem(vaccineProductsInStock)
       const randombatchNumber = randomItem(randomVaccineProduct.batches)
 
+      const randomLegalMechanism = randomItem(data.legalMechanisms).value
+
       const vaccinator = randomItem(vaccinators)
 
       const randomName = randomItem(listOfFirstNames) + " " + randomItem(listOfLastNames)
@@ -127,6 +132,7 @@ module.exports = router => {
         batchNumber: randombatchNumber.batchNumber,
         batchExpiryDate: "2025-01-05",
         vaccinatorId: vaccinator.id,
+        legalMechanism: randomLegalMechanism,
         eligibility: ["Pregnant"],
         pregnancyDueDate: {
           day: "04",

app/routes/record-vaccinations.js

@@ -72,10 +72,10 @@ module.exports = router => {
 
 
     if (req.query.showErrors === "yes") {
-      if (!req.session.data.deliveryTeam) {
+      if (!req.session.data.siteId) {
         errors.push({
           text: "Select a site",
-          href: "#delivery-team-1"
+          href: "#site-id"
         })
       }
     }
@@ -89,7 +89,7 @@ module.exports = router => {
   router.post('/record-vaccinations/answer-delivery-team', (req, res) => {
     const data = req.session.data
 
-    if (!data.deliveryTeam) {
+    if (!data.siteId) {
       return res.redirect('/record-vaccinations/delivery-team?showErrors=yes')
     } else {
       res.redirect('/record-vaccinations/vaccinator')
@@ -144,7 +144,7 @@ module.exports = router => {
     let vaccineError, vaccineProductError
     const data = req.session.data
 
-    const vaccineStock = data.vaccineStock.filter((vaccine) => vaccine.siteId === data.deliveryTeam)
+    const vaccineStock = data.vaccineStock.filter((vaccine) => vaccine.siteId === data.siteId)
     const vaccinesAdded = [...new Set(vaccineStock.map((vaccineAdded) => vaccineAdded.vaccine))]
     const vaccineProductsAdded = [...new Set(vaccineStock.map((vaccineAdded) => vaccineAdded.vaccineProduct))]
 
@@ -190,7 +190,8 @@ module.exports = router => {
 
     if (nhsNumberKnown === "yes" && nhsNumber.match(/^\d{10}$/) &&  nhsNumber.startsWith('9')) {
 
-      req.session.data.patientName = "Jodie Brown"
+      req.session.data.firstName = "Jodie"
+      req.session.data.lastName = "Brown"
       req.session.data.dateOfBirth = {day: "15", month: "8", year: "1949"}
       req.session.data.postcode = "GD3 I83"
 
@@ -309,7 +310,8 @@ module.exports = router => {
       // Otherwise pretend there is a single result and
       // go to patient details page
       } else {
-        data.patientName = 'Jodie Brown'
+        data.firstName = 'Jodie'
+        data.lastName =  'Brown'
         data.nhsNumber = '9123456788'
         res.redirect('/record-vaccinations/patient-history')
       }
@@ -405,6 +407,26 @@ module.exports = router => {
 
   })
 
+  router.get('/record-vaccinations/legal-mechanism', (req, res) => {
+    const data = req.session.data
+
+    const vaccine = data.vaccineStock.find(function(batch) {
+      return (batch.vaccineProduct === data.vaccineProduct) &&
+        (batch.vaccine === data.vaccine)
+    })
+    if (!vaccine) { res.redirect('/record-vaccinations'); return }
+
+    const allLegalMechanisms = data.legalMechanisms
+
+    const legalMechanisms = allLegalMechanisms.filter((legalMechanism) => {
+      return vaccine.legalMechanisms.includes(legalMechanism.value)
+    })
+
+    res.render('record-vaccinations/legal-mechanism', {
+      legalMechanisms
+    })
+
+  })
 
   router.get('/record-vaccinations/patient-estimated-due-date', (req, res) => {
 
@@ -524,7 +546,6 @@ module.exports = router => {
 
   })
 
-
   router.get('/record-vaccinations/eligibility', (req, res) => {
     const data = req.session.data
     const eligibility = data.eligibility
@@ -554,7 +575,7 @@ module.exports = router => {
 
       nextPage = "/record-vaccinations/eligibility?showErrors=yes"
 
-    } else if (data.patientName && data.patientName != "" && data.repeatPatient === "yes") {
+    } else if (data.firstName && data.firstName != "" && data.repeatPatient === "yes") {
 
       if (data.vaccine === "Pertussis" || ((data.vaccine == "RSV") && (eligibility === "Pregnant"))) {
         nextPage = "/record-vaccinations/patient-estimated-due-date"
@@ -580,6 +601,7 @@ module.exports = router => {
   router.post('/record-vaccinations/confirmed', (req, res) => {
 
     const data = req.session.data
+    const currentOrganisation = res.locals.currentOrganisation
 
     const generatedId = Math.floor(Math.random() * 10000000).toString()
 
@@ -591,9 +613,9 @@ module.exports = router => {
     const yearToday = (dateToday.getFullYear())
 
     if (data.vaccinationToday === 'yes') {
-      data.vaccinationDate.day = dayToday
-      data.vaccinationDate.month = monthToday
-      data.vaccinationDate.year = yearToday
+      data.vaccinationDate.day = String(dayToday)
+      data.vaccinationDate.month = String(monthToday)
+      data.vaccinationDate.year = String(yearToday)
     }
 
     data.vaccinationsRecorded.push({
@@ -602,13 +624,15 @@ module.exports = router => {
       vaccine: data.vaccine,
       vaccineProduct: data.vaccineProduct,
       patient: {
-        name: data.firstName + " " + data.lastName,
+        name: "" + data.firstName + " " + data.lastName,
         nhsNumber: data.nhsNumber
       },
       batchNumber: data.vaccineBatch,
       batchExpiryDate: "2025-12-05",
-      siteId: data.deliveryTeam,
+      organisationId: currentOrganisation.id,
+      siteId: data.siteId,
       vaccinatorId: data.vaccinatorId,
+      legalMechanism: data.legalMechanism,
       eligibility: data.eligibility,
       pregnancyDueDate: data.pregnancyDueDate,
       consent: data.consent,
@@ -703,7 +727,8 @@ module.exports = router => {
 
     if (answer === 'same-vaccination-another-patient') {
 
-      req.session.data.patientName = ""
+      req.session.data.firstName = ""
+      req.session.data.lastName = ""
       req.session.data.nhsNumber = ""
 
       // newly added batch becomes the default
@@ -721,6 +746,7 @@ module.exports = router => {
       req.session.data.vaccineProduct = ""
       req.session.data.vaccineBatch = ""
       req.session.data.eligibility = ""
+      req.session.data.legalMechanism = ""
 
       res.redirect('/record-vaccinations/vaccine?repeatPatient=yes&repeatVaccination=no')
 
@@ -731,6 +757,7 @@ module.exports = router => {
       req.session.data.vaccineBatch = ""
       req.session.data.eligibility = ""
       req.session.data.nhsNumber = ""
+      req.session.data.legalMechanism = ""
 
       res.redirect('/record-vaccinations/vaccine')
     } else {
@@ -813,14 +840,35 @@ module.exports = router => {
     const vaccineBatch = data.vaccineBatch
     const vaccine = data.vaccine
 
+    const vaccineOptions = data.vaccineStock.find(function(batch) {
+      return (batch.vaccineProduct === data.vaccineProduct) &&
+        (batch.vaccine === data.vaccine)
+    })
+    if (!vaccineOptions) { res.redirect('/record-vaccinations'); return }
+
+    const allLegalMechanisms = data.legalMechanisms
+
+    const legalMechanisms = allLegalMechanisms.filter((legalMechanism) => {
+      return vaccineOptions.legalMechanisms.includes(legalMechanism['value'])
+    })
+
     let redirectPath
 
     if (vaccineBatch === "add-new") {
       redirectPath = "/record-vaccinations/add-batch"
     } else if (!vaccineBatch) {
       redirectPath = "/record-vaccinations/batch?showError=yes"
     } else if (["COVID-19", "flu", "flu (London service)", "RSV", "pneumococcal"].includes(data.vaccine)) {
-      redirectPath = "/record-vaccinations/eligibility"
+
+      if (legalMechanisms.length > 1) {
+        redirectPath = "/record-vaccinations/legal-mechanism"
+      } else {
+        // Set legal mechanism to the only option available and skip
+        // the question
+        data.legalMechanism = legalMechanisms[0].value
+        redirectPath = "/record-vaccinations/eligibility"
+      }
+
     } else if (data.repeatPatient === "yes") {
       redirectPath = "/record-vaccinations/patient-estimated-due-date"
     } else {
@@ -868,7 +916,7 @@ module.exports = router => {
     } else if ((data.vaccine === "pertussis") || (data.vaccine === "MMR")) {
       nextPage = "/record-vaccinations/patient"
     } else {
-      nextPage = "/record-vaccinations/eligibility"
+      nextPage = "/record-vaccinations/legal-mechanism"
     }
 
     res.redirect(nextPage)
@@ -959,6 +1007,24 @@ module.exports = router => {
     })
   })
 
+  router.post('/record-vaccinations/answer-legal-mechanism', (req, res) => {
+    const data = req.session.data
+
+    if (!data.legalMechanism) {
+
+      const legalMechanismError = {
+        text: "Select legal mechanism",
+        href: "#legal-mechanism"
+      }
+
+      res.render('record-vaccinations/legal-mechanism', {
+        legalMechanismError
+      })
+    } else {
+      res.redirect('/record-vaccinations/eligibility')
+    }
+  })
+
   router.post('/record-vaccinations/answer-consent', (req, res) => {
     const data = req.session.data
     const consent = data.consent

app/routes/records.js

@@ -53,7 +53,8 @@ module.exports = router => {
 
   if (data.nhsNumberKnown === "yes") {
 
-    req.session.data.patientName = "Jodie Brown"
+    req.session.data.firstName = "Jodie"
+    req.session.data.firstName = "Brown"
     req.session.data.dateOfBirth = {day: "15", month: "8", year: "1949"}
     req.session.data.postcode = "GD3 I83"
 
@@ -135,6 +136,10 @@ module.exports = router => {
       vaccination.batchNumber = data.batchNumber
     }
 
+    if (data.legalMechanism) {
+      vaccination.legalMechanism = data.legalMechanism
+    }
+
     if (data.notes) {
       vaccination.notes = data.notes
     }
@@ -157,7 +162,6 @@ module.exports = router => {
 
     if (firstName && lastName && dateOfBirth) {
 
-      data.patientName = firstName + " " + lastName
       data.nhsNumber = '9123456788'
 
       res.redirect('/records/patient-history')

app/routes/vaccines.js

@@ -14,6 +14,7 @@ module.exports = (router) => {
       vaccine: data.vaccine,
       vaccineProduct: data.vaccineProduct,
       siteId: data.siteId,
+      legalMechanisms: data.vaccineLegalMechanisms,
       batches: [
         {
           id: Math.floor(Math.random() * 10000000).toString(),
@@ -33,6 +34,7 @@ module.exports = (router) => {
     req.session.data.batchExpiryDate.day = ''
     req.session.data.batchExpiryDate.month = ''
     req.session.data.batchExpiryDate.year = ''
+    req.session.data.vaccineLegalMechanisms = ''
 
     res.redirect('/vaccines/' + generatedId)
   })
@@ -107,6 +109,12 @@ module.exports = (router) => {
     res.render('vaccines/add-batch')
   })
 
+  // Viewing legal mechanisms page
+  router.get('/vaccines/legal-mechanisms', (req, res) => {
+
+    res.render('vaccines/legal-mechanisms')
+  })
+
   // Viewing check answers page
   router.get('/vaccines/check', (req, res) => {
 
@@ -145,6 +153,7 @@ module.exports = (router) => {
     req.session.data.batchExpiryDate.day = ''
     req.session.data.batchExpiryDate.month = ''
     req.session.data.batchExpiryDate.year = ''
+    req.session.data.vaccineLegalMechanisms = ''
 
     res.redirect('/vaccines/' + vaccine.id)
   })

app/views/lists/list.html

@@ -96,7 +96,7 @@ <h1 class="nhsuk-heading-l">{{ pageName }}</h1>
                 {{ patient.dateOfBirth | govukDate }}
               </td>
               <td class="nhsuk-table__cell">
-                <a class="nhsuk-link" href="/record-vaccinations/patient-history?patientName={{ patient.firstName}} {{ patient.lastName }}&nhsNumber={{ patient.nhsNumber }}&dateOfBirth={{ patient.dateOfBirth }}?fromListId={{ patientList.id }}">Record</a>
+                <a class="nhsuk-link" href="/record-vaccinations/patient-history?firstName={{ patient.firstName}}&lastName{{ patient.lastName }}&nhsNumber={{ patient.nhsNumber }}&dateOfBirth={{ patient.dateOfBirth }}?fromListId={{ patientList.id }}">Record</a>
               </td>
               <td class="nhsuk-table__cell nhsuk-table__cell--numeric">
                 <a class="nhsuk-link" href="/lists/remove">Remove

app/views/lists/record/done.html

@@ -2,8 +2,6 @@
 
 {% set pageName = "Vaccination saved" %}
 
-{% set patientName = data.patientName if data.patientName else "Jodies Smith" %}
-
 {% set currentSection = "vaccinate" %}
 
 {% block content %}