his_emr_api_lab 0.0.2

data/app/services/lab/lims/order_serializer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Lab
+  module Lims
+    ##
+    # Serializes a LabOrder into a LIMS OrderDTO.
+    module OrderSerializer
+      class << self
+        include Utils
+
+        def serialize_order(order)
+          serialized_order = structify(Lab::LabOrderSerializer.serialize_order(order))
+
+          OrderDTO.new(
+            tracking_number: serialized_order.accession_number,
+            sending_facility: current_facility_name,
+            receiving_facility: serialized_order.target_lab,
+            tests: serialized_order.tests.collect(&:name),
+            patient: format_patient(serialized_order.patient_id),
+            order_location: format_order_location(serialized_order.encounter_id),
+            sample_type: format_sample_type(serialized_order.specimen.name),
+            sample_status: format_sample_status(serialized_order.specimen.name),
+            districy: current_district, # yes districy [sic]...
+            priority: serialized_order.reason_for_test.name,
+            date_created: serialized_order.order_date,
+            test_results: format_test_results(serialized_order),
+            type: 'Order'
+          )
+        end
+
+        private
+
+        def format_order_location(encounter_id)
+          location_id = Encounter.select(:location_id).where(encounter_id: encounter_id)
+          location = Location.select(:name)
+                             .where(location_id: location_id)
+                             .first
+
+          location&.name
+        end
+
+        # Format patient into a structure that LIMS expects
+        def format_patient(patient_id)
+          person = Person.find(patient_id)
+          name = PersonName.find_by_person_id(patient_id)
+          national_id = PatientIdentifier.joins(:type)
+                                         .merge(PatientIdentifierType.where(name: 'National ID'))
+                                         .where(patient_id: patient_id)
+                                         .first
+          phone_number = PersonAttribute.joins(:type)
+                                        .merge(PersonAttributeType.where(name: 'Cell phone Number'))
+                                        .where(person_id: patient_id)
+                                        .first
+
+          {
+            first_name: name&.given_name,
+            last_name: name&.family_name,
+            id: national_id&.identifier,
+            phone_number: phone_number.value,
+            gender: person.gender,
+            email: nil
+          }
+        end
+
+        def format_sample_type(name)
+          name.casecmp?('Unknown') ? 'not_specified' : name
+        end
+
+        def format_sample_status(name)
+          name.casecmp?('Unknown') ? 'specimen_not_collected' : 'specimen_collected'
+        end
+
+        def format_test_results(order)
+          order.tests.each_with_object({}) do |test, results|
+            results[test.name] = {
+              results: test.result.each_with_object({}) do |measure, measures|
+                measures[measure.indicator.name] = { result_value: "#{measure.value_modifier}#{measure.value}" }
+              end,
+              result_date: test.result.first&.date,
+              result_entered_by: {}
+            }
+          end
+        end
+
+        def current_health_center
+          health_center = Location.current_health_center
+          raise 'Current health center not set' unless health_center
+
+          health_center
+        end
+
+        def current_district
+          district = current_health_center.city_village\
+                       || current_health_center.parent&.name\
+                       || GlobalProperty.find_by_property('current_health_center_district')&.property_value
+
+          return district if district
+
+          GlobalProperty.create(property: 'current_health_center_district',
+                                property_value: Config.application['district'],
+                                uuid: SecureRandom.uuid)
+
+          Config.application['district']
+        end
+
+        def current_facility_name
+          current_health_center.name
+        end
+      end
+    end
+  end
+end

data/app/services/lab/lims/utils.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Lab
+  module Lims
+    ##
+    # Various helper methods for modules in the Lims namespaces...
+    module Utils
+      def logger
+        Rails.logger
+      end
+
+      def structify(object)
+        if object.is_a?(Hash)
+          object.each_with_object(OpenStruct.new) do |kv_pair, struct|
+            key, value = kv_pair
+
+            struct[key] = structify(value)
+          end
+        elsif object.respond_to?(:map)
+          object.map { |item| structify(item) }
+        else
+          object
+        end
+      end
+    end
+  end
+end

