Merge pull request #3841 from nhsuk/fhir-create-job

Add job to sync vaccination records upstream to NHS

Author: misaka

app/jobs/sync_vaccination_record_to_nhs_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class SyncVaccinationRecordToNHSJob < ApplicationJob
+  queue_as :immunisation_api
+
+  def perform(vaccination_record)
+    if vaccination_record.nhs_immunisations_api_synced_at.present?
+      Rails.logger.info(
+        "Vaccination record already synced: #{vaccination_record.id}"
+      )
+      return
+    end
+
+    NHS::ImmunisationsAPI.record_immunisation(vaccination_record)
+  end
+end

app/lib/mavis_cli.rb

@@ -24,3 +24,4 @@ def self.progress_bar(total)
 require_relative "mavis_cli/gias/check_import"
 require_relative "mavis_cli/gias/download"
 require_relative "mavis_cli/gias/import"
+require_relative "mavis_cli/vaccination_records/sync"

app/lib/mavis_cli/vaccination_records/sync.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MavisCLI
+  module VaccinationRecords
+    class Sync < Dry::CLI::Command
+      desc "Sync a vaccination record to NHS Immunisations API"
+      argument :vaccination_record_id,
+               required: true,
+               desc: "ID of vaccination record to sync"
+
+      def call(vaccination_record_id:, **)
+        MavisCLI.load_rails
+
+        vaccination_record =
+          ::VaccinationRecord.find_by(id: vaccination_record_id)
+
+        if vaccination_record.nil?
+          puts "Vaccination record with ID #{vaccination_record_id} not found"
+          return
+        end
+
+        if vaccination_record.nhs_immunisations_api_synced_at.present?
+          puts "Vaccination record #{vaccination_record_id} has already been" \
+                 " synced at #{vaccination_record.nhs_immunisations_api_synced_at}"
+          return
+        end
+
+        SyncVaccinationRecordToNHSJob.perform_now(vaccination_record)
+        puts "Successfully synced vaccination record #{vaccination_record_id}"
+      end
+    end
+  end
+
+  register "vaccination-records" do |prefix|
+    prefix.register "sync", VaccinationRecords::Sync
+  end
+end

app/lib/nhs/immunisations_api.rb

@@ -1,43 +1,67 @@
 # frozen_string_literal: true
 
 module NHS::ImmunisationsAPI
-  class PatientNotFound < StandardError
-  end
-
   class << self
     def record_immunisation(vaccination_record)
-      NHS::API.connection.post(
-        "/immunisation-fhir-api/FHIR/R4/Immunization",
-        vaccination_record.fhir_record.to_json,
-        "Content-Type" => "application/fhir+json"
-      )
-    rescue Faraday::Error => e
-      info = extract_error_info(e.response[:body])
-      Rails.logger.error(
-        "Error recording vaccination record (#{vaccination_record.id}):" \
-          " [#{info[:code]}] #{info[:diagnostics]}"
-      )
-      raise e
+      unless Flipper.enabled?(:immunisations_fhir_api_integration)
+        Rails.logger.info(
+          "Not syncing vaccination record to immunisations API as the feature" \
+            " flag is disabled: #{vaccination_record.id}"
+        )
+        return
+      end
+
+      response =
+        NHS::API.connection.post(
+          "/immunisation-fhir-api/FHIR/R4/Immunization",
+          vaccination_record.fhir_record.to_json,
+          "Content-Type" => "application/fhir+json"
+        )
+
+      if response.status == 201
+        vaccination_record.update!(
+          nhs_immunisations_api_id:
+            extract_nhs_id(response.headers.fetch("location")),
+          nhs_immunisations_api_synced_at: Time.current,
+          # We would normally retrieve this from the API response, but the NHS
+          # Immunisations API does not return this to us, yet.
+          nhs_immunisations_api_etag: 1
+        )
+      else
+        raise "Error syncing vaccination record #{vaccination_record.id} to" \
+                " Immunisations API: unexpected response status" \
+                " #{response.status}"
+      end
+    rescue Faraday::ClientError => e
+      if (diagnostics = extract_error_diagnostics(e&.response)).present?
+        raise "Error syncing vaccination record #{vaccination_record.id} to" \
+                " Immunisations API: #{diagnostics}"
+      else
+        raise
+      end
     end
 
-    def extract_error_info(response_body)
-      return { code: nil, diagnostics: "No response body" } unless response_body
+    private
 
-      response = JSON.parse(response_body, symbolize_names: true)
+    def extract_error_diagnostics(response)
+      return nil if response.nil? || response[:body].blank?
 
-      if response.empty?
-        { code: nil, diagnostics: "No response body" }
-      elsif response[:issue].blank?
-        { code: nil, diagnostics: "No issues in response" }
-      elsif response[:issue].first[:severity] != "error"
-        { code: nil, diagnostics: "Issue is not an error" }
-      else
-        diagnostics = response[:issue].first[:diagnostics]
-        if diagnostics.match?(/NHS Number: \d{10} is invalid.*/)
-          diagnostics.replace("NHS Number is invalid or it doesn't exist")
-        end
+      begin
+        JSON.parse(response[:body], symbolize_names: true).dig(
+          :issue,
+          0,
+          :diagnostics
+        )
+      rescue JSON::ParserError
+        nil
+      end
+    end
 
-        { code: response[:issue].first[:code], diagnostics: diagnostics }
+    def extract_nhs_id(location)
+      if (match = location.match(%r{Immunization/([a-f0-9-]+)}))
+        match[1]
+      else
+        raise UnrecognisedLocation, location
       end
     end
   end

app/models/vaccination_record.rb

@@ -4,41 +4,45 @@
 #
 # Table name: vaccination_records
 #
