Improve content on vaccination record upload page

This renames, and changes the content in the dropdown
which displays which columns are required or optional.

Also change the content on the "Failed upload" page.

This content change is based on feedback received from users during the
national reporting pilot.

Jira-Issue: MAV-5893

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:")