data/app/services/lab/lims/worker.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative './utils'
+
+module Lab
+  module Lims
+    ##
+    # Pull/Push orders from/to the LIMS queue (Oops meant CouchDB).
+    class Worker
+      def initialize(lims_api)
+        @lims_api = lims_api
+      end
+
+      include Utils
+
+      attr_reader :lims_api
+
+      def push_orders(batch_size: 100)
+        loop do
+          logger.info('Fetching new orders...')
+          orders = LabOrder.where.not(order_id: LimsOrderMapping.all.select(:order_id))
+                           .limit(batch_size)
+
+          if orders.empty?
+            logger.info('No new orders available; exiting...')
+            break
+          end
+
+          orders.each { |order| push_order(order) }
+        end
+      end
+
+      def push_order_by_id(order_id)
+        order = LabOrder.find(order_id)
+        push_order(order)
+      end
+
+      ##
+      # Pushes given order to LIMS queue
+      def push_order(order)
+        logger.info("Pushing order ##{order.order_id}")
+
+        order_dto = OrderDTO.from_order(order)
+        mapping = LimsOrderMapping.find_by(order_id: order.order_id)
+
+        if mapping
+          lims_api.update_order(mapping.lims_id, order_dto)
+          mapping.update(pushed_at: Time.now)
+        else
+          order_dto = lims_api.create_order(order_dto)
+          LimsOrderMapping.create!(order: order, lims_id: order_dto['_id'], pushed_at: Time.now)
+        end
+
+        order_dto
+      end
+
+      ##
+      # Pulls orders from the LIMS queue and writes them to the local database
+      def pull_orders
+        lims_api.consume_orders(from: last_seq) do |order_dto, context|
+          logger.debug(`Retrieved order ##{order[:tracking_number]}`)
+
+          patient = find_patient_by_nhid(order_dto[:patient][:id])
+
+          unless patient
+            logger.debug(`Discarding order: Non local patient ##{order_dto[:patient][:id]} on order ##{order[:tracking_number]}`)
+            break
+          end
+
+          save_order(patient, order_dto)
+          update_last_seq(context.last_seq)
+        end
+      end
+
+      private
+
+      def find_patient_by_nhid(nhid)
+        national_id_type = PatientIdentifierType.where(name: 'National id')
+        identifier = PatientIdentifier.where(type: national_id_type, identifier: nhid)
+        patients = Patient.joins(:identifiers).merge(identifier).group(:patient_id).all
+
+        raise "Duplicate National Health ID: #{nhid}" if patients.size > 1
+
+        patients.first
+      end
+
+      def save_order(patient, order_dto)
+        mapping = LimsOrderMapping.find_by(couch_id: order_dto[:_id])
+
+        if mapping
+          update_order(patient, mapping.order_id, order_dto)
+          mapping.update(pulled_at: Time.now)
+        else
+          order = create_order(patient, order_dto)
+          LimsOrderMapping.create!(lims_id: order_dto[:_id], order: order, pulled_at: Time.now)
+        end
+
+        order
+      end
+
+      def create_order(patient, order_dto)
+        order = OrdersService.order_test(patient, order_dto.to_order_service_params)
+        update_results(order, order_dto.test_results)
+
+        order
+      end
+
+      def update_order(_patient, order_id, order_dto)
+        order = OrdersService.update_order(order_id, order_dto.to_order_service_params)
+        update_results(order, order_dto.test_results)
+
+        order
+      end
+
+      def update_results(_order, _lims_results)
+        # TODO: Implement me
+        raise 'Not implemented error'
+      end
+    end
+  end
+end

data/app/services/lab/metadata.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lab
+  module Metadata
+    # Concepts
+    REASON_FOR_TEST_CONCEPT_NAME = 'Reason for test'
+    REQUESTING_CLINICIAN_CONCEPT_NAME = 'Person making request'
+    SPECIMEN_TYPE_CONCEPT_NAME = 'Specimen type'
+    TARGET_LAB_CONCEPT_NAME = 'Lab'
+    TEST_RESULT_CONCEPT_NAME = 'Lab test result'
+    TEST_RESULT_INDICATOR_CONCEPT_NAME = 'Lab test result indicator'
+    TEST_TYPE_CONCEPT_NAME = 'Test type'
+
+    # Encounter
+    ENCOUNTER_TYPE_NAME = 'Lab'
+
+    # Order types
+    ORDER_TYPE_NAME = 'Lab'
+
+    # Programs
+    LAB_PROGRAM_NAME = 'Lab Program'
+  end
+end

