IR(ME)R authorisation: permissions, change authorised mammographer, show authorised mammographer in the right places

app/filters/nunjucks.js

@@ -110,7 +110,7 @@ const getUsername = function (userId, options = {}) {
   const user = users.find((u) => u.id === userId)
   if (!user) return userId
 
-  // Format options: full (default), short (initial + surname), initial (just initials)
+  // Format options: full (default), short (initial + surname), initial (just initials), reversed (SURNAME, First)
   const format = options.format || 'full'
 
   let formattedName
@@ -121,6 +121,9 @@ const getUsername = function (userId, options = {}) {
     case 'initial':
       formattedName = `${user.firstName.charAt(0)}${user.lastName.charAt(0)}`
       break
+    case 'reversed':
+      formattedName = `${user.lastName.toUpperCase()}, ${user.firstName}`
+      break
     case 'full':
     default:
       formattedName = `${user.firstName} ${user.lastName}`

app/lib/utils/roles-and-permissions.js

@@ -1,6 +1,7 @@
 // app/lib/utils/roles-and-permissions.js
 
 const { isMedicalHistoryItemRemoved } = require('./medical-information')
+const { getUsername } = require('../../filters/nunjucks')
 
 // Implanted devices that need a mammographer with implant imaging training.
 // The prototype treats every device type as needing it - narrow this list if
@@ -79,17 +80,9 @@ const hasAnyPermission = (user, permissions) => {
   return permissions.some((permission) => hasPermission(user, permission))
 }
 
-/**
- * Check whether an appointment needs a user with implant imaging training
- *
- * Breast implants and implanted medical devices both need it, but only while
- * they are still in place - once removed, any clinician can image the
- * participant.
- *
- * @param {object} appointment - Appointment object
- * @returns {boolean} Whether implant imaging training is needed
- */
-const requiresImplantImaging = (appointment) => {
+// Breakdown of what on an appointment needs implant imaging training. Kept
+// unexported so it doesn't become a Nunjucks filter.
+const getImplantImagingNeeds = (appointment) => {
   const medicalHistory = appointment?.medicalInformation?.medicalHistory || {}
 
   const hasActiveBreastImplants = (
@@ -104,9 +97,77 @@ const requiresImplantImaging = (appointment) => {
     }
   )
 
+  return { hasActiveBreastImplants, hasActiveDevice }
+}
+
+/**
+ * Check whether an appointment needs a user with implant imaging training
+ *
+ * Breast implants and implanted medical devices both need it, but only while
+ * they are still in place - once removed, any clinician can image the
+ * participant.
+ *
+ * @param {object} appointment - Appointment object
+ * @returns {boolean} Whether implant imaging training is needed
+ */
+const requiresImplantImaging = (appointment) => {
+  const { hasActiveBreastImplants, hasActiveDevice } =
+    getImplantImagingNeeds(appointment)
+
   return hasActiveBreastImplants || hasActiveDevice
 }
 
+/**
+ * Describe why an appointment needs a mammographer with implant imaging
+ * training, for use in page content
+ *
+ * @param {object} appointment - Appointment object
+ * @returns {string} Reason text, or '' when implant imaging is not needed
+ */
+const getImplantImagingReason = (appointment) => {
+  const { hasActiveBreastImplants, hasActiveDevice } =
+    getImplantImagingNeeds(appointment)
+
+  if (hasActiveBreastImplants && hasActiveDevice) {
+    return 'breast implants and an implanted medical device'
+  }
+  if (hasActiveBreastImplants) return 'breast implants'
+  if (hasActiveDevice) return 'an implanted medical device'
+  return ''
+}
+
+/**
+ * Check whether an authorised mammographer other than the current user has
+ * been nominated to take the images for an appointment
+ *
+ * @param {object} appointment - Appointment object
+ * @returns {boolean} Whether an authorised mammographer has been nominated
+ */
+const hasNominatedAuthorisedMammographer = (appointment) => {
+  return Boolean(
+    appointment?.authorisedMammographerId ||
+      appointment?.authorisedMammographerOtherName
+  )
+}
+
+/**
+ * Get the display name of the authorised mammographer nominated for an
+ * appointment
+ *
+ * Returns '' when nobody has been nominated, so callers can decide their own
+ * fallback.
+ *
+ * @param {object} appointment - Appointment object
+ * @param {object} [options] - Display options, as accepted by getUsername
+ * @returns {string} Nominated authorised mammographer's name, or ''
+ */
+const getAuthorisedMammographerName = function (appointment, options = {}) {
+  if (appointment?.authorisedMammographerId) {
+    return getUsername.call(this, appointment.authorisedMammographerId, options)
+  }
+  return appointment?.authorisedMammographerOtherName || ''
+}
+
 /**
  * Check whether a user is able to screen a given appointment
  *
@@ -208,6 +269,9 @@ module.exports = {
   hasPermission,
   hasAnyPermission,
   requiresImplantImaging,
+  getImplantImagingReason,
+  hasNominatedAuthorisedMammographer,
+  getAuthorisedMammographerName,
   canUserScreenAppointment,
   isClinician,
   isAdministrative,

app/routes/appointments/lifecycle.js

@@ -337,6 +337,94 @@ module.exports = (router) => {
     }
   )
 
+  // Change the authorised mammographer from the in-page modal, then return to
+  // the page it was opened from with a success banner if it actually changed
+  router.post(
+    '/clinics/:clinicId/appointments/:appointmentId/change-authorised-mammographer-answer',
+    (req, res) => {
+      const { clinicId, appointmentId } = req.params
+      const data = req.session.data
+      const appointmentUrl = `/clinics/${clinicId}/appointments/${appointmentId}`
+
+      const authorisedMammographerTemp =
+        data.appointment?.authorisedMammographerTemp || {}
+      const selectedUserId = authorisedMammographerTemp.userId
+      const otherName = (authorisedMammographerTemp.otherName || '')
+        .toString()
+        .trim()
+
+      const errors = []
+      if (!selectedUserId) {
+        errors.push({
+          text: 'Select who is taking the images',
+          name: 'appointment[authorisedMammographerTemp][userId]',
+          href: '#authorisedMammographerUserId'
+        })
+      } else if (selectedUserId === 'other' && !otherName) {
+        errors.push({
+          text: "Enter the mammographer's full name",
+          name: 'appointment[authorisedMammographerTemp][otherName]',
+          href: '#authorisedMammographerOtherName'
+        })
+      }
+
+      if (errors.length) {
+        errors.forEach((error) => req.flash('error', error))
+        // Back to the modal page - _modal is threaded by the modal middleware,
+        // the referrer chain has to be carried by hand
+        return res.redirect(
+          urlWithReferrer(
+            `${appointmentUrl}/change-authorised-mammographer`,
+            req.query.referrerChain
+          )
+        )
+      }
+
+      const previousAuthorisedMammographerId =
+        data.appointment?.authorisedMammographerId
+      const previousAuthorisedMammographerOtherName =
+        data.appointment?.authorisedMammographerOtherName
+
+      if (selectedUserId === 'other') {
+        data.appointment.authorisedMammographerId = null
+        data.appointment.authorisedMammographerOtherName = otherName
+      } else {
+        // Nominating yourself is the same as no nomination at all
+        data.appointment.authorisedMammographerId =
+          selectedUserId === data.currentUser?.id ? null : selectedUserId
+        data.appointment.authorisedMammographerOtherName = null
+      }
+
+      // Clear the transient modal fields so they don't leak into other forms
+      delete data.appointment.authorisedMammographerTemp
+
+      const hasChanged =
+        data.appointment.authorisedMammographerId !==
+          (previousAuthorisedMammographerId || null) ||
+        data.appointment.authorisedMammographerOtherName !==
+          (previousAuthorisedMammographerOtherName || null)
+
+      if (hasChanged) {
+        const selectedUser = (data.users || []).find(
+          (user) => user.id === selectedUserId
+        )
+        const newAuthorisedMammographerName = selectedUser
+          ? `${selectedUser.lastName.toUpperCase()}, ${selectedUser.firstName}`
+          : otherName
+        req.flash(
+          'success',
+          `Authorised mammographer updated to ${newAuthorisedMammographerName}`
+        )
+      }
+
+      const returnUrl = getReturnUrl(
+        `${appointmentUrl}/check-information`,
+        req.query.referrerChain
+      )
+      res.redirect(modalBreakout(returnUrl))
+    }
+  )
+
   // Appointment within clinic context
   router.get('/clinics/:clinicId/appointments/:appointmentId', (req, res) => {
     const { clinicId, appointmentId } = req.params

app/routes/clinics.js

@@ -482,6 +482,9 @@ module.exports = (router) => {
     }
 
     const clinicData = getClinicData(req.session.data, req.params.id)
+    if (!clinicData) {
+      return res.redirect('/clinics')
+    }
     let remainingCount = filterAppointmentsByStatus(
       clinicData.appointments,
       'remaining'

app/views/_includes/authorised-mammographer.njk

@@ -0,0 +1,56 @@
+{# app/views/_includes/authorised-mammographer.njk #}
+
+{#
+  The authorised mammographer for an in-progress appointment, alongside the
+  button that continues the workflow.
+
+  Where the current user cannot image this participant themselves and nobody
+  else has been nominated, the workflow is blocked until an authorised
+  mammographer with implant imaging training is chosen.
+
+  Set continueButtonText before including.
+#}
+
+{% set authorisedMammographerChangeHref = (appointmentUrl + "/change-authorised-mammographer") | urlWithReferrer(referrerChain | appendReferrer(currentUrl)) %}
+
+{% set needsNominatedAuthorisedMammographer = appointment.workflowStatus['review-medical-information'] != 'completed'
+  and not (currentUser | canUserScreenAppointment(appointment))
+  and not (appointment | hasNominatedAuthorisedMammographer) %}
+
+{% if needsNominatedAuthorisedMammographer %}
+
+  {% set insetTextHtml %}
+    <p>Due to {{ appointment | getImplantImagingReason }} you do not have the relevant permissions to take all the mammograms required for this appointment. Change the mammographer to someone authorised to take these images or {{ appLink({ text: "exit the appointment", href: (appointmentUrl + "/exit-appointment") | urlWithReferrer(referrerChain) }) | trim | safe }}.</p>
+  {% endset %}
+
+  {{ insetText({
+    html: insetTextHtml
+  }) }}
+
+  <div class="nhsuk-grid-row">
+    <div class="nhsuk-grid-column-two-thirds">
+      <div class="nhsuk-button-group">
+        {{ button({
+          text: "Change mammographer",
+          href: authorisedMammographerChangeHref,
+          classes: "nhsuk-u-margin-bottom-0"
+        } | openInModal) }}
+      </div>
+    </div>
+  </div>
+
+{% else %}
+
+  {% set authorisedMammographerName = (appointment | getAuthorisedMammographerName({ format: "reversed" })) or (currentUser.id | getUsername({ format: "reversed" })) %}
+
+  <div class="nhsuk-grid-row">
+    <div class="nhsuk-grid-column-two-thirds">
+      {{ button({
+        text: continueButtonText,
+        classes: "nhsuk-u-margin-bottom-0 js-complete-all-sections"
+      }) }}
+      <p class="nhsuk-u-margin-top-2">Authorised mammographer: <span class="nhsuk-u-font-weight-bold">{{ authorisedMammographerName }}</span> ({{ appLink({ text: "change", href: authorisedMammographerChangeHref } | openInModal) | trim | safe }})</p>
+    </div>
+  </div>
+
+{% endif %}

app/views/_includes/summary-lists/medical-information/mammogram-image-data.njk

@@ -137,7 +137,7 @@
   }) %}
 {% endif %}
 
-{# Machine room #}
+{# Mammogram location #}
 {% if appointment.mammogramData.machineRoom %}
   {# Check if this is a mobile clinic #}
   {% set isMobileClinic = (clinic.location.type == 'mobile_unit') %}
@@ -148,14 +148,14 @@
       {
         href: "./images-room-selection" | urlWithReferrer(referrerChain, scrollTo),
         text: "Change",
-        visuallyHiddenText: "machine room"
+        visuallyHiddenText: "mammogram location"
       }
     ] %}
   {% endif %}
 
   {% set summaryRows = summaryRows | push({
     key: {
-      text: "Machine room"
+      text: "Mammogram location"
     },
     value: {
       text: appointment.mammogramData.machineRoom
@@ -166,6 +166,42 @@
   }) %}
 {% endif %}
 
+{# Authorised mammographer - whoever was nominated to take the images, falling
+   back to whoever ran the appointment #}
+{% set authorisedMammographerName = appointment | getAuthorisedMammographerName({ format: "reversed" }) %}
+{% if not authorisedMammographerName %}
+  {% if appointment.sessionDetails.endedBy %}
+    {% set authorisedMammographerName = appointment.sessionDetails.endedBy | getUsername({ format: "reversed" }) %}
+  {% else %}
+    {% set authorisedMammographerName = appointment.sessionDetails.startedBy | getUsername({ format: "reversed" }) %}
+  {% endif %}
+{% endif %}
+
+{% if authorisedMammographerName %}
+  {% set authorisedMammographerActions = [] %}
+  {% if allowEdits and authorisedMammographerChangeHref %}
+    {% set authorisedMammographerActions = [
+      ({
+        href: authorisedMammographerChangeHref,
+        text: "Change",
+        visuallyHiddenText: "authorised mammographer"
+      } | openInModal)
+    ] %}
+  {% endif %}
+
+  {% set summaryRows = summaryRows | push({
+    key: {
+      text: "Authorised mammographer"
+    },
+    value: {
+      text: authorisedMammographerName
+    },
+    actions: {
+      items: authorisedMammographerActions
+    }
+  }) %}
+{% endif %}
+
 {# Combined views taken (showing all view information in one row) #}
 {# Sort views by side and standard order before displaying #}
 {% set sortedViews = [] %}

app/views/appointments/appointment.html

@@ -229,11 +229,11 @@
         },
         {
           key: {
-            text: "Screened by"
+            text: "Run by"
           },
           value: {
-            html: (appointment.sessionDetails.endedBy | getUsername) + 
-                  ((" and " + (appointment.sessionDetails.authors | last).userId | getUsername) 
+            html: (appointment.sessionDetails.endedBy | getUsername({ format: "reversed" })) + 
+                  ((" and " + ((appointment.sessionDetails.authors | last).userId | getUsername({ format: "reversed" }))) 
                    if appointment.sessionDetails.authors and appointment.sessionDetails.authors.length > 0 
                    and (appointment.sessionDetails.authors | last).userId != appointment.sessionDetails.endedBy
                    else "")
@@ -242,6 +242,17 @@
             items: []
           }
         } if appointment.status == "complete" and appointment.sessionDetails.endedBy else {},
+        {
+          key: {
+            text: "Authorised mammographer"
+          },
+          value: {
+            html: (appointment | getAuthorisedMammographerName({ format: "reversed" })) or (appointment.sessionDetails.endedBy | getUsername({ format: "reversed" })) or (appointment.sessionDetails.startedBy | getUsername({ format: "reversed" }))
+          },
+          actions: {
+            items: []
+          }
+        } if appointment.status == "complete" and appointment.sessionDetails.endedBy else {},
         {
           key: {
             text: "Special appointment"