his_emr_api_lab 0.0.2

data/app/serializers/lab/result_serializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Lab
+  ##
+  # Serialize a Lab order result
+  module ResultSerializer
+    def self.serialize(result)
+      result.children.map do |measure|
+        value, value_type = read_value(measure)
+        concept_name = ConceptName.find_by_concept_id(measure.concept_id)
+
+        {
+          id: measure.obs_id,
+          indicator: {
+            concept_id: concept_name&.concept_id,
+            name: concept_name&.name
+          },
+          date: measure.obs_datetime,
+          value: value,
+          value_type: value_type,
+          value_modifier: measure.value_modifier
+        }
+      end
+    end
+
+    def self.read_value(measure)
+      %w[value_numeric value_coded value_boolean value_text].each do |field|
+        value = measure.send(field)
+
+        return [value, field.split('_')[1]] if value
+      end
+
+      [nil, 'unknown']
+    end
+  end
+end

data/app/serializers/lab/test_serializer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Lab
+  module TestSerializer
+    def self.serialize(test, order: nil, result: nil)
+      order ||= test.order
+      result ||= test.result
+
+      {
+        id: test.obs_id,
+        concept_id: test.value_coded,
+        name: ConceptName.find_by_concept_id(test.value_coded)&.name,
+        order: {
+          id: order.order_id,
+          concept_id: order.concept_id,
+          name: ConceptName.find_by_concept_id(order.concept_id)&.name,
+          accession_number: order.accession_number
+        },
+        result: if result
+                  {
+                    id: result.obs_id,
+                    modifier: result.value_modifier,
+                    value: result.value_text
+                  }
+                end
+      }
+    end
+  end
+end

data/app/services/lab/accession_number_service.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Lab
+  # Responsible for the generation of tracking numbers
+  module AccessionNumberService
+    class << self
+      # Returns the next accession number on the given date or today.
+      #
+      # Throws:
+      #   RangeError - If date is greater than system date
+      def next_accession_number(date = nil)
+        date = validate_date(date || Date.today)
+        counter = find_counter(date)
+
+        counter.with_lock do
+          accession_number = format_accession_number(date, counter.value)
+          counter.value += 1
+          counter.save!
+
+          return accession_number
+        end
+      end
+
+      private
+
+      def find_counter(date)
+        counter = Lab::LabAccessionNumberCounter.find_by(date: date)
+        return counter if counter
+
+        Lab::LabAccessionNumberCounter.create(date: date, value: 1)
+      end
+
+      # Checks if date does not exceed system date
+      def validate_date(date)
+        return date unless date > Date.today
+
+        raise RangeError, "Specified date exceeds system date: #{date} > #{Date.today}"
+      end
+
+      def format_accession_number(date, counter)
+        year = format_year(date.year)
+        month = format_month(date.month)
+        day = format_day(date.day)
+
+        "X#{site_code}#{year}#{month}#{day}#{counter}"
+      end
+
+      def format_year(year)
+        (year % 100).to_s.rjust(2, '0')
+      end
+
+      # It's base 32 that uses letters for values 10+ but the letters
+      # are ordered in a way that seems rather arbitrary
+      # (see #get_day in https://github.com/HISMalawi/nlims_controller/blob/3c0faf1cb6572a11cb3b9bd1ea8444f457d01fd7/lib/tracking_number_service.rb#L58)
+      DAY_NUMBERING_SYSTEM = %w[1 2 3 4 5 6 7 8 9 A B C E F G H Y J K Z M N O P Q R S T V W X].freeze
+
+      def format_day(day)
+        DAY_NUMBERING_SYSTEM[day - 1]
+      end
+
+      def format_month(month)
+        # Months use a base 13 numbering system that's just a subset of the
+        # numbering system used for days
+        format_day(month)
+      end
+
+      def site_code
+        property = GlobalProperty.find_by(property: 'site_prefix')
+        value = property&.property_value&.strip
+
+        raise "Global property 'site_prefix' not set" unless value
+
+        value
+      end
+    end
+  end
+end

