his_emr_api_lab 1.1.22 → 1.1.23

data/app/services/lab/orders_search_service.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Lab
+  # Search Lab orders.
+  module OrdersSearchService
+    class << self
+      def find_orders(filters)
+        extra_filters = pop_filters(filters, :date, :end_date, :status)
+
+        orders = Lab::LabOrder.prefetch_relationships
+                              .where(filters)
+                              .order(start_date: :desc)
+
+        orders = filter_orders_by_status(orders, pop_filters(extra_filters, :status))
+        orders = filter_orders_by_date(orders, extra_filters)
+
+        orders.map { |order| Lab::LabOrderSerializer.serialize_order(order) }
+      end
+
+      def find_orders_without_results(patient_id: nil)
+        results_query = Lab::LabResult.all
+        results_query = results_query.where(person_id: patient_id) if patient_id
+
+        query = Lab::LabOrder.where.not(order_id: results_query.select(:order_id))
+        query = query.where(patient_id: patient_id) if patient_id
+
+        query
+      end
+
+      def filter_orders_by_date(orders, date: nil, end_date: nil)
+        date = date&.to_date
+        end_date = end_date&.to_date
+
+        return orders.where('start_date BETWEEN ? AND ?', date, end_date + 1.day) if date && end_date
+
+        return orders.where('start_date BETWEEN ? AND ?', date, date + 1.day) if date
+
+        return orders.where('start_date < ?', end_date + 1.day) if end_date
+
+        orders
+      end
+
+      def filter_orders_by_status(orders, status: nil)
+        case status&.downcase
+        when 'ordered' then orders.where(concept_id: unknown_concept_id)
+        when 'drawn' then orders.where.not(concept_id: unknown_concept_id)
+        else orders
+        end
+      end
+
+      def unknown_concept_id
+        ConceptName.find_by_name!('Unknown').concept_id
+      end
+
+      def pop_filters(params, *filters)
+        filters.each_with_object({}) do |filter, popped_params|
+          next unless params.key?(filter)
+
+          popped_params[filter.to_sym] = params.delete(filter)
+        end
+      end
+
+      def fetch_results(order); end
+    end
+  end
+end

data/app/services/lab/orders_service.rb

@@ -0,0 +1,212 @@
+# 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: :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)
+        raise ::InvalidParameterError, 'Specimen concept_id is required' unless specimen_id
+
+        order = Lab::LabOrder.find(order_id)
+        if order.concept_id != unknown_concept_id && !params[:force_update]&.casecmp?('true')
+          raise ::UnprocessableEntityError, "Can't change order specimen once set"
+        end
+
+        if specimen_id.to_i != order.concept_id
+          Rails.logger.debug("Updating order ##{order.order_id}")
+          order.update!(concept_id: specimen_id,
+                        discontinued: true,
+                        discontinued_by: User.current.user_id,
+                        discontinued_date: params[:date]&.to_date || Time.now,
+                        discontinued_reason_non_coded: 'Sample drawn/updated')
+        end
+
+        if params[:reason_for_test_id]
+          Rails.logger.debug("Updating reason for test on order ##{order.order_id}")
+          update_reason_for_test(order, params[:reason_for_test_id])
+        end
+
+        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 { |test| test.void(reason) }
+        voided = order.void(reason)
+
+        voided
+      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)
+        return Encounter.find(order_params[:encounter_id]) if order_params[:encounter_id]
+
+        raise InvalidParameterError, 'encounter_id or patient_id required' unless order_params[:patient_id]
+
+        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.person.person_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)
+        return nil unless params['target_lab']
+
+        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
+
+      def update_reason_for_test(order, concept_id)
+        raise InvalidParameterError, "Reason for test can't be blank" if concept_id.blank?
+
+        return if order.reason_for_test&.value_coded == concept_id
+
+        raise InvalidParameterError, "Can't change reason for test once set" if order.reason_for_test&.value_coded
+
+        order.reason_for_test&.delete
+        add_reason_for_test(order, date: order.start_date, reason_for_test_id: concept_id)
+      end
+    end
+  end
+end

