his_emr_api_lab 1.0.5 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cecc609c02db9bc3bfef3b86458006055944bf3bc7729446490c5375c9ceabd4
-  data.tar.gz: 9992f6d05a17f52c725dc014876a29faadc1b96ba2711f26851e73c917e44e61
+  metadata.gz: 69ffcbf9ab0cea24c83a5e18f9298af7599090009eea8f17f111c37333902b64
+  data.tar.gz: 2e4dab1daa94bfa9af75510691c40505468bfb4faaa5410eaaf6cf43ee47e8f8
 SHA512:
-  metadata.gz: 4d37c96cfad06c9d7c8a62dab06ab9c4a2ecbb7ffed973287d09abfe5f7f3fb9d721ae5f473edc1aab7ba100cf4f525af329f8797e319cfb534f7141e96d12c3
-  data.tar.gz: 2e88ceb111fa7a74be37c78d8b7df7a6b179f28c38ee9824d829097e8568c058ea9996afd2105fff44d61e51aa37184d495f77fd6ed6ee84e3ffd86419cc8e9f
+  metadata.gz: 951f366fed5cc8ac190a7b73bcf958a9f93eb233d724fb9b30d42b9f4b5de78985cd20a01cc262fa85a795fb4fdf86d3d8e912e11256b25b980605493319f736
+  data.tar.gz: da971e7cb0f69ea705fcf2b8f9a52d2101959183b20004c0330c2103ec49d03a3c16492b8e3908d3f8ffd13f128a444f6b011c54fdfd37fb982ab392b840a0f0

data/README.md

