HIS EMR API Development and Documentation
Petros Kayange
Like this project
Posted May 1, 2025
Developed and documented the HIS EMR API for healthcare data management.
Likes
0
Views
0
Timeline
Dec 1, 2020 - May 1, 2025
Clients
Luke International
HIS EMR API
Table of Contents
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:
For sites that are operating offline, you can use the following command to install the required gems
Setting up Production mode
Incase this does not run you might want to make it executable and you can achieve that by doing this
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.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.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:
The command above should give a response similar to the following:
Take token above and use it the following command as a parameter to the Authorization header as:
Updating Metadata
Facilities
You will have to choose the environment you want to update the metadata for.
Developers To add metadata into the system
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
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:
An example of the file output by this process would be
The migration will skip certain results if they are blank/without value. You can find this list in the following file structure:
An example of the file output by this process would be
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
Running the API
You can do the following (don't run it like this in production):
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:
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:
To check the status of the service, run the following command:
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
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:
A wrapper script for the above command is provided to make life easier. Execute it like so:
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.
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>.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/orError 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:
Useful (recommended) tools for development
Vscode for editing
Rubocop - you can use this to format your code and find/fix various defect attractors
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 ContainerWait 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
Contributors
These are organizations that have contributed to the development of the HIS EMR API