data/app/services/lab/results_service.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Lab
+  module ResultsService
+    class << self
+      ##
+      # Attach results to a test
+      #
+      # Params:
+      #   test_id: The tests id (maps to obs_id of the test's observation in OpenMRS)
+      #   params: A hash comprising the following fields
+      #     - encounter_id: Encounter to create result under (can be ommitted but provider_id has to specified)
+      #     - provider_id: Specify a provider for an encounter the result is going to be created under
+      #     - date: Retrospective date when the result was received (can be ommitted, defaults to today)
+      #     - measures: An array of measures. A measure is an object of the following structure
+      #         - indicator: An object that has a concept_id field (concept_id of the indicator)
+      #         - value_type: An enum that's limited to 'numeric', 'boolean', 'text', and 'coded'
+      #   result_enter_by: A string that specifies who created the result
+      def create_results(test_id, params, result_enter_by = 'LIMS')
+        serializer = {}
+        results_obs = {}
+        ActiveRecord::Base.transaction do
+          test = Lab::LabTest.find(test_id)
+          encounter = find_encounter(test, encounter_id: params[:encounter_id],
+                                           date: params[:date]&.to_date,
+                                           provider_id: params[:provider_id])
+
+          results_obs = create_results_obs(encounter, test, params[:date], params[:comments])
+          params[:measures].map { |measure| add_measure_to_results(results_obs, measure, params[:date]) }
+          OrderExtension.create!(creator: User.current, value: result_enter_by, order_id: results_obs.order_id,
+                                 date_created: Time.now)
+
+          serializer = Lab::ResultSerializer.serialize(results_obs)
+        end
+        NotificationService.new.create_notification(result_enter_by, prepare_notification_message(results_obs, serializer, result_enter_by))
+        Rails.logger.info("Lab::ResultsService: Result created for test #{test_id} #{serializer}")
+        serializer
+      end
+
+      private
+
+      def prepare_notification_message(result, values, result_enter_by)
+        order = Order.find(result.order_id)
+        { Type: result_enter_by,
+          'Test type': ConceptName.find_by(concept_id: result.test.value_coded)&.name,
+          'Accession number': order&.accession_number,
+          'ARV-Number': find_arv_number(result.person_id),
+          PatientID: result.person_id,
+          'Ordered By': order&.provider&.person&.name,
+          Result: values }.as_json
+      end
+
+      def find_arv_number(patient_id)
+        PatientIdentifier.joins(:type)
+                         .merge(PatientIdentifierType.where(name: 'ARV Number'))
+                         .where(patient_id: patient_id)
+                         .first&.identifier
+      end
+
+      def find_encounter(test, encounter_id: nil, date: nil, provider_id: nil)
+        return Encounter.find(encounter_id) if encounter_id
+
+        Encounter.create!(
+          patient_id: test.person_id,
+          program_id: test.encounter.program_id,
+          type: EncounterType.find_by_name!(Lab::Metadata::ENCOUNTER_TYPE_NAME),
+          encounter_datetime: date || Date.today,
+          provider_id: provider_id || User.current.user_id
+        )
+      end
+
+      # Creates the parent observation for results to which the different measures are attached
+      def create_results_obs(encounter, test, date, comments = nil)
+        void_existing_results_obs(encounter, test)
+
+        Lab::LabResult.create!(
+          person_id: encounter.patient_id,
+          encounter_id: encounter.encounter_id,
+          concept_id: test_result_concept.concept_id,
+          order_id: test.order_id,
+          obs_group_id: test.obs_id,
+          obs_datetime: date&.to_datetime || DateTime.now,
+          comments: comments
+        )
+      end
+
+      def void_existing_results_obs(encounter, test)
+        result = Lab::LabResult.find_by(person_id: encounter.patient_id,
+                                        concept_id: test_result_concept.concept_id,
+                                        obs_group_id: test.obs_id)
+        return unless result
+
+        OrderExtension.find_by(order_id: result.order_id)&.void("Updated/overwritten by #{User.current.username}")
+        result.measures.map { |child_obs| child_obs.void("Updated/overwritten by #{User.current.username}") }
+        result.void("Updated/overwritten by #{User.current.username}")
+      end
+
+      def test_result_concept
+        ConceptName.find_by_name!(Lab::Metadata::TEST_RESULT_CONCEPT_NAME)
+      end
+
+      def add_measure_to_results(results_obs, params, date)
+        validate_measure_params(params)
+
+        Observation.create!(
+          person_id: results_obs.person_id,
+          encounter_id: results_obs.encounter_id,
+          order_id: results_obs.order_id,
+          concept_id: params[:indicator][:concept_id],
+          obs_group_id: results_obs.obs_id,
+          obs_datetime: date&.to_datetime || DateTime.now,
+          **make_measure_value(params)
+        )
+      end
+
+      def validate_measure_params(params)
+        raise InvalidParameterError, 'measures.value is required' if params[:value].blank?
+
+        if params[:indicator]&.[](:concept_id).blank?
+          raise InvalidParameterError, 'measures.indicator.concept_id is required'
+        end
+
+        params
+      end
+
+      # Converts user provided measure values to observation_values
+      def make_measure_value(params)
+        obs_value = { value_modifier: params[:value_modifier] }
+        value_type = params[:value_type] || 'text'
+
+        case value_type.downcase
+        when 'numeric' then obs_value.merge(value_numeric: params[:value])
+        when 'boolean' then obs_value.merge(value_boolean: parse_boolen_value(params[:value]))
+        when 'coded' then obs_value.merge(value_coded: params[:value]) # Should we be collecting value_name_coded_id?
+        when 'text' then obs_value.merge(value_text: params[:value])
+        else raise InvalidParameterError, "Invalid value_type: #{params[:value_type]}"
+        end
+      end
+
+      def parse_boolen_value(string)
+        case string.downcase
+        when 'true' then true
+        when 'false' then false
+        else raise InvalidParameterError, "Invalid boolean value: #{string}"
+        end
+      end
+    end
+  end
+end