data/app/services/lab/concepts_service.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Lab
+  # A read-only repository of sort for all lab-centric concepts.
+  module ConceptsService
+    def self.test_types(name: nil, specimen_type: nil)
+      test_types = ConceptSet.find_members_by_name(Lab::Metadata::TEST_TYPE_CONCEPT_NAME)
+      test_types = test_types.filter_members(name: name) if name
+
+      unless specimen_type
+        return test_types.joins('INNER JOIN concept_name ON concept_set.concept_id = concept_name.concept_id')
+                         .select('concept_name.name, concept_name.concept_id')
+                         .group('concept_name.concept_id')
+      end
+
+      # Filter out only those test types that have the specified specimen
+      # type.
+      specimen_types = ConceptSet.find_members_by_name(Lab::Metadata::SPECIMEN_TYPE_CONCEPT_NAME)
+                                 .filter_members(name: specimen_type)
+                                 .select(:concept_id)
+
+      concept_set = ConceptSet.where(
+        concept_id: specimen_types,
+        concept_set: test_types.select(:concept_id)
+      )
+
+      concept_set.joins('INNER JOIN concept_name ON concept_set.concept_set = concept_name.concept_id')
+                 .select('concept_name.concept_id, concept_name.name')
+                 .group('concept_name.concept_id')
+    end
+
+    def self.specimen_types(name: nil, test_type: nil)
+      specimen_types = ConceptSet.find_members_by_name(Lab::Metadata::SPECIMEN_TYPE_CONCEPT_NAME)
+      specimen_types = specimen_types.filter_members(name: name) if name
+
+      unless test_type
+        return specimen_types.select('concept_name.concept_id, concept_name.name')
+                             .joins('INNER JOIN concept_name ON concept_name.concept_id = concept_set.concept_id')
+                             .group('concept_name.concept_id')
+      end
+
+      # Retrieve only those specimen types that belong to concept
+      # set of the selected test_type
+      test_types = ConceptSet.find_members_by_name(Lab::Metadata::TEST_TYPE_CONCEPT_NAME)
+                             .filter_members(name: test_type)
+                             .select(:concept_id)
+
+      concept_set = ConceptSet.where(
+        concept_id: specimen_types.select(:concept_id),
+        concept_set: test_types
+      )
+
+      concept_set.select('concept_name.concept_id, concept_name.name')
+                 .joins('INNER JOIN concept_name ON concept_name.concept_id = concept_set.concept_id')
+                 .group('concept_name.concept_id')
+    end
+
+    def self.test_result_indicators(test_type_id)
+      # Verify that the specified test_type is indeed a test_type
+      test = ConceptSet.find_members_by_name(Lab::Metadata::TEST_TYPE_CONCEPT_NAME)
+                       .where(concept_id: test_type_id)
+                       .select(:concept_id)
+
+      # From the members above, filter out only those concepts that are result indicators
+      measures = ConceptSet.find_members_by_name(Lab::Metadata::TEST_RESULT_INDICATOR_CONCEPT_NAME)
+                           .select(:concept_id)
+
+      ConceptSet.where(concept_set: measures, concept_id: test)
+                .joins('INNER JOIN concept_name AS measure ON measure.concept_id = concept_set.concept_set')
+                .select('measure.concept_id, measure.name')
+                .group('measure.concept_id')
+                .map { |concept| { name: concept.name, concept_id: concept.concept_id } }
+    end
+
+    def self.reasons_for_test
+      ConceptSet.find_members_by_name(Lab::Metadata::REASON_FOR_TEST_CONCEPT_NAME)
+                .joins('INNER JOIN concept_name ON concept_name.concept_id = concept_set.concept_id')
+                .select('concept_name.concept_id, concept_name.name')
+                .map { |concept| { name: concept.name, concept_id: concept.concept_id } }
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'couch_bum/couch_bum'
+
+require_relative './config'
+
+module Lab
+  module Lims
+    ##
+    # Talk to LIMS like a boss
+    class Api
+      attr_reader :bum
+
+      def initialize(config: nil)
+        config ||= Config.couchdb
+
+        @bum = CouchBum.new(protocol: config['protocol'],
+                            host: config['host'],
+                            port: config['port'],
+                            database: "#{config['prefix']}_order_#{config['suffix']}",
+                            username: config['username'],
+                            password: config['password'])
+      end
+
+      ##
+      # Consume orders from the LIMS queue.
+      #
+      # Retrieves orders from the LIMS queue and passes each order to
+      # given block until the queue is empty or connection is terminated
+      # by calling method +choke+.
+      def consume_orders(from: 0, limit: 30)
+        bum.binge_changes(since: from, limit: limit, include_docs: true) do |change|
+          yield OrderDTO.new(change['doc']), self
+        end
+      end
+
+      def create_order(order)
+        bum.couch_rest :post, '/', order
+      end
+
+      def update_order(id, order)
+        bum.couch_rest :put, "/#{id}", order
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Lab
+  module Lims
+    ##
+    # Load LIMS' configuration files
+    module Config
+      class ConfigNotFound < RuntimeError; end
+
+      class << self
+        ##
+        # Returns LIMS' couchdb configuration file for the current environment (Rails.env)
+        def couchdb
+          config_path = begin
+            find_config_path('couchdb.yml')
+          rescue ConfigNotFound => e
+            Rails.logger.error("Failed to find default LIMS couchdb config: #{e.message}")
+            find_config_path('couchdb-lims.yml') # This can be placed in HIS-EMR-API/config
+          end
+
+          Rails.logger.debug("Using LIMS couchdb config: #{config_path}")
+
+          YAML.load_file(config_path)[Rails.env]
+        end
+
+        ##
+        # Returns LIMS' application.yml configuration file
+        def application
+          YAML.load_file(find_config_path('application.yml'))
+        end
+
+        private
+
+        ##
+        # Looks for a config file in various LIMS installation directories
+        #
+        # Returns: a path to a file found
+        def find_config_path(filename)
+          paths = [
+            "#{ENV['HOME']}/apps/nlims_controller/config/#{filename}",
+            "/var/www/nlims_controller/config/#{filename}",
+            Rails.root.parent.join("nlims_controller/config/#{filename}"),
+            Rails.root.join('config/lims-couch.yml')
+          ]
+
+          paths.each do |path|
+            Rails.logger.debug("Looking for LIMS couchdb config at: #{path}")
+            return path if File.exist?(path)
+          end
+
+          raise ConfigNotFound, "Could not find a configuration file, checked: #{paths.join(':')}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Lab
+  module Lims
+    ##
+    # LIMS' Data Transfer Object for orders
+    class OrderDTO < ActiveSupport::HashWithIndifferentAccess
+      class << self
+        include Utils
+
+        ##
+        # Takes a Lab::LabOrder and serializes it into a DTO
+        def from_order(order)
+          serialized_order = structify(Lab::LabOrderSerializer.serialize_order(order))
+
+          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&.value,
+            phone_number: phone_number,
+            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
+          unless current_health_center.parent
+            raise "Current health center ##{current_health_center.id} is not associated with any district"
+          end
+
+          current_health_center.city_village || current_health_center.parent.name
+        end
+
+        def current_facility_name
+          current_health_center.name
+        end
+      end
+
+      ##
+      # Unpacks a LIMS order into an object that OrdersService can handle
+      def to_order_service_params(lims_order)
+        ActiveSupport::HashWithIndifferentAccess.new(
+          program_id: lab_program.program_id,
+          patient_id: patient.patient_id,
+          specimen_type: { concept_id: specimen_type_id(lims_order.sample_type) },
+          tests: lims_order.tests&.map { |test| { concept_id: test_type_id(test) } },
+          requesting_clinician: requesting_clinician(lims_order.who_order_test),
+          start_date: start_date(lims_order.date_created),
+          target_lab: facility_name(lims_order.receiving_facility),
+          order_location: facility_name(lims_order.sending_facility),
+          reason_for_test: reason_for_test(lims_order.sample_priority)
+        )
+      end
+
+      private
+
+      # Translates a LIMS specimen name to an OpenMRS concept_id
+      def specimen_type_id(lims_specimen_name)
+        if lims_specimen_name == 'specimen_not_collected'
+          return ConceptName.select(:concept_id).find_by_name!('Unknown')
+        end
+
+        concept = ConceptName.select(:concept_id).find_by_name(lims_specimen_name)
+        return concept.concept_id if concept
+
+        raise "Unknown specimen name: #{lims_specimen_name}"
+      end
+
+      # Translates a LIMS test type name to an OpenMRS concept_id
+      def test_type_id(lims_test_name)
+        concept = ConceptName.select(:concept_id).find_by_name(lims_test_name)
+        return concept.concept_id if concept
+
+        raise "Unknown test type: #{lims_test_name}"
+      end
+
+      # Extract requesting clinician name from LIMS
+      def requesting_clinician(lims_user)
+        # TODO: Extend requesting clinician to an obs tree having extra parameters
+        # like phone number and ID to closely match the lims user.
+        first_name = lims_user.first_name || ''
+        last_name = lims_user.last_name || ''
+
+        if first_name.blank? && last_name.blank?
+          logger.warn('Missing requesting clinician name')
+          return ''
+        end
+
+        "#{first_name} #{last_name}"
+      end
+
+      def start_date(lims_order_date_created)
+        lims_order_date_created.to_datetime
+      end
+
+      # Parses a LIMS facility name
+      def facility_name(lims_target_lab)
+        return 'Unknown' if lims_target_lab == 'not_assigned'
+
+        lims_target_lab
+      end
+
+      # Translates a LIMS priority to a concept_id
+      def reason_for_test(lims_sample_priority)
+        ConceptName.find_by_name!(lims_sample_priority).concept_id
+      end
+    end
+  end
+end