Merge pull request #6578 from NHSDigital/alistair/imports-help-text-content-tweak

Improve content on vaccination record upload page

Author: alistair-white-horne-tng

app/components/app_import_format_details_component.html.erb

@@ -1,4 +1,4 @@
-<%= govuk_details(summary_text:) do %>
+<%= govuk_details(summary_text: "What your CSV file must include") do %>
   <p>Make sure the CSV you upload uses the following columns:</p>
 
   <%= govuk_table(classes: "app-table--csv app-table--small") do |table|

app/components/app_import_format_details_component.rb

@@ -10,23 +10,6 @@ def initialize(import:)
   delegate :team, to: :@import
   delegate :govuk_details, :govuk_table, to: :helpers
 
-  def summary_text
-    case @import
-    when ClassImport
-      "How to format your Mavis CSV file for class lists"
-    when CohortImport
-      "How to format your Mavis CSV file for child records"
-    when ImmunisationImport
-      if team.has_national_reporting_access?
-        "How to format your CSV file for vaccination records"
-      else
-        "How to format your Mavis CSV file for vaccination records"
-      end
-    else
-      raise ArgumentError, "Unsupported import type: #{@import.class}"
-    end
-  end
-
   def columns
     case @import
     when ClassImport
@@ -44,7 +27,7 @@ def class_import_columns
         {
           name: "CHILD_POSTCODE",
           notes:
-            "Optional, must be formatted as a valid postcode, for example #{tag.i("SW1A 1AA")}."
+            "Optional, must be a full postcode, for example #{tag.i("SW1A 1AA")}"
         }
       ] + parent_columns
   end
@@ -55,7 +38,7 @@ def cohort_import_columns
         {
           name: "CHILD_POSTCODE",
           notes:
-            "#{tag.strong("Required")}, must be formatted as a valid postcode, for example #{tag.i("SW1A 1AA")}."
+            "#{tag.strong("Required")}, must be a full postcode, for example #{tag.i("SW1A 1AA")}"
         },
         {
           name: "CHILD_SCHOOL_URN",
@@ -77,33 +60,26 @@ def immunisation_import_columns
 
   def point_of_care_immunisation_import_columns
     organisation_code(optionality: "Optional") +
-      school_urn(optionality: "Optional") + school_name +
-      nhs_number(optionality: "Optional") +
-      patient_demographics(optionality: "Required") +
-      date_and_time_of_vaccination(date_optionality: "Required") +
+      school_urn(optionality: "Optional") + school_name + nhs_number +
+      patient_demographics + date_and_time_of_vaccination +
       vaccinated(
-        optionality: "Required",
-        extra_notes:
-          "Can be omitted if #{tag.code("VACCINE_GIVEN")} is provided."
+        notes:
+          "Enter #{tag.i("Y")} or #{tag.i("N")}. Mavis will assume #{tag.i("Y")} if " \
+            "#{tag.code(" VACCINE_GIVEN ")} is provided."
       ) + vaccine_and_batch + programme + anatomical_site +
       reason_not_vaccinated_and_notes + dose_sequence + care_setting +
       performing_professional
   end
 
   def national_reporting_immunisation_import_columns
-    organisation_code(optionality: "Mandatory") +
-      school_urn(optionality: "Mandatory") +
-      nhs_number(optionality: "Required") +
-      patient_demographics(
-        optionality: "Mandatory",
-        gender_field_name: "PERSON_GENDER"
-      ) +
+    organisation_code(optionality: "Required") +
+      school_urn(optionality: "Required") + nhs_number +
+      patient_demographics(gender_field_name: "PERSON_GENDER") +
       vaccinated(
-        optionality: "Optional",
-        extra_notes:
-          "Rows with the value #{tag.i("N")} will not be validated and will not be imported."
-      ) + date_and_time_of_vaccination(date_optionality: "Mandatory") +
-      national_reporting_vaccine_and_batch +
+        notes:
+          "Optional, enter #{tag.i("Y")} or #{tag.i("N")}. If you enter nothing, Mavis will assume " \
+            "#{tag.i("Y")}. If you enter #{tag.i("N")}, the row will not be uploaded."
+      ) + date_and_time_of_vaccination + national_reporting_vaccine_and_batch +
       national_reporting_anatomical_site + national_reporting_dose_sequence +
       national_reporting_performing_professional_names + local_patient_id
   end
