HIS EMR API

Table of Contents

• HIS EMR API
  • Requirements
  • Setting up
    • Configuration
    • Setting up rails
    • Setting up Production mode
      • Database
        • Using an existing database
        • Using an empty database
      • DDE
    • Updating Metadata
    • EMC to POC
    • AIT Intergration
    • Running the API
  • Creating a Service
  • Raw Data Store
  • For developers
    • Documentation
      • Building the Documentation
    • Testing
    • Coding style/standards
    • Useful (recommended) tools for development
    • Dev Container
    • Data Cleaning
  • Contributors

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

Back to top

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

1. Load metadata into your mysql database as follows:

   cat db/sql/openmrs_metadata_1_7.sql | mysql -u <username> -p <database_name>

2. Run migrations:

   bin/rails db:migrate

3. Load moh regimen tables into your database:

   cat db/sql/add_regimens_13_and_above.sql | mysql -u <username> -p <database>

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

   cat db/sql/ntp_regimens.sql | mysql -u <username> -p <database>

5. Set up the test database as follows:

   bin/initial_database_setup.sh test mpc

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

   bin/rspec

Using an empty database

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

   bin/initial_database_setup.sh production mpc && bin/initial_database_setup.sh development mpc && bin/initial_database_setup.sh test mpc

2. Run test suite as follows:

   bin/rspec

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

Back to top

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

Back to top

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

Back to top

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

Back to top