Skip to main content

OpenMRS Adaptor

About OpenMRS​

OpenMRS (Open Medical Record System) is an open-source platform designed to manage electronic medical records (EMRs) in low-resource environments. It provides a framework that allows developers to extend its core functionality through custom modules and APIs.

Integration Options​

1. Rest API: OpenMRS offers a REST API that enables external applications to interact with its database and perform bulk operations. This option is ideal for applications requiring scheduled or bulk synchronization with OpenMRS. Refer to the OpenMRS REST API documentation for detailed guidelines on endpoints and payload formats.

2. Webhook: OpenMRS does not natively support webhooks as a standard feature. However, the platform is highly extensible and allows for customization through its module system. More details can be found on the OpenMRS documentation page​.

Authentication​

When integrating with OpenMRS via OpenFn, Basic Authentication is supported.

The instanceUrl, username an password properties are all required to access your OpenMRS instance.

See Managing Credentials to configure a credential in OpenFn.

If working locally or if using a Raw JSON credential type, then your configuration will look something like this:

{
  "instanceUrl": "http://openmrs.com/instance/url",
  "password":"test",
  "username":"test"
}

See this adaptor's Configuration docs for more details.

API Basics​

There are three ways you can use the OpenMRS API, all available interchangeable in the same step in a workflow.

Like other adaptors, the FHIR adaptor "returns" output by writing to state.data:

get('patient/71075074-f02e-4270-89a3-f2dcda436f70');
fn(state => {
  console.log(state.data); // the downloaded patient is available here
  return state;
});

REST API Operations​

The main namespace contains high-level helper functions, which are designed as the primary interface. These are designed to handle the most common use cases, like downloading OpenMRS resources. They will configure default values and handle some complications for you, like authorization and pagination.

All requests generated by these operations are made against your instance URL plus ws/rest/v1.

For a list of valid resource types, see the OpenMRS REST API Docs. These docs are a useful resource when using OpenMRS, as different resources have different usage rules.

For example, to download all concepts:

get('concept');
// calls <instanceUrl>/ws/rest/v1/concept

Each resource in OpenMRS defines a number of query parameters. These can be passed as an options object as the second argument. For example, to set the source parameter on the concept resource:

get('concept', { source: 'SNOWMED' });
// calls <instanceUrl>/ws/rest/v1/concept?source=SNOWMED

Most options are appended to the request URL as query parameters, so you can pass whatever parameters OpenMRS requires.

The adaptor will download resources over multiple pages. Each individual request to OpenMRS will be logged, for debugging and optimization.

Note that by default, the function imposes a download limit of 10,000 records. You can force all data to be downloaded by passing max: Infinity, like this:

get('concept', { max: Infinity });

When paging, the adaptor will make multiple requests. By default each request will download a page of data according to the instance's configuration. To force a larger page size (and reduce the number of requests, pass pageSize)

get('concept', { pageSize: 1000 });

To disable pagination and force a single request, set limit.

You can page from a specific position by passing startIndex. This works with pagination and with limit.

HTTP Utility Functions​

The REST API operations are be opinionated, and in some cases can make too many assumptions about what you want to do.

The operations in the http namespace are simpler, lower-level helpers and work more like curl or postman. They'll do exactly what you ask for them. They'll handle authorization for you but won't paginate or prepend anything to the requested path.

To request a single page of concepts, you can do:

http.get('ws/rest/v1/concept');

You can pass a query via the options object:

http.get('ws/rest/v1/concept', {
  query: {
    limit: 1000,
    source: 'SNOWMED',
  },
});

Using the http helpers, pagination must be implemented manually.

The HTTP helpers write to things to your state object:

  • state.data is the response body returned by OpenMRS
  • state.response is the rest of the HTTP response (excluding the body), including statusCode, statusMessage and headers.

FHIR Helpers​

The OpenMRS adaptor also provides a FHIR helper API, which allows you to make requests against FHIR endpoints and download FHIR data.

fhir.get('Encounter', {
  count: 100,
  lastUpdated: 'ge2024-01-01T00:00:00Z',
});
  1. OpenMRS Developer Guide
  2. Community Forums: OpenMRS Talk

Implementation Examples​

  1. OpenFn Prototype for Médecins Sans Frontières (MSF) LIME Project - OpenMRS -> DHIS2 sync: https://github.com/OpenFn/openfn-lime