@@ -157,7 +133,7 @@ def child_columns
       },
       {
         name: "CHILD_NHS_NUMBER",
-        notes: "Optional, must be 10 digits and numeric."
+        notes: "You must enter a valid NHS number if available."
       },
       {
         name: "CHILD_GENDER",
@@ -181,12 +157,17 @@ def organisation_code(optionality:)
     ]
   end
 
-  def nhs_number(optionality:)
+  def nhs_number
     [
       {
         name: "NHS_NUMBER",
         notes:
-          "#{tag.strong(optionality)}, must be a valid #{link_to("NHS number", "https://www.datadictionary.nhs.uk/attributes/nhs_number.html")}."
+          "You must enter a valid #{
+            link_to(
+              "NHS number",
+              "https://www.datadictionary.nhs.uk/attributes/nhs_number.html"
+            )
+          } if available."
       }
     ]
   end
@@ -212,60 +193,56 @@ def school_name
     ]
   end
 
-  def patient_demographics(
-    optionality:,
-    gender_field_name: "PERSON_GENDER_CODE"
-  )
+  def patient_demographics(gender_field_name: "PERSON_GENDER_CODE")
     [
-      { name: "PERSON_FORENAME", notes: tag.strong(optionality) },
-      { name: "PERSON_SURNAME", notes: tag.strong(optionality) },
+      {
+        name: "PERSON_FORENAME",
+        notes:
+          "#{tag.strong("Required")}, must use alphabetical characters " \
+            "(you can include accents like Chloë, hyphens like Anne-Marie or apostrophes like D'Arcy " \
+            "but no other special characters)."
+      },
+      {
+        name: "PERSON_SURNAME",
+        notes:
+          "#{tag.strong("Required")}, must use alphabetical characters " \
+            "(you can include accents like Jiménez, hyphens like Burne-Jones or apostrophes like O'Hare " \
+            "but no other special characters)."
+      },
       {
         name: "PERSON_DOB",
         notes:
-          "#{tag.strong(optionality)}, must use either #{tag.i("YYYYMMDD")} or " \
+          "#{tag.strong("Required")}, you must use either #{tag.i("YYYYMMDD")} or " \
             "#{tag.i("DD/MM/YYYY")} format."
       },
       {
         name: gender_field_name,
         notes:
-          "#{tag.strong(optionality)}, must be one of: #{tag.i("female")}, " \
+          "#{tag.strong("Required")}, must be one of: #{tag.i("female")}, " \
             "#{tag.i("male")}, #{tag.i("not known")} or #{tag.i("not specified")}."
       },
       {
         name: "PERSON_POSTCODE",
         notes:
-          "#{tag.strong(optionality)}, must be formatted as a valid postcode, for example #{tag.i("SW1A 1AA")}."
+          "#{tag.strong("Required")}, must be a full postcode, for example #{tag.i("SW1A 1AA")}"
       }
     ]
   end
 
-  def vaccinated(optionality:, extra_notes: "")
-    optionality_html =
-      if %w[Mandatory Required].include?(optionality)
-        tag.strong(optionality)
-      else
-        optionality
-      end
-
-    [
-      {
-        name: "VACCINATED",
-        notes:
-          "#{optionality_html}, must be #{tag.i("Y")} or #{tag.i("N")}. #{extra_notes}"
-      }
-    ]
+  def vaccinated(notes:)
+    [{ name: "VACCINATED", notes: }]
   end
 