@@ -43,9 +43,28 @@ Finally run:
 $ bundle exec rails lab:install
 ```
 
+## Configuration
+
+This module in most cases should work without any configuration, however to enable
+certain features some configuration may be required. Visit the
+[configuration](./docs/configuration.md) page to learn how to configure the
+application.
+
 ## Contributing
 
-Contribution directions go here.
+Fork this application create a branch for the contribution you want to make,
+push your changes to the branch and then issue a pull request. You may want
+to create a new first on our repository, so that your pull request references
+this issue.
+
+If you are fixing a bug, it will be nice to add a unit test that exposes
+the bug. Although this is not a requirement in most cases.
+
+Be sure to follow [this](https://github.com/rubocop/ruby-style-guide) Ruby
+style guide. We don't necessarily look for strict adherence to the guidelines
+but too much a departure from it is frowned upon. For example, you will be forgiven
+for writing a method with 15 to 20 lines if you clearly justify why you couldn't
+break that method into multiple smaller methods.
 
 ## License
 

data/app/jobs/lab/update_patient_orders_job.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Lab
+  ##
+  # Fetches updates on a patient's orders from external sources.
+  class UpdatePatientOrdersJob < ApplicationJob
+    queue_as :default
+
+    def perform(patient_id)
+      Rails.logger.info('Initialising LIMS REST API...')
+
+      User.current = Lab::Lims::Utils.lab_user
+      Location.current = Location.find_by_name('ART clinic')
+
+      lims_api = Lab::Lims::Api::RestApi.new
+      worker = Lab::Lims::Worker.new(lims_api)
+      worker.pull_orders(patient_id: patient_id)
+    end
+  end
+end

data/app/jobs/lab/void_order_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Lab
+  class VoidOrderJob < ApplicationJob
+    queue_as :default
+
+    def perform(order_id)
+      Rails.logger.info("Voiding order ##{order_id} in LIMS")
+
+      User.current = Lab::Lims::Utils.lab_user
+      Location.current = Location.find_by_name('ART clinic')
+
+      lims_api = Lab::Lims::Api::RestApi.new
+      worker = Lab::Lims::Worker.new(lims_api)
+      worker.push_order(Lab::LabOrder.unscoped.find(order_id))
+    end
+  end
+end

data/app/models/lab/lab_order.rb

@@ -41,6 +41,10 @@ module Lab
         .where.not(concept_id: ConceptName.where(name: 'Tests ordered').select(:concept_id))
     end
 
+    scope :drawn, -> { where.not(concept_id: ConceptName.where(name: 'Unknown').select(:concept_id)) }
+
+    scope :not_drawn, -> { where(concept_id: ConceptName.where(name: 'Unknown').select(:concept_id)) }
+
     def self.prefetch_relationships
       includes(:reason_for_test,
                :requesting_clinician,

data/app/serializers/lab/lab_order_serializer.rb

@@ -3,7 +3,7 @@
 module Lab
   module LabOrderSerializer
     def self.serialize_order(order, tests: nil, requesting_clinician: nil, reason_for_test: nil, target_lab: nil)
-      tests ||= order.tests
+      tests ||= order.voided == 1 ? voided_tests(order) : order.tests
       requesting_clinician ||= order.requesting_clinician
       reason_for_test ||= order.reason_for_test
       target_lab ||= order.target_lab
@@ -45,5 +45,11 @@ module Lab
 
       ConceptName.select(:name).find_by_concept_id(concept_id)&.name
     end
+
+    def self.voided_tests(order)
+      concept = ConceptName.where(name: Lab::Metadata::TEST_TYPE_CONCEPT_NAME)
+                           .select(:concept_id)
+      LabTest.unscoped.where(concept: concept, order: order, voided: true)
+    end
   end
 end

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

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+class Lab::Lims::Api::RestApi
+  class LimsApiError < GatewayError; end
+
+  class AuthenticationTokenExpired < LimsApiError; end
+
+  class InvalidParameters < LimsApiError; end
+
+  def initialize(config)
+    @config = config
+  end
+
+  def create_order(order_dto)
+    response = in_authenticated_session do |headers|
+      Rails.logger.info("Pushing order ##{order_dto[:tracking_number]} to LIMS")
+
+      if order_dto['sample_type'].casecmp?('not_specified')
+        RestClient.post(expand_uri('request_order', api_version: 'v2'), make_create_params(order_dto), headers)
+      else
+        RestClient.post(expand_uri('create_order'), make_create_params(order_dto), headers)
+      end
+    end
+
+    update_order_results(order_dto)
+
+    data = JSON.parse(response.body)['data']
+
+    ActiveSupport::HashWithIndifferentAccess.new(
+      id: data['tracking_number'],
+      rev: 0,
+      tracking_number: data['tracking_number']
+    )
+  end
+
+  def update_order(_id, order_dto)
+    in_authenticated_session do |headers|
+      RestClient.post(expand_uri('update_order'), make_update_params(order_dto), headers)
+    end
+
+    update_order_results(order_dto)
+
+    { tracking_number: order_dto[:tracking_number] }
+  end
+
+  def consume_orders(*_args, patient_id: nil, **_kwargs)
+    Rails.logger.info('Looking for orders without results...')
+    orders = Lab::OrdersSearchService.find_orders_without_results(patient_id: patient_id)
+
+    orders.each do |order|
+      response = in_authenticated_session do |headers|
+        Rails.logger.info("Fetching results for order ##{order.accession_number}")
+        RestClient.get(expand_uri("query_results_by_tracking_number/#{order.accession_number}"), headers)
+      end
+
+      Rails.logger.info("Result for order ##{order.accession_number} found... Parsing...")
+      results = JSON.parse(response).fetch('data').fetch('results')
+      order_dto = Lab::Lims::OrderSerializer.serialize_order(order)
+      yield lims_results_to_order_dto(results, order_dto), OpenStruct.new(last_seq: 0)
+    rescue InvalidParameters => e # LIMS responds with a 401 when a result is not found :(
+      Rails.logger.error("Failed to fetch results for ##{order.accession_number}: #{e.message}")
+    end
+  end
+
+  def delete_order(_id, order_dto)
+    tracking_number = order_dto.fetch('tracking_number')
+
+    order_dto['tests'].each do |test|
+      Rails.logger.info("Voiding test '#{test}' (#{tracking_number}) in LIMS")
+      in_authenticated_session do |headers|
+        date_voided, voided_status = find_test_status(order_dto, test, 'Voided')
+        params = make_void_test_params(tracking_number, test, voided_status['updated_by'], date_voided)
+        RestClient.post(expand_uri('update_test'), params, headers)
+      end
+    end
+  end
+
+  private
+
+  attr_reader :config
+
+  MAX_LIMS_RETRIES = 5 # LIMS API Calls can only fail this number of times before we give up on it
+
+  ##
+  # Execute LIMS API calls within an authenticated session.
+  #
+  # Method automatically checks authenticates with LIMS if necessary and passes
+  # down the necessary headers for authentication to the REST call being made.
+  #
+  # Example:
+  #
+  #   response = in_authenticated_session do |headers|
+  #     RestClient.get(expand_uri('query_results_by_tracking_number/XXXXXX'), headers)
+  #   end
+  #
+  #   pp JSON.parse(response.body) if response.code == 200
+  def in_authenticated_session
+    retries ||= MAX_LIMS_RETRIES
+
+    self.authentication_token = authenticate unless authentication_token
+
+    response = yield 'token' => authentication_token, 'Content-type' => 'application/json'
+    check_response!(response)
+  rescue AuthenticationTokenExpired => e
+    self.authentication_token = nil
+    retry if (retries -= 1).positive?
+  rescue RestClient::ExceptionWithResponse => e
+    Rails.logger.error("LIMS Error: #{e.response.code} - #{e.response.body}")
+    raise e unless e.response.code == 401
+
+    self.authentication_token = nil
+    retry if (retries -= 1).positive?
+  end
+
+  def authenticate
+    username = config.fetch(:username)
+    password = config.fetch(:password)
+
+    Rails.logger.debug("Authenticating with LIMS as: #{username}")
+    response = RestClient.get(expand_uri("re_authenticate/#{username}/#{password}"), headers: { 'Content-type' => 'application/json' })
+    response_body = JSON.parse(response.body)
+
+    if response_body['status'] == 401
+      Rails.logger.error("Failed to authenticate with LIMS as #{config.fetch(:username)}: #{response_body['message']}")
+      raise LimsApiError, 'LIMS authentication failed'
+    end
+
+    response_body['data']['token']
+  end
+
+  def authentication_token=(token)
+    Thread.current[:lims_authentication_token] = token
+  end
+
+  def authentication_token
+    Thread.current[:lims_authentication_token]
+  end
+
+  ##
+  # Examines a response from LIMS to check if token has expired.
+  #
+  # LIMS' doesn't properly use HTTP status codes; the codes are embedded in the
+  # response body. 200 is used for success responses and 401 for everything else.
+  # We have this work around to examine the response body and
+  # throw errors accordingly. The following are the errors thrown:
+  #
+  #   Lims::AuthenticationTokenExpired
+  #   Lims::InvalidParameters
+  #   Lims::ApiError - Thrown when we couldn't make sense of the error
+  def check_response!(response)
+    body = JSON.parse(response.body)
+    return response if body['status'] == 200
+
+    Rails.logger.error("Lims Api Error: #{response.body}")
+
+    if body['status'] != 401
+      raise LimsApiError, "#{body['status']} - #{body['message']}"
+    end
+
+    if body['message'].match?(/token expired/i)
+      raise AuthenticationTokenExpired, "Authentication token expired: #{body['message']}"
+    end
+
+    raise InvalidParameters, body['message']
+  end
+
+  ##
+  # Takes a LIMS API relative URI and converts it to a full URL.
+  def expand_uri(uri, api_version: 'v1')
+    protocol = config.fetch(:protocol)
+    host = config.fetch(:host)
+    port = config.fetch(:port)
+    uri = uri.gsub(%r{^/+}, '')
+
+    "#{protocol}://#{host}:#{port}/api/#{api_version}/#{uri}"
+  end
+
+  ##
+  # Converts an OrderDTO to parameters for POST /create_order
+  def make_create_params(order_dto)
+    {
+      tracking_number: order_dto.fetch(:tracking_number),
+      district: current_district,
+      health_facility_name: order_dto.fetch(:sending_facility),
+      first_name: order_dto.fetch(:patient).fetch(:first_name),
+      last_name: order_dto.fetch(:patient).fetch(:last_name),
+      phone_number: order_dto.fetch(:patient).fetch(:phone_number),
+      gender: order_dto.fetch(:patient).fetch(:gender),
+      national_patient_id: order_dto.fetch(:patient).fetch(:id),
+      requesting_clinician: requesting_clinician(order_dto),
+      sample_type: order_dto.fetch(:sample_type),
+      tests: order_dto.fetch(:tests),
+      date_sample_drawn: sample_drawn_date(order_dto),
+      sample_priority: order_dto.fetch(:priority) || 'Routine',
+      sample_status: order_dto.fetch(:sample_status),
+      target_lab: order_dto.fetch(:receiving_facility),
+      order_location: order_dto.fetch(:order_location) || 'Unknown',
+      who_order_test_first_name: order_dto.fetch(:who_order_test).fetch(:first_name),
+      who_order_test_last_name: order_dto.fetch(:who_order_test).fetch(:last_name)
+    }
+  end
+
+  ##
+  # Converts an OrderDTO to parameters for POST /update_order
+  def make_update_params(order_dto)
+    date_updated, status = sample_drawn_status(order_dto)
+
+    {
+      tracking_number: order_dto.fetch(:tracking_number),
+      who_updated: status.fetch(:updated_by),
+      date_updated: date_updated,
+      specimen_type: order_dto.fetch(:sample_type),
+      status: 'specimen_collected'
+    }
+  end
+
+  def current_district
+    health_centre = Location.current_health_center
+    raise 'Current health centre not set' unless health_centre
+
+    district = health_centre.district || Lab::Lims::Config.application['district']
+
+    unless district
+      health_centre_name = "##{health_centre.id} - #{health_centre.name}"
+      raise "Current health centre district not set: #{health_centre_name}"
+    end
+
+    district
+  end
+
+  ##
+  # Extracts sample drawn status from an OrderDTO
+  def sample_drawn_status(order_dto)
+    order_dto[:sample_statuses].each do |trail_entry|
+      date, status = trail_entry.each_pair.find { |_date, status| status['status'].casecmp?('Drawn') }
+      next unless date
+
+      return Date.strptime(date, '%Y%m%d%H%M%S').strftime('%Y-%m-%d'), status
+    end
+
+    [order_dto['date_created'], nil]
+  end
+
+  ##
+  # Extracts a sample drawn date from a LIMS OrderDTO.
+  def sample_drawn_date(order_dto)
+    sample_drawn_status(order_dto).first
+  end
+
+  ##
+  # Extracts the requesting clinician from a LIMS OrderDTO
+  def requesting_clinician(order_dto)
+    orderer = order_dto[:who_order_test]
+
+    "#{orderer[:first_name]} #{orderer[:last_name]}"
+  end
+
+  ##
+  # Make a copy of the order_dto with the results from LIMS parsed
+  # and appended to it.
+  def lims_results_to_order_dto(results, order_dto)
+    order_dto.merge(
+      '_id' => order_dto[:tracking_number],
+      '_rev' => 0,
+      'test_results' => results.each_with_object({}) do |result, formatted_results|
+        test_name, measures = result
+        result_date = measures.delete('result_date')
+
+        formatted_results[test_name] = {
+          results: measures.each_with_object({}) do |measure, processed_measures|
+            processed_measures[measure[0]] = { 'result_value' => measure[1] }
+          end,
+          result_date: result_date,
+          result_entered_by: {}
+        }
+      end
+    )
+  end
+
+  def update_order_results(order_dto)
+    if order_dto['test_results'].nil? || order_dto['test_results'].empty?
+      return nil
+    end
+
+    order_dto['test_results'].each do |test_name, results|
+      Rails.logger.info("Pushing result for order ##{order_dto['tracking_number']}")
+      in_authenticated_session do |headers|
+        params = make_update_test_params(order_dto['tracking_number'], test_name, results)
+
+        RestClient.post(expand_uri('update_test'), params, headers)
+      end
+    end
+  end
+
+  def make_update_test_params(tracking_number, test_name, results, test_status = 'Drawn')
+    {
+      tracking_number: tracking_number,
+      test_name: test_name,
+      result_date: results['result_date'],
+      time_updated: results['result_date'],
+      who_updated: {
+        first_name: results[:result_entered_by][:first_name],
+        last_name: results[:result_entered_by][:last_name],
+        id_number: results[:result_entered_by][:id]
+      },
+      test_status: test_status,
+      results: results['results']&.each_with_object({}) do |measure, formatted_results|
+        measure_name, measure_value = measure
+
+        formatted_results[measure_name] = measure_value['result_value']
+      end
+    }
+  end
+
+  def find_test_status(order_dto, target_test, target_status)
+    order_dto['test_statuses'].each do |test, statuses|
+      next unless test.casecmp?(target_test)
+
+      statuses.each do |date, status|
+        next unless status['status'].casecmp?(target_status)
+
+        return [Date.strptime(date, '%Y%m%d%H%M%S'), status]
+      end
+    end
+
+    nil
+  end
+
+  def make_void_test_params(tracking_number, test_name, voided_by, void_date = nil)
+    void_date ||= Time.now
+
+    {
+      tracking_number: tracking_number,
+      test_name: test_name,
+      time_updated: void_date,
+      who_updated: {
+        first_name: voided_by[:first_name],
+        last_name: voided_by[:last_name],
+        id_number: voided_by[:id]
+      },
+      test_status: 'voided'
+    }
+  end
+end