The goal of this API is to allow implementing organisations to customise KenyaEMR by providing additional content such as forms and reports etc.
This API is still in its early stages and is subject to change. We strongly recommend that potential add-on module developers join the KenyaEMR mailing list to be notified about changes and also provide input.
What is an add-on module?
An add-on module is a regular OpenMRS module that provides content to KenyaEMR. Such a module should require KenyaEMR so ensure that you specify this in the add-on module's config.xml:
Next we need to add kenyaemr-api and it's dependencies to the add-on module's main pom.xml. There are too many to list here so take a look at this POM for the example add-on module
To integrate with the UI of KenyaEMR, add-on modules should provide a UI Framework configuration in their webModuleApplicationContext.xml file, e.g.
Checkout the code for this example add-on module.
What content can be added?
An add-on module can add the following content to Kenya EMR:
KenyaEMR uses the OpenMRS App Framework module to manage apps. This means that add-on modules can add new apps by simply defining app descriptor beans in their moduleApplicationContext.xml file, e.g.
An add-on module can define as many new apps as it wants and these will all appear on the KenyaEMR home page. The icon URL must be in format provider:path where provider is UI Framework resource provider and path is the path of the image resource.
In KenyaEMR 13.2, page controllers must use AppUiUtils.startApp(...) to signify which app they belong to. That class is due to removed from the App Framework module and so in 13.3 page controllers will use new @AppPage and @SharedPage annotations to show which app they belong to. These annotations will check that the current user has the required privilege to access the specified app.
KenyaEMR uses the Metadata Deploy module to facilitate the installation of metadata. Add-on modules can provide their own metadata bundles and these will be automatically installed during distribution startup.
To create a bundle, add metadatadeploy as a requirement of your add-on module and then define a component class which extends AbstractMetadataBundle, e.g.
Bundles can also install metadata sharing packages, though this not recommended as package installation can be slow. You can see an example of this here.
Once you've added a form via a metadata bundle, you can integrate it into KenyaEMR by describing it with a form descriptor. Add something like this to your moduleApplicationContext.xml, e.g.
The property values should be as follows:
- targetUuid is the UUID of the form object - NOT the htmlform
- apps specifies the set of apps that will include this form. These are references to AppDescriptor beans in the application context.
- icon is the path to the icon for this form (optional)
- htmlform is the path to the form XML file (optional)
- order is a number used for ordering the forms (optional)
If you specify htmlform then KenyaEMR will load the form content as a UI Framework resource from the specified XML file. Otherwise, KenyaEMR will try to load it from the database.
If you want to use the form as a general visit form, add it to a new FormConfiguration like this
If you want to use the form as a visit form for an existing program in KenyaEMR, add it with a reference to that program;
If you want to add the form to a new program, you have to first describe that new program...
Programs are described with program descriptor beans.
The property values should be as follows:
- targetUuid is a reference to the actual OpenMRS program object
- eligibilityCalculation is calculation which will determine if a given patient is eligible to be enrolled in this program
- defaultEnrollmentForm is the default form for enrollment
- defaultCompletionForm is the default form for discontinuation
- visitForms are the forms which will be included in the "Available Forms" UI component which providers see
- fragments are the UI Framework components which are used to render program specific content
Patient flags are calculation objects which are evaluated for the patient being viewed. To tell KenyaEMR that a calculation should be used as a patient flag make it implement FlagCalculation, e.g.
The calculation should return a true value for any patient who the alert should be displayed for.
Identifier types are described with identifier descriptor beans.
To define your own report first create a report descriptor to describe how the report will be used in the EMR, e.g.
Then create a builder component to construct the ReportDefinition during distribution startup, e.g.
A chore is a task which is run once during a startup of KenyaEMR. Typically a module will use a liquibase changeset to make one-time low-level changes to databases. Chores provide a mechanism to make one-time changes in Java at the end of the KenyaEMR startup process. This means a chore has access to all of the content used by KenyaEMR.
The name of the chore component is used as a global property so ensure that it doesn't contain punctuation except spaces