Merge pull request #5853 from nhsuk/school-info

Update `school.name` in reporting API totals view

Author: mikejamesthompson

db/migrate/20260122093544_update_reporting_api_totals_to_version_4.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class UpdateReportingAPITotalsToVersion4 < ActiveRecord::Migration[8.1]
+  def change
+    update_view :reporting_api_totals,
+                version: 4,
+                revert_to_version: 3,
+                materialized: true
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[8.1].define(version: 2026_01_19_161311) do
+ActiveRecord::Schema[8.1].define(version: 2026_01_22_093544) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pg_catalog.plpgsql"
   enable_extension "pg_trgm"
@@ -1387,8 +1387,8 @@
           END AS patient_school_urn,
           CASE
               WHEN (school.name IS NOT NULL) THEN school.name
-              WHEN (pat.home_educated = true) THEN 'Home educated'::text
-              ELSE 'Unknown'::text
+              WHEN (pat.home_educated = true) THEN 'Home-schooled'::text
+              ELSE 'Unknown school'::text
           END AS patient_school_name,
       (ar.patient_id IS NOT NULL) AS is_archived,
       (EXISTS ( SELECT 1

db/views/reporting_api_totals_v04.sql

@@ -0,0 +1,91 @@
+SELECT
+  -- Composite key for unique index (required for concurrent refresh)
+  pps.patient_id || '-' ||
+  pps.programme_type || '-' ||
+  tl.team_id || '-' ||
+  pl.location_id || '-' ||
+  pps.academic_year                     AS id,
+
+  -- Identifiers (for counting and grouping)
+  pps.patient_id,                       -- COUNT(DISTINCT patient_id) for totals
+  pps.academic_year,                    -- Filter: ?academic_year=2024
+  pps.programme_type,                   -- Filter: ?programme=hpv
+  pps.status,                           -- Scope: .vaccinated (status IN 60,61)
+  tl.team_id,                           -- Filter: by user's team_ids
+  pl.location_id                        AS session_location_id,  -- Year group eligibility subquery
+
+  -- Patient demographics (used for filtering and CSV grouping)
+  CASE pat.gender_code
+    WHEN 0 THEN 'not known'
+    WHEN 1 THEN 'male'
+    WHEN 2 THEN 'female'
+    WHEN 9 THEN 'not specified'
+    ELSE NULL
+  END                                   AS patient_gender,       -- Filter: ?gender=female
+
+  pps.academic_year
+    - pat.birth_academic_year - 5       AS patient_year_group,   -- Filter: ?year_group=8,9
+  COALESCE(la.mhclg_code, '')           AS patient_local_authority_code,        -- Filter: ?local_authority=E09000001
+  COALESCE(la.mhclg_code, '')           AS patient_school_local_authority_code, -- Filter: ?school_local_authority=E09000001
+
+  -- School info (for CSV grouping by school)
+  CASE
+    WHEN school.urn IS NOT NULL THEN school.urn
+    WHEN pat.home_educated = true THEN '999999'
+    ELSE '888888'
+  END                                   AS patient_school_urn,
+  CASE
+    WHEN school.name IS NOT NULL THEN school.name
+    WHEN pat.home_educated = true THEN 'Home-schooled'
+    ELSE 'Unknown school'
+  END                                   AS patient_school_name,
+
+  -- Status flags
+  ar.patient_id IS NOT NULL             AS is_archived,  -- Scope: .not_archived
+
+  -- Parent declared "already vaccinated" (counts toward vaccinated total)
+  EXISTS (
+    SELECT 1 FROM consents con
+    WHERE con.patient_id         = pps.patient_id
+      AND con.programme_type     = pps.programme_type
+      AND con.academic_year      = pps.academic_year
+      AND con.invalidated_at     IS NULL
+      AND con.withdrawn_at       IS NULL
+      AND con.response           = 1  -- refused
+      AND con.reason_for_refusal = 1  -- already_vaccinated
+  )                                     AS has_already_vaccinated_consent
+
+-- Source: pre-computed patient status per programme/year
+FROM patient_programme_statuses pps
+
+-- Patient record (for demographics and exclusion checks)
+JOIN patients pat
+  ON pat.id = pps.patient_id
+
+-- Where the patient is enrolled this year (links to team via location)
+JOIN patient_locations pl
+  ON pl.patient_id    = pps.patient_id
+ AND pl.academic_year = pps.academic_year
+
+-- Which team owns this location (for team_id filtering)
+JOIN team_locations tl
+  ON tl.location_id   = pl.location_id
+ AND tl.academic_year = pps.academic_year
+
+-- Check if patient is archived by this team (LEFT: most aren't)
+LEFT JOIN archive_reasons ar
+  ON ar.patient_id = pps.patient_id
+ AND ar.team_id    = tl.team_id
+
+-- Patient's school (LEFT: home-educated patients have no school)
+LEFT JOIN locations school
+  ON school.id = pat.school_id
+
+-- School's local authority (LEFT: school may not have LA set)
+LEFT JOIN local_authorities la
+  ON la.gias_code = school.gias_local_authority_code
+
+-- Exclude patients who shouldn't appear in any reports
+WHERE pat.invalidated_at IS NULL  -- Merged/duplicate record
+  AND pat.restricted_at  IS NULL  -- S31 restricted access
+  AND pat.date_of_death  IS NULL  -- Deceased

spec/controllers/api/reporting/totals_controller_spec.rb

@@ -242,12 +242,12 @@
       expect(school_two_data["vaccinated"]).to eq(1)
       expect(school_two_data["not_vaccinated"]).to eq(0)
 
-      expect(home_educated_data["school_name"]).to eq("Home educated")
+      expect(home_educated_data["school_name"]).to eq("Home-schooled")
       expect(home_educated_data["cohort"]).to eq(1)
       expect(home_educated_data["vaccinated"]).to eq(0)
       expect(home_educated_data["not_vaccinated"]).to eq(1)
 
-      expect(unknown_data["school_name"]).to eq("Unknown")
+      expect(unknown_data["school_name"]).to eq("Unknown school")
       expect(unknown_data["cohort"]).to eq(1)
       expect(unknown_data["vaccinated"]).to eq(0)
       expect(unknown_data["not_vaccinated"]).to eq(1)