NLIMS SETUP

Prerequisites

Before installing NLIMS, ensure that the following requirements are met:

• Ruby 3.2.0
• MySQL 8
• Rails 7
• redis 7+

Configuration

1. Checkout to the main branch

   git checkout main

   OR

   git checkout [tag]

2. Open the respective configuration files in the config folder: Copy the .example file to respective .yml file e.g

   cp database.yml.example database.yml

   • database.yml: Configure your database settings.
   • application.yml: Edit application-specific configurations as required.

3. Update the configuration settings in these files to match your environment.

Installation

1. Install project dependencies using Bundler. Run the following command in your project directory:

   bundle install --local

First-Time Setup

If you are installing the app for the first time, follow these steps:

1. Create the database:

   rails db:create

2. Seed the database with initial data:

   ./bin/initialize_db.sh development

3. Update metadata:

   ./bin/update_metadata.sh development

Updating NLIMS

If you already had NLIMS running before and want to update it, follow these steps:

1. Checkout to intended tag.

   git checkout [tag]

2. Run bundle install

   rm Gemfile.lock
   bundle install --local

3. Run update metadata:

   ./bin/update_metadata.sh

Configuring the integration with other systems

1. Run the following command to configure the integration with other systems and follow the prompts(In production: use the production credentials for master as directed in the setup instruction):

      ./configure_apps.sh

2. Get the user credentials created in the user_credentials.txt file following the script run and and use them in subsequent steps

Running the Application

To start the application:

rails s -p3000 -b 0.0.0.0

To start the sidekiq worker:

bundle exec sidekiq

OR Copy the nlims-api.service file to /etc/systemd/system/. Note that the service file is configured to run the application on port 3009 and rbenv is used(If you are using other environment managers e.g rvm, update accordingly). And the service user is set to emr-user, rails enviroment to development and working directory is set to /var/www/nlims_controller which you can change to your desired location and user and environment(production or development).

sudo cp nlims-api.service /etc/systemd/system/

Then run the following command to start the application:

sudo systemctl start nlims-api

Enable the service to start on boot:

sudo systemctl enable nlims-api

Check the status of the service:

sudo systemctl status nlims-api

Running sidekiq to handle background jobs such as syncing data between the ART application and the central CHSU NLIMS.

Copy the nlims-sidekiq.service file to /etc/systemd/system/. Note that the service user is set to emr-user, rails enviroment to development and working directory is set to /var/www/nlims_controller which you can change to your desired location and user and environment(production or development).

sudo cp nlims-sidekiq.service /etc/systemd/system/

Then run the following command to start the service:

sudo systemctl start nlims-sidekiq

Enable the service to start on boot:

sudo systemctl enable nlims-sidekiq

Check the status of the service:

sudo systemctl status nlims-sidekiq

NOTE: The above steps for running the application are for the ART server and the CHSU server. For the ART server, the application is run on port 3009 and for the CHSU server, the application is run on port 3010 which is configured in the service file.

NOTE: The rails environment in which nlims-api is running should be the same envinronment in which the sidekiq worker is running. If development, sidekiq should also be development. If production, sidekiq should also be production. You can change the environments in the services file.

Running the MaHIS CouchDB integration

NLIMS can listen to MaHIS CouchDB patients_records changes and import lab orders as soon as they are saved in MaHIS. Before starting the listener, make sure the MaHIS CouchDB settings are configured in config/application.yml.

Start the permanent MaHIS CouchDB listener:

RAILS_ENV=production bundle exec rake mahis_couchdb:listen

The listener prints MaHIS CouchDB order activity to the terminal and Rails logs. You should see messages for connection status, pending-order backfill, processed CouchDB changes, imported lab orders, already-imported orders, and failed order imports. Result write-back logs are also printed by the process that pushes the result, usually Sidekiq, including pushed results and failed result write-backs.

The order listener does not scan every patient record. MaHIS marks patient docs that contain NLiMS work with has_pending_nlims_orders=true, and NLIMS creates a CouchDB Mango index on that field. On startup and reconnect, NLIMS queries only those pending docs, then marks each order with nlims_order_listener_status as processed, failed, or dead_letter.

For development, use:

bundle exec rake mahis_couchdb:listen

To test the CouchDB sync once and exit:

RAILS_ENV=production bundle exec rake mahis_couchdb:sync_once

Keep Sidekiq running as well, because result write-back retries, scheduled jobs, and failed-order backfills run through Sidekiq:

RAILS_ENV=production bundle exec sidekiq

If CouchDB or metadata was unavailable and some lab orders were written to SyncErrorLog, retry them manually with:

RAILS_ENV=production bundle exec rake mahis_couchdb:retry_failed_orders LIMIT=100

To enqueue the same retry through Sidekiq:

RAILS_ENV=production bundle exec rake mahis_couchdb:enqueue_retry_failed_orders LIMIT=100

The failed-order backfill job is also scheduled in config/schedule.yml to run every 5 minutes. Restart Sidekiq after changing the schedule so the new cron entry is loaded.

Local NLIMS at Sites

Overview

Local NLIMS (National Laboratory Information Management System) is an integral part of the healthcare infrastructure in ART sites. It plays a crucial role in facilitating communication between the ART application and the central CHSU (Central Health Service Unit) NLIMS. This document provides an overview of how Local NLIMS operates and communicates with various components.

Functionality

• Running in ART Sites: Local NLIMS is deployed and operates within ART sites, specifically on the ART server.

• Communication with ART: Every ART application at the site has an associated account with the Local NLIMS. This allows ART to push orders and pull statuses and results from the Local NLIMS.

• Integration with CHSU NLIMS: Local NLIMS further communicates with the central CHSU NLIMS. It pushes orders to the CHSU NLIMS and pulls statuses and results from it.

• Data Relay to ART: Once the Local NLIMS retrieves statuses and results from the CHSU NLIMS, it pushes this data to the ART application, ensuring seamless data transfer.

• Access Control: Local NLIMS enforces access control by requiring accounts to permit transactions between it and other systems. This access is configured via usernames and passwords.

How ART Communicates with Local NLIMS

ART communicates with the Local NLIMS through its backend, which is the API module. To configure this communication, follow these steps:

1. Check application.yml: Within the EMR API, locate the application.yml file.

2. Configuration Settings:

   • Ensure that lims_api is not commented out, as this allows the API to interact with the Local NLIMS.
   • Verify that lims_port specifies the correct port number on which the Local NLIMS is running.
   • Customize lims_username and lims_password with the appropriate credentials from the user_credentials.txt file created during the nlims setup.

3. With these configurations in place, BHT-EMR-API can now interact with the Local NLIMS. Additionally, a job within the EMR-API allows transactions to and from the Local NLIMS. This job should be scheduled in the crontab to execute at specified intervals. The job is found under bin/lab/sync_worker.rb.

* * * * * /bin/bash -l -c 'cd /var/www/BHT-EMR-API && bin/rails runner -e development '\''bin/lab/sync_worker.rb'\'''

How IBLIS Communicates with Local NLIMS

1. Check application.yml: Within the MLAB API, locate the application.yml file.

2. Configuration Settings:

• Customize username and password of the nlims_service block with the appropriate credentials from the user_credentials.txt file created during the nlims setup.
• Ensure the base_url is pointing to the correct nlims.