Merge pull request #4335 from nhsuk/vaccination-from-fhir-record

Create `VaccinationRecord` from FHIR record

Author: alistair-white-horne-tng

app/lib/fhir_mapper/vaccination_record.rb

@@ -2,6 +2,9 @@
 
 module FHIRMapper
   class VaccinationRecord
+    class UnknownVaccine < StandardError
+    end
+
     delegate_missing_to :@vaccination_record
 
     def initialize(vaccination_record)
@@ -47,6 +50,76 @@ def fhir_record
       immunisation
     end
 
+    def self.from_fhir_record(fhir_record, patient:, team:)
+      attrs = {}
+
+      # attrs[:source] = "nhs_immunisations_api"
+
+      attrs[:patient] = patient
+
+      attrs[:nhs_immunisations_api_id] = fhir_record.id
+      attrs[:nhs_immunisations_api_synced_at] = Time.current
+
+      attrs[:programme] = programme_from_fhir(fhir_record)
+
+      attrs[:performed_at] = Time.zone.parse(fhir_record.occurrenceDateTime)
+      attrs[:outcome] = outcome_from_fhir(fhir_record)
+
+      location_system = fhir_record.location.identifier.system
+      location_value = fhir_record.location.identifier.value
+      unless location_value == "X99999"
+        case location_system
+        when "https://fhir.hl7.org.uk/Id/urn-school-number"
+          attrs[:location] = Location.find_by(urn: location_value)
+        when "https://fhir.nhs.uk/Id/ods-organization-code"
+          attrs[:location] = Location.find_by(ods_code: location_value)
+        end
+      end
+
+      if attrs[:location].nil?
+        attrs[:location_name] = fhir_record.location.identifier.value
+      end
+
+      # TODO: There is also a `display` field which could be used to identify the origin of the record,
+      #       but this is not marked as required on the schema, so is likely to be unreliable
+      attrs[:performed_ods_code] = org_performer_ods_code_from_fhir(fhir_record)
+
+      user_performer_name = user_performer_name_from_fhir(fhir_record)
+      attrs[:performed_by_given_name] = user_performer_name&.given&.first
+      attrs[:performed_by_family_name] = user_performer_name&.family
+
+      attrs[:delivery_method] = delivery_method_from_fhir(fhir_record)
+      attrs[:delivery_site] = site_from_fhir(fhir_record)
+
+      attrs[:dose_sequence] = fhir_record
+        .protocolApplied
+        .first
+        .doseNumberPositiveInt
+
+      attrs[:vaccine] = Vaccine.from_fhir_record(fhir_record)
+
+      if attrs[:vaccine] && team
+        attrs[:batch] = batch_from_fhir(
+          fhir_record,
+          vaccine: attrs[:vaccine],
+          team:
+        )
+        attrs[:full_dose] = full_dose_from_fhir(
+          fhir_record,
+          vaccine: attrs[:vaccine]
+        )
+      else
+        attrs[:notes] = vaccine_batch_notes_from_fhir(fhir_record)
+        attrs[:full_dose] = true
+
+        Sentry.capture_exception(
+          UnknownVaccine.new(fhir_record.vaccineCode.coding.first.code)
+        )
+      end
+
+      ::VaccinationRecord.new(attrs)
+    end
+
     private
 
     def fhir_identifier
@@ -77,6 +150,19 @@ def fhir_status
       end
     end
 
+    private_class_method def self.outcome_from_fhir(fhir_record)
+      case fhir_record.status
+      when "completed"
+        "administered"
+      when "not-done"
+        # "refused"
+        # TODO: handle this more gracefully
+        raise "Cannot import not-done vaccination records"
+      else
+        raise "Unexpected vaccination status: #{fhir_record.status}. Expected only 'completed' or 'not-done'"
+      end
+    end
+
     def fhir_site
       site_info =
         ::VaccinationRecord::DELIVERY_SITE_SNOMED_CODES_AND_TERMS[delivery_site]
@@ -92,6 +178,18 @@ def fhir_site
       )
     end
 