-  def date_and_time_of_vaccination(date_optionality:)
+  def date_and_time_of_vaccination
     [
       {
         name: "DATE_OF_VACCINATION",
         notes:
-          "#{tag.strong(date_optionality)}, must use either #{tag.i("YYYYMMDD")} or #{tag.i("DD/MM/YYYY")} format."
+          "#{tag.strong("Required")}, you must use either #{tag.i("YYYYMMDD")} or #{tag.i("DD/MM/YYYY")} format."
       },
       {
         name: "TIME_OF_VACCINATION",
-        notes: "Optional, must use #{tag.i("HH:MM:SS")} format."
+        notes: "Optional, use #{tag.i("HH:MM:SS")} format."
       }
     ]
   end
@@ -331,15 +308,11 @@ def vaccine_and_batch
         name: "VACCINE_GIVEN",
         notes: "Optional, must be one of: #{vaccines_sentence}."
       },
-      {
-        name: "BATCH_NUMBER",
-        notes: "Required if #{tag.code("BATCH_EXPIRY_DATE")} is provided."
-      },
+      { name: "BATCH_NUMBER", notes: "Optional" },
       {
         name: "BATCH_EXPIRY_DATE",
         notes:
-          "Required if #{tag.code("BATCH_NUMBER")} is provided, must use " \
-            "either #{tag.i("YYYYMMDD")} or #{tag.i("DD/MM/YYYY")} format."
+          "Optional, use either #{tag.i("YYYYMMDD")} or #{tag.i("DD/MM/YYYY")} format."
       }
     ]
   end
@@ -357,17 +330,17 @@ def national_reporting_vaccine_and_batch
       {
         name: "VACCINE_GIVEN",
         notes:
-          "#{tag.strong("Mandatory")}" \
+          "#{tag.strong("Required")}" \
             "#{tag.br}#{tag.br}" \
             "For HPV records, must be one of: #{hpv_vaccines_sentence}." \
             "#{tag.br}#{tag.br}" \
             "For flu records, must be one of: #{flu_vaccines_sentence}."
       },
-      { name: "BATCH_NUMBER", notes: tag.strong("Mandatory") },
+      { name: "BATCH_NUMBER", notes: tag.strong("Required") },
       {
         name: "BATCH_EXPIRY_DATE",
         notes:
-          "#{tag.strong("Mandatory")}, must use #{tag.i("YYYYMMDD")} format."
+          "#{tag.strong("Required")}, must use #{tag.i("YYYYMMDD")} format."
       }
     ]
   end
@@ -466,11 +439,11 @@ def national_reporting_performing_professional_names
     [
       {
         name: "PERFORMING_PROFESSIONAL_FORENAME",
-        notes: "Mandatory for flu records, optional for HPV records."
+        notes: "Required for flu records, optional for HPV records."
       },
       {
         name: "PERFORMING_PROFESSIONAL_SURNAME",
-        notes: "Mandatory for flu records, optional for HPV records."
+        notes: "Required for flu records, optional for HPV records."
       }
     ]
   end
@@ -496,7 +469,7 @@ def national_reporting_anatomical_site
     [
       {
         name: "ANATOMICAL_SITE",
-        notes: "#{tag.strong("Mandatory")}, must be one of: #{site_sentence}."
+        notes: "#{tag.strong("Required")}, must be one of: #{site_sentence}."
       }
     ]
   end
@@ -509,7 +482,7 @@ def national_reporting_dose_sequence
       {
         name: "DOSE_SEQUENCE",
         notes:
-          "Mandatory for HPV records, optional for flu records." \
+          "Required for HPV records, optional for flu records." \
             "#{tag.br} #{tag.br}" \
             "Must be a number between 1 and #{hpv_max} for HPV records and between 1 and #{flu_max} for flu records."
       }
@@ -518,8 +491,16 @@ def national_reporting_dose_sequence
 
   def local_patient_id
     [
-      { name: "LOCAL_PATIENT_ID", notes: tag.strong("Mandatory") },
-      { name: "LOCAL_PATIENT_ID_URI", notes: tag.strong("Mandatory") }
+      {
+        name: "LOCAL_PATIENT_ID",
+        notes:
+          "#{tag.strong("Required")}, supplied automatically by your vaccination recording system."
+      },
+      {
+        name: "LOCAL_PATIENT_ID_URI",
+        notes:
+          "#{tag.strong("Required")}, supplied automatically by your vaccination recording system."
+      }
     ]
   end
 end

