Parse the doseNumberString field from the Imms API

The logic for extracting `dose_sequence` is now as follows:
1. Use `doseNumberPositiveInt`
2. Naively cast `doseNumberString` to an `int`
3. Save the value to the `notes` field, so we can analyse them easily
   in the future, to decide how to best parse them

Jira-Issue: MAV-5716

Author: alistair-white-horne-tng

app/lib/fhir_mapper/vaccination_record.rb

@@ -107,11 +107,15 @@ def self.from_fhir_record(fhir_record, patient:)
       attrs[:delivery_site] = site_from_fhir(fhir_record)
 
       dose_sequence = dose_sequence_from_fhir(fhir_record)
-      max_dose_sequence = attrs[:programme].maximum_dose_sequence
-      if dose_sequence.present? && dose_sequence > max_dose_sequence
-        notes << "Reported dose sequence: #{dose_sequence}"
+      if dose_sequence
+        if dose_sequence > attrs[:programme].maximum_dose_sequence ||
+             dose_sequence < 1
+          notes << "Reported dose number: #{dose_sequence}"
+        else
+          attrs[:dose_sequence] = dose_sequence
+        end
       else
-        attrs[:dose_sequence] = dose_sequence
+        notes << dose_number_string_note_from_fhir(fhir_record)
       end
 
       attrs[:vaccine] = Vaccine.from_fhir_record(fhir_record)
@@ -331,10 +335,21 @@ def fhir_protocol_applied
     end
 
     private_class_method def self.dose_sequence_from_fhir(fhir_record)
-      # TODO: currently we only look at `doseNumberPositiveInt` but often `doseNumberString` is populated instead
-      #       This doesn't matter much for flu, but this may need to be revisited when we start consuming programmes
-      #       where dose number matters more (eg MMR)
-      fhir_record.protocolApplied.sole.doseNumberPositiveInt
+      protocol = fhir_record.protocolApplied&.sole
+
+      if protocol&.doseNumberPositiveInt.present?
+        return protocol&.doseNumberPositiveInt
+      end
+
+      Integer(protocol&.doseNumberString, exception: false)
+    end
+
+    private_class_method def self.dose_number_string_note_from_fhir(fhir_record)
+      dose_string = fhir_record.protocolApplied&.sole&.doseNumberString
+
+      return if dose_string.blank?
+
+      "Reported dose number string: #{dose_string}"
     end
   end
 end

spec/lib/fhir_mapper/vaccination_record_spec.rb

@@ -504,44 +504,97 @@
         end
       end
 
-      describe "the parsed dose_sequence value" do
+      describe "dose sequence parsing" do
         subject { record.dose_sequence }
 
         let(:fixture_file_name) { "fhir/flu/fhir_record_full.json" }
+        let(:dose_number_positive_int) { nil }
+        let(:dose_number_string) { nil }
 
         before do
-          allow(fhir_immunization.protocolApplied.sole).to receive(
-            :doseNumberPositiveInt
-          ).and_return(dose_number)
+          allow(fhir_immunization.protocolApplied.sole).to receive_messages(
+            doseNumberPositiveInt: dose_number_positive_int,
+            doseNumberString: dose_number_string
+          )
         end
 
-        context "when doseNumberPositiveInt is nil" do
-          let(:dose_number) { nil }
-
+        context "when both fields are nil" do
           it { should be_nil }
 
-          it "does not include a dose sequence note" do
-            expect(record.notes.to_s).not_to include("Reported dose sequence")
+          it "does not include any dose notes" do
+            expect(record.notes.to_s).not_to include("Reported dose number")
+            expect(record.notes.to_s).not_to include(
+              "Reported dose number string"
+            )
           end
         end
 
-        context "when doseNumberPositiveInt is less than the maximum dose sequence for flu" do
-          let(:dose_number) { 1 }
+        context "when doseNumberPositiveInt is within the maximum dose sequence for flu" do
+          let(:dose_number_positive_int) { 1 }
 
           it { should eq 1 }
 
           it "does not include a dose sequence note" do
