Overview

openmrs.js is a JavaScript library that wraps the OpenMRS RESTful API. It provides intuitively named methods to perform common OpenMRS actions, such as creating patients, observations, visits, and much more. It also provides inline help, so you have the API docs right in front of you while you're writing your JavaScript application.

The JavaScript code is dynamically generated from the OpenMRS OpenAPI specification, which is itself generated from the RESTful resources currently available in the system at runtime. This means that JavaScript functions will only be available for resources that your current version of the Rest Web Services Module provides, as well as any other resources provided by add on modules installed in your system.

The library is isomorphic (or more recently, universal), meaning that you can use it the browser or in your Node.js application.

Installation

The openmrs.js library is installed using npm:

npm install openmrs.js

Once the library has been installed, both the browser and the Node.js version can be found in the node_modules directory. To use openmrs.js in the browser, add the browser bundle to your HTML page:

<script src="node_modules/openmrs.js/lib/openmrs.bundle.min.js"></script>

To use openmrs.js in Node.js, require the library in your JavaScript:

const OpenMRS = require('openmrs.js');

Authentication

The OpenMRS RESTful API uses HTTP Basic Authentication. It is therefore very important to use transport layer security when using the API (i.e. run OpenMRS over HTTPS).

To log into OpenMRS with openmrs.js, run:

Alternatively, you can pass in a config object:

The login() method returns a promise, so you will need to wait for it to resolve before using the API. The reason a promise is required, is that openmrs.js is fetching the OpenAPI specification from the server in order to generate the required JavaScript code.

Getting Help

The OpenMRS OpenAPI specification is also used to generate API documentation. Interactive documentation is available at runtime in the OpenMRS application, accessible via the administration page. Click on API Documentation link under the REST Web Services menu.

A static version of the API documentation is also available online at psbrandt.io/openmrs-contrib-apidocs.

You can also get help directly in the Node.js or browser console, but running something like:

o.api.patient.help();

or

o.api.patient.getPatient.help();

The latter should return something like:

getPatient: Fetch by uuid

  * uuid (string): uuid to filter by
  * v (string): The representation to return (ref, default, full or custom)

Running o.api.help(); will give you a list of all API methods available.

hint: try this in your browser console now.

Examples

The following examples show some of the ways that openmrs.js can be used.

Patient

Create a patient with the minimum possible information:

Create a patient with more information:

hint: try these in your browser console now.