app/views/imports/show.html.erb

@@ -25,7 +25,7 @@
     <% end %>
 
     <p class="nhsuk-u-reading-width">
-      Correct the issues listed, save the changes and upload the file again.
+      Refer to <u>What your CSV file must include</u> to correct the issues listed below, save the changes and upload the file again.
 
       <% if import.changesets_are_invalid? %>
         This may include errors identified after Mavis added a missing NHS number or replaced an incorrect NHS number.

spec/components/app_import_format_details_component_spec.rb

@@ -4,36 +4,10 @@
   let(:programme) { Programme.hpv }
   let(:team) { create(:team, programmes: [programme]) }
 
-  it "renders the correct summary text for ClassImport" do
+  it "renders the correct summary text" do
     import = ClassImport.new(team:)
     render_inline(described_class.new(import:))
-    expect(page).to have_content(
-      "How to format your Mavis CSV file for class lists"
-    )
-  end
-
-  it "renders the correct summary text for CohortImport" do
-    import = CohortImport.new(team:)
-    render_inline(described_class.new(import:))
-    expect(page).to have_content(
-      "How to format your Mavis CSV file for child records"
-    )
-  end
-
-  it "renders the correct summary text for ImmunisationImport" do
-    import = ImmunisationImport.new(team:)
-    render_inline(described_class.new(import:))
-    expect(page).to have_content(
-      "How to format your Mavis CSV file for vaccination records"
-    )
-  end
-
-  it "raises an error for unsupported import types" do
-    import = Object.new
-    expect { render_inline(described_class.new(import:)) }.to raise_error(
-      ArgumentError,
-      "Unsupported import type: Object"
-    )
+    expect(page).to have_content("What your CSV file must include")
   end
 
   it "renders the correct columns for ClassImport" do
@@ -83,14 +57,6 @@
   context "with a national reporting team" do
     let(:team) { create(:team, :national_reporting, programmes: [programme]) }
 
-    it "renders the correct summary text for ImmunisationImport" do
-      import = ImmunisationImport.new(team:)
-      render_inline(described_class.new(import:))
-      expect(page).to have_content(
-        "How to format your CSV file for vaccination records"
-      )
-    end
-
     it "renders the correct columns for ImmunisationImport" do
       import = ImmunisationImport.new(team:)
       render_inline(described_class.new(import:))

spec/features/import_child_records_spec.rb

@@ -239,9 +239,7 @@ def when_i_upload_a_file_with_invalid_fields
   end
 
   def then_i_should_the_errors_page_with_invalid_fields
-    expect(page).to have_content(
-      "How to format your Mavis CSV file for child records"
-    )
+    expect(page).to have_content("What your CSV file must include")
     expect(page).to have_content("Row 2")
   end
 

spec/features/import_class_lists_spec.rb

@@ -219,9 +219,7 @@ def when_i_upload_a_file_with_invalid_fields
   end
 
   def then_i_should_the_errors_page_with_invalid_fields
-    expect(page).to have_content(
-      "How to format your Mavis CSV file for class lists"
-    )
+    expect(page).to have_content("What your CSV file must include")
     expect(page).to have_content("Row 1")
   end
 

spec/features/import_vaccination_records_national_reporting_spec.rb

@@ -218,9 +218,7 @@ def when_i_upload_an_invalid_file
   end
 
   def then_i_should_see_the_errors_page
-    expect(page).to have_content(
-      "How to format your CSV file for vaccination records"
-    )
+    expect(page).to have_content("What your CSV file must include")
     expect(page).to have_content("Row 2")
     expect(page).to have_content("ANATOMICAL_SITE:")
     expect(page).to have_content("SCHOOL_URN:")