-            expect(record.notes.to_s).not_to include("Reported dose sequence")
+            expect(record.notes.to_s).not_to include("Reported dose number")
           end
         end
 
         context "when doseNumberPositiveInt exceeds the maximum dose sequence for flu" do
-          let(:dose_number) { 3 }
+          let(:dose_number_positive_int) { 3 }
 
           it { should be_nil }
 
           it "records the out-of-range dose sequence in notes" do
-            expect(record.notes.to_s).to include("Reported dose sequence: 3")
+            expect(record.notes.to_s).to include("Reported dose number: 3")
+          end
+        end
+
+        context "when doseNumberPositiveInt is present and doseNumberString is also present" do
+          let(:dose_number_positive_int) { 2 }
+          let(:dose_number_string) { "first" }
+
+          it { should eq 2 }
+
+          it "does not include a dose number string note" do
+            expect(record.notes.to_s).not_to include(
+              "Reported dose number string"
+            )
+          end
+        end
+
+        context "when doseNumberString is an integer string" do
+          let(:dose_number_string) { "1" }
+
+          it { should eq 1 }
+
+          it "does not include a dose number string note" do
+            expect(record.notes.to_s).not_to include(
+              "Reported dose number string"
+            )
+          end
+        end
+
+        context "when doseNumberString is a non-integer string" do
+          let(:dose_number_string) { "first" }
+
+          it { should be_nil }
+
+          it "appends the value to notes" do
+            expect(record.notes.to_s).to include(
+              "Reported dose number string: first"
+            )
+          end
+        end
+
+        context "when doseNumberString is blank" do
+          let(:dose_number_string) { "" }
+
+          it { should be_nil }
+
+          it "does not include a dose number string note" do
+            expect(record.notes.to_s).not_to include(
+              "Reported dose number string"
+            )
           end
         end
       end
@@ -783,7 +836,11 @@
         its(:performed_ods_code) { should eq "B12345" }
         its(:nhs_immunisations_api_primary_source) { should be false }
 
-        its(:notes) { should be_nil }
+        its(:notes) do
+          should include(
+                   "Reported dose number string: Dose sequence not recorded"
+                 )
+        end
       end
 
       context "with a record that is nasal flu, and is missing dose quantity (from real GP)" do
@@ -980,7 +1037,11 @@
         its(:outcome) { should eq "administered" }
         its(:performed_ods_code) { should eq "B12345" }
 
-        its(:notes) { should be_nil }
+        its(:notes) do
+          should include(
+                   "Reported dose number string: Dose sequence not recorded"
+                 )
+        end
       end
     end
 
@@ -1070,7 +1131,7 @@
         its(:performed_ods_code) { should eq "R1L" }
         its(:nhs_immunisations_api_primary_source) { should be true }
 
-        its(:notes) { should be_nil }
+        its(:notes) { should include("Reported dose number string: Unknown") }
       end
     end
 
@@ -1115,7 +1176,7 @@
         its(:performed_ods_code) { should eq "R1L" }
         its(:nhs_immunisations_api_primary_source) { should be true }
 
-        its(:notes) { should be_nil }
+        its(:notes) { should include("Reported dose number string: Unknown") }
       end
     end
 
@@ -1164,7 +1225,7 @@
         its(:performed_ods_code) { should eq "R1L" }
         its(:nhs_immunisations_api_primary_source) { should be true }
 
-        its(:notes) { should be_nil }
+        its(:notes) { should include("Reported dose number string: Unknown") }
       end
     end
 
@@ -1213,7 +1274,7 @@
         its(:performed_ods_code) { should eq "R1L" }
         its(:nhs_immunisations_api_primary_source) { should be true }
 
-        its(:notes) { should be_nil }
+        its(:notes) { should include("Reported dose number string: Unknown") }
       end
     end
   end