data/app/services/lab/orders_search_service.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Lab
+  # Search Lab orders.
+  module OrdersSearchService
+    class << self
+      def find_orders(filters)
+        date = filters.delete(:date)
+        status = filters.delete(:status)
+
+        orders = Lab::LabOrder.prefetch_relationships
+                              .where(filters)
+                              .order(start_date: :desc)
+
+        orders = filter_orders_by_date(orders, date) if date
+        orders = filter_orders_by_status(orders, status) if status
+
+        orders.map { |order| Lab::LabOrderSerializer.serialize_order(order) }
+      end
+
+      def filter_orders_by_date(orders, date)
+        orders.where('start_date < DATE(?)', date.to_date + 1.day)
+      end
+
+      def filter_orders_by_status(orders, status)
+        case status.downcase
+        when 'ordered' then orders.where(concept_id: unknown_concept_id)
+        when 'drawn' then orders.where.not(concept_id: unknown_concept_id)
+        end
+      end
+
+      def unknown_concept_id
+        ConceptName.find_by_name!('Unknown').concept_id
+      end
+
+      def filter_orders_by_status(orders, status)
+        case status.downcase
+        when 'ordered' then orders.where(concept_id: unknown_concept_id)
+        when 'drawn' then orders.where.not(concept_id: unknown_concept_id)
+        end
+      end
+
+      def unknown_concept_id
+        ConceptName.find_by_name!('Unknown').concept_id
+      end
+    end
+  end
+end

