OpenMRS Open Concept Lab module

The Open Concept Lab module is a module to import concepts to OpenMRS. The concepts from Open Concept Lab and Dictionary Manager can be imported either using a subscription url and unique token or offline from file. The module fetches all the items from the subscription URL updating the existing concepts, and can store subscription URL in global properties.

Development environment

Please make sure you have the following installed:

• MySQL 5.6.x
• JDK 8
• Maven
• OpenMRS SDK, see installation instructions

Next run this command to setup OpenMRS server (just the first time):

$ mvn openmrs-sdk:setup -DserverId=refapp -Ddistro=referenceapplication:2.4
# Note: Pick default values for everything except MySQL username and password

If there are any issues with setting up the server, check out OpenMRS SDK documentation

You also need to deploy webservices.rest module:

$ mvn openmrs-sdk:deploy -DartifactId=webservices.rest -Dversion=2.17-SNAPSHOT -DserverId=refapp

Fork and clone Open Concept Lab module project:

$ mvn openmrs-sdk:clone -DartifactId=openconceptlab
$ cd openmrs-module-openconceptlab

Build and install the module on the server:

$ mvn clean install openmrs-sdk:deploy -DserverId=refapp

You can also configure the server to automatically reload classes and pages from the omod directory:

$ mvn openmrs-sdk:watch -DserverId=refapp

Run the server:

$ mvn openmrs-sdk:run -DserverId=refapp

Once you run the command you need to wait for Jetty Started message, open up a browser and go to:

http://localhost:8080/openmrs

The server can be stopped from the terminal, in which it is running with the Ctrl and C (Ctrl + C) keys combination.

Every time you make changes in code in the api directory, you need to build and install the module and restart the server.

Alternatively you can upload *.omod file via Advanced Administration -> Manage Modules panel. This way you will not have to restart the server.

The module no longer ships a dedicated management UI. On O3, the Open Concept Lab tile under System Administration (/openmrs/spa/ocl, from @openmrs/esm-openconceptlab-app) is where you manage the subscription, run imports (from the subscription or an uploaded zip) and review past imports. Elsewhere the module is configured through global properties and driven through its REST API (/openmrs/ws/rest/v1/openconceptlab/...). Dictionary Manager (https://app.openconceptlab.org) is the recommended front end for browsing and managing the concepts you subscribe to.

The one piece of UI the module still contributes is on the legacy concept dictionary page: if a concept was downloaded from your OCL subscription, it shows a banner warning that local edits will be lost on the next import.

Setup Subscription

You need to set up the subscription before using the module (except for 'Import at server startup'). You will need an account on the Open Concept Lab server, which you can create at https://app.openconceptlab.org/#/accounts/signup/ Login and go to your profile page by clicking your username in the page header and copy your API token, which can be found on the bottom left. Now determine the collection URL or source URL you want to subscribe to, create a version and copy the subscription URL. Set the subscription URL and token through the openconceptlab.subscriptionUrl and openconceptlab.token global properties (or via the module's REST subscription resource), then start an import with POST /openmrs/ws/rest/v1/openconceptlab/import.

OpenMRS Custom Validation Schema

OCL provides a “custom validation schema” feature for OpenMRS that allows the OCL API to perform extra validation checks on concepts. You might get errors while importing concepts to OpenMRS if it is not validated with validator schema. The OpenMRS concept validator rule includes:

For any concept…

1. Only one fully specified name per locale
2. Must not have more than one preferred name per locale
3. All names (except short names) must be unique within the concept
4. Must not have more than one short name per locale
5. Short name must not be marked as locale preferred
6. At least one fully specified name (across all locales)
7. Valid values for class, data type, name type, and locale
8. All concepts should have a UUID (currently OCL’s external ID)
9. Concept UUID should not exceed 38 characters in length
10. Concept UUID must be unique (ideally universally… but certainly within any source/collection)

For a dictionary…

1. Fully specified names must be unique across all names (except short names and index terms) in a locale
2. Multiple concepts cannot share the same preferred name in the same locale
3. All concepts should have a unique external_id (OpenMRS UUID) not exceeding 38 chars