data/app/services/lab/tests_service.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Lab
+  ##
+  # Manage tests that have been ordered through the ordering service.
+  module TestsService
+    class << self
+      def find_tests(filters)
+        tests = Lab::LabTest.all
+
+        tests = filter_tests(tests, test_type_id: filters.delete(:test_type_id),
+                                    patient_id: filters.delete(:patient_id))
+
+        tests = filter_tests_by_results(tests) if %w[1 true].include?(filters[:pending_results]&.downcase)
+
+        tests = filter_tests_by_order(tests, accession_number: filters.delete(:accession_number),
+                                             order_date: filters.delete(:order_date),
+                                             specimen_type_id: filters.delete(:specimen_type_id))
+
+        tests.map { |test| Lab::TestSerializer.serialize(test) }
+      end
+
+      def create_tests(order, date, tests_params)
+        raise InvalidParameterError, 'tests are required' if tests_params.nil? || tests_params.empty?
+
+        Lab::LabTest.transaction do
+          tests_params.map do |params|
+            test = Lab::LabTest.create!(
+              concept_id: ConceptName.find_by_name!(Lab::Metadata::TEST_TYPE_CONCEPT_NAME)
+                                     .concept_id,
+              encounter_id: order.encounter_id,
+              order_id: order.order_id,
+              person_id: order.patient_id,
+              obs_datetime: date&.to_time || Time.now,
+              value_coded: params[:concept_id]
+            )
+
+            Lab::TestSerializer.serialize(test, order: order)
+          end
+        end
+      end
+
+      private
+
+      ##
+      # Filter a LabTests Relation.
+      def filter_tests(tests, test_type_id: nil, patient_id: nil)
+        tests = tests.where(value_coded: test_type_id) if test_type_id
+        tests = tests.where(person_id: patient_id) if patient_id
+
+        tests
+      end
+
+      ##
+      # Filter out any tests having results
+      def filter_tests_by_results(tests)
+        tests.where.not(obs_id: Lab::LabResult.all.select(:obs_group_id))
+      end
+
+      ##
+      # Filter LabTests Relation using their parent orders parameters.
+      def filter_tests_by_order(tests, accession_number: nil, order_date: nil, specimen_type_id: nil)
+        return tests unless accession_number || order_date || specimen_type_id
+
+        lab_orders = filter_orders(Lab::LabOrder.all, accession_number: accession_number,
+                                                      order_date: order_date,
+                                                      specimen_type_id: specimen_type_id)
+        tests.joins(:order).merge(lab_orders)
+      end
+
+      def filter_orders(orders, accession_number: nil, order_date: nil, specimen_type_id: nil)
+        if order_date
+          order_date = order_date.to_date
+          orders = orders.where('start_date >= ? AND start_date < ?', order_date, order_date + 1.day)
+        end
+
+        orders = orders.where(accession_number: accession_number) if accession_number
+        orders = orders.where(concept_id: specimen_type_id) if specimen_type_id
+
+        orders
+      end
+
+      def create_test(order, date, test_type_id)
+        create_order_observation(
+          order,
+          Lab::Metadata::TEST_TYPE_CONCEPT_NAME,
+          date,
+          value_coded: test_type_id
+        )
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Lab::Engine.routes.draw do
+  resources :orders, path: 'api/v1/lab/orders'
+  resources :tests, path: 'api/v1/lab/tests', except: %i[update] do # ?pending=true to select tests without results?
+    resources :results, only: %i[index create destroy]
+  end
+
+  get 'api/v1/lab/labels/order', to: 'labels#print_order_label'
+
+  # Metadata
+  # TODO: Move the following to namespace /concepts
+  resources :specimen_types, only: %i[index], path: 'api/v1/lab/specimen_types'
+  resources :test_result_indicators, only: %i[index], path: 'api/v1/lab/test_result_indicators'
+  resources :test_types, only: %i[index], path: 'api/v1/lab/test_types'
+  resources :reasons_for_test, only: %i[index], path: 'api/v1/lab/reasons_for_test'
+end

