HIS EMR API Development and Documentation

Petros Kayange

Completed work

Database Engineer

Software Engineer

MySQL

Ruby

Ruby on Rails

Healthcare

HIS EMR API

Requirements

The following are required to run the API:

Ruby 3.2+

Rails 7.0+

MySQL 5.6+

The following dependencies are also required for some operations, however the API can do without:

DDE3 - Grab it from here

In addition to the requirements above, you need the following for development.

Postman - Used for editing documentation

Postmanerator - Used for building the documentation

Setting up

All the operations below assume your current working directory is the project directory. Navigate to that if you are some place else.

Configuration

Setting up rails

Install the required gems like so:

bundle install

For sites that are operating offline, you can use the following command to install the required gems

bundle install --local

Setting up Production mode

bin/setup_production_mode.sh

Incase this does not run you might want to make it executable and you can achieve that by doing this

chmod +x bin/setup_production_mode.sh

Database

The API uses an Openmrs 1.7 compatible database as a base for its own database. If you have an ART database dump available you can (and should) use that. The API was designed to hook into an already existing database.

Copy the configuration file from config/database.yml.example to config/database.yml. Edit the new file to point to your database.

$ cp config/database.yml.example config/database.yml
...
$ vim config/database.yml   # Edit configuration
...

Using an existing database

Load metadata into your mysql database as follows:

Run migrations:

Load moh regimen tables into your database:

For TB app: Load ntp regimen tables into your database:

Set up the test database as follows:

Run the following to run tests (if all goes well you are good to go):

Using an empty database

Run the following commands to set up your development and test databases.

Run test suite as follows:

DDE

Configuration

Copy config/application.yml.example to config/application.yml. Edit all the dde_* parameters to point to a running DDE instance.

$ cp config/application.yml.example config/application.yml
...
$ vim config/application.yml
...

Enabling DDE

To enable DDE you have to set the global_property dde_enabled to 1. Global properties can be updated through the properties end-point or directly in the database on the global_property table. Below is how you can do it on a UNIX terminal.

First log into the API:

curl -X POST -H "Content-Type: application/json" -d '{
    "username": "admin",
    "password": "test"
}' "http://127.0.0.1:3000/api/v1/auth/login"

The command above should give a response similar to the following:

    {
        "authorization": {
            "token": "AiJViSpF3spb",
            "expiry_time": "2018-08-28T11:01:55.501+02:00"
        }
    }

Take token above and use it the following command as a parameter to the Authorization header as:

curl -X POST -H "Authorization: AiJViSpF3spb" -H "Content-Type: application/json" -d '{
    "property": "dde_enabled",
    "value": "true"
}' "http://127.0.0.1:3000/api/v1/properties"

Updating Metadata

Facilities

./bin/update_art_metadata.sh [production|development|test]

You will have to choose the environment you want to update the metadata for.

Developers To add metadata into the system

bin/dump_metadata.sh

Commit the changes to the repository. And as always make sure you create a PR to be reviewed.

EMC to POC

These are the instructions of migrating data for sites that have changed from an e-Mastercard(EMC) to Point of Care(POC). Open a terminal and navigate to the API application folder. On the root of the application folder run this command in your terminal

rails r ./bin/vl_migration.rb

Once this process completes a csv file will be created on the root of the application folder. The file name will have the following structure:

emc_poc_migration_dateMigrationWasRun.csv

An example of the file output by this process would be

emc_poc_migration_20220816.csv

The migration will skip certain results if they are blank/without value. You can find this list in the following file structure:

emc_poc_migration_skipped_yearmonthday.csv

An example of the file output by this process would be

emc_poc_migration_skipped_20220816.csv

The file will indicate the result date and the client ARV number which can be used for BDE purposes

AIT Intergration

To intergrate to AIT and send HTS patient data, follow the steps below

Copy and populate the AIT config file

cp ./config/ait.yml.example ./config/ait.yml

SETUP AIT CONFIGURATION

Running the API