+    private_class_method def self.site_from_fhir(fhir_record)
+      site_code =
+        fhir_record
+          .site
+          &.coding
+          &.find { it.system == "http://snomed.info/sct" }
+          &.code
+      ::VaccinationRecord::DELIVERY_SITE_SNOMED_CODES_AND_TERMS
+        .find { |_key, value| value.first == site_code }
+        &.first
+    end
+
     def fhir_route
       FHIR::CodeableConcept.new(
         coding: [
@@ -104,6 +202,18 @@ def fhir_route
       )
     end
 
+    private_class_method def self.delivery_method_from_fhir(fhir_record)
+      route_code =
+        fhir_record
+          .route
+          &.coding
+          &.find { it.system == "http://snomed.info/sct" }
+          &.code
+      ::VaccinationRecord::DELIVERY_METHOD_SNOMED_CODES_AND_TERMS
+        .find { |_key, value| value.first == route_code }
+        &.first
+    end
+
     def fhir_dose_quantity
       FHIR::Quantity.new(
         value: dose_volume_ml.to_f,
@@ -113,18 +223,73 @@ def fhir_dose_quantity
       )
     end
 
+    private_class_method def self.dose_volume_ml_from_fhir(fhir_record)
+      dq = fhir_record.doseQuantity
+      if dq.system == "http://unitsofmeasure.org" && dq.code == "ml"
+        dq.value.to_f
+      else
+        raise "Unknown dose quantity system: #{dq.system} and code: #{dq.code}"
+      end
+    end
+
+    private_class_method def self.full_dose_from_fhir(fhir_record, vaccine:)
+      if vaccine.programme.type == :flu && vaccine.method == :nasal
+        fhir_record.doseQuantity.value >= vaccine.dose_volume_ml
+      end
+
+      true
+    end
+
+    private_class_method def self.vaccine_batch_notes_from_fhir(fhir_record)
+      fhir_vaccine =
+        fhir_record.vaccineCode.coding.find do
+          it.system == "http://snomed.info/sct"
+        end
+
+      vaccine_snomed_code = fhir_vaccine.code
+      vaccine_description = fhir_vaccine.display.presence
+
+      batch_number = fhir_record.lotNumber
+      batch_expiry = fhir_record.expirationDate
+
+      "SNOMED product code: #{vaccine_snomed_code}\n" \
+        "#{"SNOMED description: #{vaccine_description}\n" if vaccine_description}" \
+        "Batch number: #{batch_number}\n" \
+        "Batch expiry: #{batch_expiry}"
+    end
+
     def fhir_user_performer(reference_id:)
       FHIR::Immunization::Performer.new(
         actor: FHIR::Reference.new(reference: "##{reference_id}")
       )
     end
 
+    private_class_method def self.user_performer_name_from_fhir(fhir_record)
+      performer_references =
+        fhir_record
+          .performer
+          .reject { it.actor&.type == "Organization" }
+          .map { it.actor.reference&.sub("#", "") }
+      user_actor =
+        fhir_record.contained.find do |c|
+          c.id.in?(performer_references) && c.resourceType == "Practitioner"
+        end
+      user_actor&.name&.find { it&.use == "official" } ||
+        user_actor&.name&.first
+    end
+
     def fhir_org_performer
       FHIR::Immunization::Performer.new(
         actor: Organisation.fhir_reference(ods_code: performed_ods_code)
       )
     end
 
+    private_class_method def self.org_performer_ods_code_from_fhir(fhir_record)
+      org_actor =
+        fhir_record.performer.find { it.actor&.type == "Organization" }&.actor
+      org_actor&.identifier&.value
+    end
+
     def fhir_reason_code
       FHIR::CodeableConcept.new(
         coding: [
@@ -139,5 +304,31 @@ def fhir_protocol_applied
         doseNumberPositiveInt: dose_sequence
       )
     end
+
+    private_class_method def self.programme_from_fhir(fhir_record)
+      target_diseases = fhir_record.protocolApplied.first.targetDisease
+      target_diseases_codes =
+        target_diseases.map do |disease|
+          disease
+            .coding
+            .find { |coding| coding.system == "http://snomed.info/sct" }
+            .code
+        end
+      # This may need to change when we start consuming programmes which have multiple target diseases, eg MMR
+      target_disease_code = target_diseases_codes.first
+
+      ::Programme.find_by(
+        type: ::Programme::SNOMED_TARGET_DISEASE_CODES.key(target_disease_code)
+      )
+    end
+
+    private_class_method def self.batch_from_fhir(fhir_record, vaccine:, team:)
+      ::Batch.create_with(archived_at: Time.current).find_or_create_by!(
+        expiry: fhir_record.expirationDate&.to_date,
+        name: fhir_record.lotNumber.to_s,
+        team:,
+        vaccine:
+      )
+    end
   end
 end

app/lib/fhir_mapper/vaccine.rb

@@ -25,6 +25,16 @@ def fhir_codeable_concept
       )
     end
 
+    def self.from_fhir_record(fhir_record)
+      snomed_product_code =
+        fhir_record
+          .vaccineCode
+          .coding
+          .find { it.system == "http://snomed.info/sct" }
+          .code
+      ::Vaccine.find_by(snomed_product_code:)
+    end
+
     def fhir_manufacturer_reference
       FHIR::Reference.new(display: manufacturer)
     end

app/models/vaccination_record.rb

@@ -173,6 +173,10 @@ class VaccinationRecord < ApplicationRecord
 
   delegate :fhir_record, to: :fhir_mapper
 
+  class << self
+    delegate :from_fhir_record, to: FHIRMapper::VaccinationRecord
+  end
+
   def academic_year = performed_at.to_date.academic_year
 
   def not_administered?

config/feature_flags.yml

@@ -12,6 +12,9 @@ enqueue_sync_vaccination_records_to_nhs: Send new vaccinations recorded by
 immunisations_fhir_api_integration: Master switch to control communications
   with NHS Immunisations FHIR API.
 
+immunisations_fhir_api_integration_search: Master switch to control whether
+  search requests can be made to the NHS Immunisations FHIR API.
+
 import_choose_academic_year: Add an option to choose the academic year when
   importing patients during the preparation period.