data/app/services/lab/orders_service.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Lab
+  ##
+  # Manage lab orders.
+  #
+  # Lab orders are just ordinary openmrs orders with extra metadata that
+  # separates them from other orders. Lab orders have an order type of 'Lab'
+  # with the order's test type as the order's concept. The order's start
+  # date is the day the order is made. Additional information pertaining to
+  # the order is stored as observations that point to the order. The
+  # specimen types, requesting clinician, target lab, and reason for test
+  # are saved as observations to the order. Refer to method #order_test for
+  # more information.
+  module OrdersService
+    class << self
+      ##
+      # Create a lab order.
+      #
+      # Parameters schema:
+      #
+      #     {
+      #       encounter_id: {
+      #         type: :integer,
+      #         required: :false,
+      #         description: 'Attach order to this if program_id and patient_id are not provided'
+      #       },
+      #       program_id: { type: :integer, required: false },
+      #       patient_id: { type: :integer, required: false }
+      #       specimen_type_id: { type: :object, properties: { concept_id: :integer }, required: %i[concept_id] },
+      #       test_type_ids: {
+      #         type: :array,
+      #         items: {
+      #           type: :object,
+      #           properties: { concept_id: :integer },
+      #           required: %i[concept_id]
+      #         }
+      #       },
+      #       start_date: { type: :datetime }
+      #       accession_number: { type: :string }
+      #       target_lab: { type: :string },
+      #       reason_for_test_id: { type: :integer },
+      #       requesting_clinician: { type: :string }
+      #     }
+      #
+      # encounter_id: is an ID of the encounter the lab order is to be created under
+      # test_type_id: is a concept_id of the name of test being ordered
+      # specimen_type_id: is a list of IDs for the specimens to be tested (can be ommited)
+      # target_lab: is the name of the lab where test will be carried out
+      # reason_for_test_id: is a concept_id for a (standard) reason of why the test is being carried out
+      # requesting_clinician: Name of the clinician requesting the test (defaults to current user)
+      def order_test(order_params)
+        Order.transaction do
+          encounter = find_encounter(order_params)
+          order = create_order(encounter, order_params)
+
+          Lab::TestsService.create_tests(order, order_params[:date], order_params[:tests])
+
+          Lab::LabOrderSerializer.serialize_order(
+            order, requesting_clinician: add_requesting_clinician(order, order_params),
+                   reason_for_test: add_reason_for_test(order, order_params),
+                   target_lab: add_target_lab(order, order_params)
+          )
+        end
+      end
+
+      def update_order(order_id, params)
+        specimen_id = params.dig(:specimen, :concept_id)
+        unless specimen_id
+          raise ::InvalidParameterError, 'Specimen concept_id is required'
+        end
+
+        order = Lab::LabOrder.find(order_id)
+        unless order.concept_id == unknown_concept_id
+          raise ::UnprocessableEntityError
+        end
+
+        order.update!(concept_id: specimen_id)
+        Lab::LabOrderSerializer.serialize_order(order)
+      end
+
+      def void_order(order_id, reason)
+        order = Lab::LabOrder.includes(%i[requesting_clinician reason_for_test target_lab], tests: [:result])
+                             .find(order_id)
+
+        order.requesting_clinician&.void(reason)
+        order.reason_for_test&.void(reason)
+        order.target_lab&.void(reason)
+
+        order.tests.each do |test|
+          test.result&.void(reason)
+          test.void(reason)
+        end
+
+        order.void(reason)
+      end
+
+      private
+
+      ##
+      # Extract an encounter from the given parameters.
+      #
+      # Uses an encounter_id to retrieve an encounter if provided else
+      # a 'Lab' encounter is created using the provided program_id and
+      # patient_id.
+      def find_encounter(order_params)
+        if order_params[:encounter_id]
+          return Encounter.find(order_params[:encounter_id])
+        end
+
+        unless order_params[:patient_id]
+          raise InvalidParameterError, 'encounter_id or patient_id required'
+        end
+
+        program_id = order_params[:program_id] || Program.find_by_name!(Lab::Metadata::LAB_PROGRAM_NAME).program_id
+
+        Encounter.create!(
+          patient_id: order_params[:patient_id],
+          program_id: program_id,
+          type: EncounterType.find_by_name!(Lab::Metadata::ENCOUNTER_TYPE_NAME),
+          encounter_datetime: order_params[:date] || Date.today,
+          provider_id: order_params[:provider_id] || User.current&.user_id
+        )
+      end
+
+      def create_order(encounter, params)
+        Lab::LabOrder.create!(
+          order_type: OrderType.find_by_name!(Lab::Metadata::ORDER_TYPE_NAME),
+          concept_id: params.dig(:specimen, :concept_id) || unknown_concept_id,
+          encounter_id: encounter.encounter_id,
+          patient_id: encounter.patient_id,
+          start_date: params[:date]&.to_date || Date.today,
+          auto_expire_date: params[:end_date],
+          accession_number: params[:accession_number] || next_accession_number,
+          orderer: User.current&.user_id
+        )
+      end
+
+      ##
+      # Attach the requesting clinician to an order
+      def add_requesting_clinician(order, params)
+        create_order_observation(
+          order,
+          Lab::Metadata::REQUESTING_CLINICIAN_CONCEPT_NAME,
+          params[:date],
+          value_text: params['requesting_clinician']
+        )
+      end
+
+      ##
+      # Attach a reason for the order/test
+      #
+      # Examples of reasons include: Routine, Targeted, Confirmatory, Repeat, or Stat.
+      def add_reason_for_test(order, params)
+        create_order_observation(
+          order,
+          Lab::Metadata::REASON_FOR_TEST_CONCEPT_NAME,
+          params[:date],
+          value_coded: params['reason_for_test_id']
+        )
+      end
+
+      ##
+      # Attach the lab where the test is going to get carried out.
+      def add_target_lab(order, params)
+        create_order_observation(
+          order,
+          Lab::Metadata::TARGET_LAB_CONCEPT_NAME,
+          params[:date],
+          value_text: params['target_lab']
+        )
+      end
+
+      def create_order_observation(order, concept_name, date, **values)
+        Observation.create!(
+          order: order,
+          encounter_id: order.encounter_id,
+          person_id: order.patient_id,
+          concept_id: ConceptName.find_by_name!(concept_name).concept_id,
+          obs_datetime: date&.to_time || Time.now,
+          **values
+        )
+      end
+
+      def next_accession_number(date = nil)
+        Lab::AccessionNumberService.next_accession_number(date)
+      end
+
+      def unknown_concept_id
+        ConceptName.find_by_name!('Unknown').concept_id
+      end
+    end
+  end
+end