You can do the following (don't run it like this in production):

bin/rails server

Creating a Service

Instead of manually running the server, you can create a service to run the server. This is useful when you want to run the server in the background. To create a service, run the following command:

sudo chmod +x ./bin/create_service.sh && ./bin/create_service.sh

Please follow the instructions provided by the script. Once the service is created, you can start, stop, and restart the service using the following commands:

sudo service emr-api start
sudo service emr-api stop
sudo service emr-api restart

To check the status of the service, run the following command:

sudo service emr-api status

Raw Data Store

The BHT-EMR-API is capable of pushing data to the Raw Data Store. More information on how to get it to do this can be found here

For developers

Documentation

If you need to build the documentation then you have to set up postman and postmanerator. Set up postman by following the instructions provided here. For postmanerator grab a binary for your operating system from here.

Building the Documentation

To edit the documentation, fire up postman and then import the collection at doc/src/index.json. Once done editing it in postman, export it back as version 1 collection to the same path.

To build the documentation do the following:

postmanerator --collection=doc/src/index.json --output=public/index.html

A wrapper script for the above command is provided to make life easier. Execute it like so:

bin/make_docs

You can view the documentation by opening public/index.html or hitting /index.html on a running instance of the API.

Testing

RSpec and RSpec-rails are used for unit/integration testing. Primarily tests are written as feature tests for services (See coding style below), however in some cases unit tests are done for small pieces that looks suspect.

A test database is require before anything else. Run the following to set up the test database.

$ bin/initial_database_setup.sh test moh
...

WARNING: The command above will clobber the database set up for testing the database configuration.

To run the tests, navigate to the project directory and run bin/rspec. You can target a specific test by running bin/rspec <path-to-test>.

$ bin/rspec     # To run all tests
...
$ bin/rspec path/to/test    # To run specific test
...

Coding style/standards

At a minimum try to stick to the following:

Use 2 spaces (not tab configured to take 2 spaces) for indentation

Methods should normally not exceed 12 lines (you can go beyond this with good reason)

Prefer &&/|| over and/or

Error should never pass silently, if you handle an exception, log the error you just handled

Related to the point above, avoid inline rescue statements

Use guard statements when validating a variable, if you can't, consider moving the validation logic to a method

Package your business logic in services where possible. These are located in app/services directory. Try to keep them SOLID please.

If you know it's a hack please leave a useful comment

If what you wrote doesn't make sense, revise until it does else leave useful comments and a unit test

If a file exceeds 120 lines, you better have a good reason as to why it is so

This is Ruby, it shouldn't read like Java, see Writing Beautiful Ruby

See the following for more:

Rubocop style guide

Useful (recommended) tools for development

Vscode for editing

Rubocop - you can use this to format your code and find/fix various defect attractors

If you use VSCode check out the following plugins Ruby, Ruby-Rubocop, and Rufo, Ruby Solargraph

Dev Container

Install Docker

Install Docker Compose

We assume you are using VSCode as your editor

Install the Remote - Containers extension

Open the project in VSCode

Click on the green button at the bottom left of the window

Select Reopen in Container

Wait for the container to build

Run bash bin/container_start.sh to setup the container and install dependencies. Only run this once unless you have rebuilt the container. If nothing happens after running this command, then you might want to execute the commands in the script manually.

Note: If you are using a dev container, then it comes with a pre-configured database and you don't need to run the migrations and seeds.

Note: Perks of using a dev container include:

You don't need to install Ruby, Rails, MySQL, etc on your local machine

You don't need to worry about setting up the database, migrations, seeds, etc

You don't need to worry about setting up mysql client the container comes with it pre-installed

You don't need to worry about setting up the environment variables, the container comes with them pre-configured

You don't need to worry about setting up the storage, the container comes with it pre-configured

You don't need to worry about setting up the locale, the container comes with it pre-configured

You don't need to worry about setting up the gems, the container comes with them pre-installed

Data Cleaning

ANC

Contributors

These are organizations that have contributed to the development of the HIS EMR API

Like this project

Completed work

Posted May 1, 2025

Developed and documented the HIS EMR API for healthcare data management.

Likes

Views

Timeline

Dec 1, 2020 - May 1, 2025

Clients

Luke International

HIS EMR API Development and Documentation

HIS EMR API

Table of Contents

Requirements

Setting up

Configuration

Setting up rails

Setting up Production mode

Updating Metadata

EMC to POC

AIT Intergration

Running the API

Creating a Service

Raw Data Store

For developers

Documentation

Testing

Coding style/standards

Useful (recommended) tools for development

Dev Container

Data Cleaning

Contributors