data/db/migrate/20210126092910_create_lab_lab_accession_number_counters.rb

@@ -0,0 +1,12 @@
+class CreateLabLabAccessionNumberCounters < ActiveRecord::Migration[5.2]
+  def change
+    create_table :lab_accession_number_counters do |t|
+      t.date :date
+      t.bigint :value
+
+      t.timestamps
+
+      t.index %i[date], unique: true
+    end
+  end
+end

data/db/migrate/20210310115457_create_lab_lims_order_mappings.rb

@@ -0,0 +1,15 @@
+class CreateLabLimsOrderMappings < ActiveRecord::Migration[5.2]
+  def change
+    create_table :lab_lims_order_mappings do |t|
+      t.integer :lims_id, null: false, unique: true
+      t.integer :order_id, null: false, unique: true
+      t.datetime :pushed_at
+      t.datetime :pulled_at
+
+      t.timestamps
+
+      t.foreign_key :orders, primary_key: :order_id, column: :order_id
+      t.index :lims_id
+    end
+  end
+end

data/db/migrate/20210323080140_change_lims_id_to_string_in_lims_order_mapping.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class ChangeLimsIdToStringInLimsOrderMapping < ActiveRecord::Migration[5.2]
+  def change
+    reversible do |direction|
+      direction.up do
+        change_column :lab_lims_order_mappings, :lims_id, :string, null: false
+      end
+
+      direction.down do
+        change_column :lab_lims_order_mappings, :lims_id, :integer, null: false
+      end
+    end
+  end
+end

data/db/migrate/20210326195504_add_order_revision_to_lims_order_mapping.rb

@@ -0,0 +1,5 @@
+class AddOrderRevisionToLimsOrderMapping < ActiveRecord::Migration[5.2]
+  def change
+    add_column :lab_lims_order_mappings, :revision, :string
+  end
+end

data/db/migrate/20210407071728_create_lab_lims_failed_imports.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateLabLimsFailedImports < ActiveRecord::Migration[5.2]
+  def change
+    create_table :lab_lims_failed_imports do |t|
+      t.string :lims_id, null: false
+      t.string :tracking_number, null: false
+      t.string :patient_nhid, null: false
+      t.string :reason, null: false
+      t.string :diff, limit: 2048
+
+      t.timestamps
+
+      t.index :lims_id
+      t.index :patient_nhid
+      t.index :tracking_number
+    end
+  end
+end

data/db/migrate/20210610095024_fix_numeric_results_value_type.rb

@@ -0,0 +1,20 @@
+class FixNumericResultsValueType < ActiveRecord::Migration[5.2]
+  def up
+    results = Lab::LabResult.all.includes(:children)
+
+    ActiveRecord::Base.connection.transaction do
+      results.each do |result|
+        result.children.each do |measure|
+          next unless measure.value_text&.match?(/^[+-]?((\d+(\.\d+)?)|\.\d+)$/)
+
+          puts "Updating result value type for result measure ##{measure.obs_id}"
+          measure.value_numeric = measure.value_text
+          measure.value_text = nil
+          measure.save!
+        end
+      end
+    end
+  end
+
+  def down; end
+end

data/db/migrate/20210807111531_add_default_to_lims_order_mapping.rb

@@ -0,0 +1,7 @@
+class AddDefaultToLimsOrderMapping < ActiveRecord::Migration[5.2]
+  def up
+    change_column :lab_lims_order_mappings, :revision, :string, limit: 256, default: nil, null: true
+  end
+
+  def down; end
+end