-#  id                       :bigint           not null, primary key
-#  confirmation_sent_at     :datetime
-#  delivery_method          :integer
-#  delivery_site            :integer
-#  discarded_at             :datetime
-#  dose_sequence            :integer
-#  full_dose                :boolean
-#  location_name            :string
-#  notes                    :text
-#  outcome                  :integer          not null
-#  pending_changes          :jsonb            not null
-#  performed_at             :datetime         not null
-#  performed_by_family_name :string
-#  performed_by_given_name  :string
-#  performed_ods_code       :string
-#  uuid                     :uuid             not null
-#  created_at               :datetime         not null
-#  updated_at               :datetime         not null
-#  batch_id                 :bigint
-#  patient_id               :bigint
-#  performed_by_user_id     :bigint
-#  programme_id             :bigint           not null
-#  session_id               :bigint
-#  vaccine_id               :bigint
+#  id                              :bigint           not null, primary key
+#  confirmation_sent_at            :datetime
+#  delivery_method                 :integer
+#  delivery_site                   :integer
+#  discarded_at                    :datetime
+#  dose_sequence                   :integer
+#  full_dose                       :boolean
+#  location_name                   :string
+#  nhs_immunisations_api_etag      :string
+#  nhs_immunisations_api_synced_at :datetime
+#  notes                           :text
+#  outcome                         :integer          not null
+#  pending_changes                 :jsonb            not null
+#  performed_at                    :datetime         not null
+#  performed_by_family_name        :string
+#  performed_by_given_name         :string
+#  performed_ods_code              :string
+#  uuid                            :uuid             not null
+#  created_at                      :datetime         not null
+#  updated_at                      :datetime         not null
+#  batch_id                        :bigint
+#  nhs_immunisations_api_id        :string
+#  patient_id                      :bigint
+#  performed_by_user_id            :bigint
+#  programme_id                    :bigint           not null
+#  session_id                      :bigint
+#  vaccine_id                      :bigint
 #
 # Indexes
 #
-#  index_vaccination_records_on_batch_id              (batch_id)
-#  index_vaccination_records_on_discarded_at          (discarded_at)
-#  index_vaccination_records_on_patient_id            (patient_id)
-#  index_vaccination_records_on_performed_by_user_id  (performed_by_user_id)
-#  index_vaccination_records_on_programme_id          (programme_id)
-#  index_vaccination_records_on_session_id            (session_id)
-#  index_vaccination_records_on_uuid                  (uuid) UNIQUE
-#  index_vaccination_records_on_vaccine_id            (vaccine_id)
+#  index_vaccination_records_on_batch_id                  (batch_id)
+#  index_vaccination_records_on_discarded_at              (discarded_at)
+#  index_vaccination_records_on_nhs_immunisations_api_id  (nhs_immunisations_api_id) UNIQUE
+#  index_vaccination_records_on_patient_id                (patient_id)
+#  index_vaccination_records_on_performed_by_user_id      (performed_by_user_id)
+#  index_vaccination_records_on_programme_id              (programme_id)
+#  index_vaccination_records_on_session_id                (session_id)
+#  index_vaccination_records_on_uuid                      (uuid) UNIQUE
+#  index_vaccination_records_on_vaccine_id                (vaccine_id)
 #
 # Foreign Keys
 #

config/feature_flags.yml

@@ -8,3 +8,6 @@ dev_tools: Developer tools useful for testing and debugging.
 mesh_jobs: Export vaccination records to MESH automatically.
 
 offline_working: Prototype support for using Mavis offline.
+
+immunisations_fhir_api_integration: Master switch to control communications with
+  NHS Immunistaions FHIR API.

db/migrate/20250625212637_add_nhs_immunisations_api_synced_at_to_vaccination_record.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class AddNHSImmunisationsAPISyncedAtToVaccinationRecord < ActiveRecord::Migration[
+  8.0
+]
+  def change
+    add_column :vaccination_records,
+               :nhs_immunisations_api_synced_at,
+               :datetime,
+               null: true
+  end
+end

db/migrate/20250630140421_add_nhs_immunisations_api_etag_to_vaccination_record.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class AddNHSImmunisationsAPIEtagToVaccinationRecord < ActiveRecord::Migration[
+  8.0
+]
+  def change
+    add_column :vaccination_records,
+               :nhs_immunisations_api_etag,
+               :string,
+               null: true
+  end
+end

db/migrate/20250630144421_add_nhs_immunisations_api_id_to_vaccination_record.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddNHSImmunisationsAPIIdToVaccinationRecord < ActiveRecord::Migration[8.0]
+  def change
+    add_column :vaccination_records,
+               :nhs_immunisations_api_id,
+               :string,
+               null: true
+    add_index :vaccination_records, :nhs_immunisations_api_id, unique: 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.0].define(version: 2025_07_02_142922) do
+ActiveRecord::Schema[8.0].define(version: 2025_07_02_162254) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pg_catalog.plpgsql"
   enable_extension "pg_trgm"
@@ -820,8 +820,12 @@
     t.string "performed_ods_code"
     t.bigint "vaccine_id"
     t.boolean "full_dose"
+    t.datetime "nhs_immunisations_api_synced_at"
+    t.string "nhs_immunisations_api_id"
+    t.string "nhs_immunisations_api_etag"
     t.index ["batch_id"], name: "index_vaccination_records_on_batch_id"
     t.index ["discarded_at"], name: "index_vaccination_records_on_discarded_at"
+    t.index ["nhs_immunisations_api_id"], name: "index_vaccination_records_on_nhs_immunisations_api_id", unique: true
     t.index ["patient_id"], name: "index_vaccination_records_on_patient_id"
     t.index ["performed_by_user_id"], name: "index_vaccination_records_on_performed_by_user_id"
     t.index ["programme_id"], name: "index_vaccination_records_on_programme_id"