Adding a New Kind of Data to the Patient Summary

Background

This tutorial describes how you would add a new kind of data about the patient. In this example we add "Patient Relationships" which was not previously part of OpenMRS 2.x, adding this to the clinician-facing patient summary (TO DO), as well as adding a detailed screen to manage those relationships.

We assume that you have a 2.x Development Environment set up already, and are familiar with OpenMRS and Angular-JS development.

Step 0 - Create a REST web service API to your data

In this example, Relationship and RelationshipType already exists in the OpenMRS data model, and there are resources for them in the webservices.rest module: RelationshipResource1_8, RelationshipTypeResource1_8.

If you are developing a new kind of data, you will need to create a Java and REST API (which is not covered here).

Step 1 - Create angular services to access your web service resources

AngularJS has an ngResource plugin that makes it very easy to interact with RESTful web services. Although it is possible to access your web services directly via HTTP calls, we strongly recommend using $resource to encapsulate this access in a service, to keep your code clean and simple.

If you want to use a core OpenMRS REST resource, check in the UI Commons module's services folder to see if it already has an associated service. (At time of writing, we only have a very few, so if the one you want is missing, you should feel free to implement the one you want, and contribute it back!). If you are using a module's REST resource, you should put the resource in that module.

Here is "relationshipService.js", which shows a pattern you can copy-and-paste from. (You should copy from the latest version in the services folder linked above, rather than using my annotated version here. Also note that when you copy-paste-edit a new one of these, that you also copy the associated javascript test!)

relationshipService.js (in the uicommons module)

// Each service should be its own angular module, so that a consuming page can include just the ones it needs.
// This module declares that it requires the 'ngResource' module, and the 'uicommons.common' module. (This provides
// important default behaviors, including suppressing the browser's basic authentication popup, and redirecting to the
// login screen if an HTTP call returns a 401 or 403.
angular.module('relationshipService', ['ngResource', 'uicommons.common'])
 
    // This is a lower-level API that the consumer will probably not use directly.
    // Relationship exposes get, query, save, and delete functions: see https://docs.angularjs.org/api/ngResource/service/$resource
    .factory('Relationship', function($resource) {
        return $resource("/" + OPENMRS_CONTEXT_PATH  + "/ws/rest/v1/relationship/:uuid", { // the url template for this resource
            uuid: '@uuid' // tells $resource that the uuid property of an object maps to :uuid in the url template
        }, {
            // Override default $resource behavior, since OpenMRS REST resources return { "results": [...] },
            // whereas $resource expects a plain [...] array.
            query: { method:'GET', isArray:false }
        });
    })
 
    // This is the higher-level API that we want consumers to actually use
    .factory('RelationshipService', function(Relationship) {
        return {

            /**
             * Fetches Relationships
             *
             * @param params to search against
             * @returns $promise of array of matching Relationships (REST ref representation by default)
             */
            getRelationships: function(params) {
                return Relationship.query(params).$promise.then(function(res) {
                    return res.results;
                });
            },

            /**
             * Creates a new relationship
             *
             * @param relationship
             * @returns {Relationship}
             */
            createRelationship: function(relationship) {
                var created = new Relationship(relationship);
                created.$save();
                return created;
            },

            /**
             * Soft-deletes a relationship
             * @param relationship must have a uuid property, but may be a minimal representation
             */
            deleteRelationship: function(relationship) {
                var toDelete = new Relationship({ uuid: relationship.uuid });
                toDelete.$delete();
            }
        }
    });

Note that this is a new pattern for OpenMRS, so we welcome feedback about how to improve it!

The latest version of this code (with less commentary) lives at relationshipService.js.

Step 2 - Create a new screen to manage your data

The OpenMRS 2.x framework is very flexible, so you can implement this screen using any technology, as long as it's accessible via a URL.

The easiest approach is to use the UI Framework to create a GSP page which lets you easily include that patient header and breadcrumbs, and do the majority of i18n.

My current preferred approach beyond that is to implement a single-page AngularJS app that lets us do sophisticated client-side behaviors, while keeping the code clean and organized.

Since we're going to do all the work on the client-side via AngularJS, our page's controller only needs to fetch the patient. Thus we can just extends a base patient controller class:

ListPageController - Located in your module eg: org.openmrs.module.yourmodule.page.controller

package org.openmrs.module.coreapps.page.controller.relationships;

import org.openmrs.module.coreapps.helper.SimplePatientPageController;

public class ListPageController extends SimplePatientPageController {
    // GET defined in superclass
}

The view for this page is large, and will require some AngularJS knowledge to understand (TO DO describe this better):

relationships/list.gsp (in coreapps module)

<%
    // Nearly every page you write should do this, to get the standard reference application decoration and includes
    ui.decorateWith("appui", "standardEmrPage")
 
    // include angular and plugins
    ui.includeJavascript("uicommons", "angular.js")
    ui.includeJavascript("uicommons", "angular-resource.min.js")
    ui.includeJavascript("uicommons", "angular-ui/ui-bootstrap-tpls-0.6.0.min.js")
    ui.includeJavascript("uicommons", "ngDialog/ngDialog.js")
    ui.includeCss("uicommons", "ngDialog/ngDialog.min.css")
 
    // we use the following OpenMRS angular services and directives
    ui.includeJavascript("uicommons", "angular-common.js")
    ui.includeJavascript("uicommons", "services/relationshipService.js")
    ui.includeJavascript("uicommons", "services/relationshipTypeService.js")
    ui.includeJavascript("uicommons", "services/personService.js")
    ui.includeJavascript("uicommons", "directives/select-person.js")
 
    // custom JS and CSS for this page
    ui.includeJavascript("coreapps", "relationships/relationships.js")
    ui.includeCss("coreapps", "relationships/list.css")
%>
 
<!-- Configuring breadcrumbs; you'd typically copy-paste this from another page and change the last item in the list -->
<script type="text/javascript">
    var breadcrumbs = [
        { icon: "icon-home", link: '/' + OPENMRS_CONTEXT_PATH + '/index.htm' },
        { label: "${ ui.escapeJs(patient.patient.familyName) }, ${ ui.escapeJs(patient.patient.givenName) }" ,
            link: '${ui.pageLink("coreapps", "clinicianfacing/patient", [patientId: patient.patient.id])}'},
        { label: "${ ui.escapeJs(ui.message("coreapps.task.relationships.label")) }" }
    ]
</script>
 
<!-- Include the standard patient header before we get to the specifics of this page -->
${ ui.includeFragment("coreapps", "patientHeader", [ patient: patient.patient ]) }
 
<!-- Your page should have a title -->
<h3>${ ui.message("coreapps.task.relationships.label") }</h3>
 
<!-- ng-init is the most convenient way to bootstrap the static js code with dynamic data from this gsp -->
<div id="relationships-app" ng-controller="PersonRelationshipsCtrl" ng-init="init('${ patient.patient.uuid }')">

    <!-- This is how you do an inline angular template -->
    <script type="text/ng-template" id="addDialogTemplate">
        <div class="dialog-header">
            <h3><%= ui.message("coreapps.relationships.add.header", "{{ ngDialogData.otherLabel }}") %></h3>
        </div>
        <div class="dialog-content">
            <div>
                <label>
                    <%= ui.message("coreapps.relationships.add.choose", "{{ ngDialogData.otherLabel }}") %>
                </label>
                <select-person ng-model="otherPerson" exclude-person="${ patient.patient.uuid }" />
            </div>
            <div class="add-confirm-spacer">
                <div ng-show="otherPerson" >
                    <h3>${ ui.message("coreapps.relationships.add.confirm") }</h3>
                    <p>{{ ngDialogData.thisLabel }}: ${ ui.format(patient.patient) } ${ ui.message("coreapps.relationships.add.thisPatient") }</p>
                    <p>{{ ngDialogData.otherLabel }}: {{ otherPerson.display }}</p>
                </div>
            </div>
            <div>
                <button class="confirm right" ng-disabled="!otherPerson" ng-click="confirm(otherPerson)">${ ui.message("uicommons.save") }</button>
                <button class="cancel" ng-click="closeThisDialog()">${ ui.message("uicommons.cancel") }</button>
            </div>
        </div>
    </script>
    <script type="text/ng-template" id="deleteDialogTemplate">
        <div class="dialog-header">
            <h3>${ ui.message("coreapps.relationships.delete.header") }</h3>
        </div>
        <div class="dialog-content">
            <form>
                ${ ui.message("coreapps.relationships.delete.title") }
                <p>
                    <label>{{ relType(ngDialogData.relationship).aIsToB }}</label>
                    {{ ngDialogData.relationship.personA.display }}
                </p>
                <p>
                    <label>{{ relType(ngDialogData.relationship).bIsToA }}</label>
                    {{ ngDialogData.relationship.personB.display }}
                </p>
                <button  class="confirm right" ng-click="confirm()">${ ui.message("uicommons.delete") }</button>
                <button class="cancel" ng-click="closeThisDialog()">${ ui.message("uicommons.cancel") }</button>
            </form>
        </div>
    </script>
 
    <div ng-repeat="relType in relationshipTypes">
        <h6>
            {{ relType.aIsToB }}
            <a ng-click="showAddDialog(relType, 'A')">
                <i class="icon-plus-sign edit-action"></i>
            </a>
        </h6>
        <span ng-repeat="rel in relationshipsByType(relType, 'A')" class="relationship">
            {{ rel.personA.display }}
            <a ng-click="showDeleteDialog(rel)">
                <i class="icon-remove delete-action"></i>
            </a>
        </span>
        <span ng-show="relType.aIsToB == relType.bIsToA" ng-repeat="rel in relationshipsByType(relType, 'B')" class="relationship">
            {{ rel.personB.display }}
            <a ng-click="showDeleteDialog(rel)">
                <i class="icon-remove delete-action"></i>
            </a>
        </span>
        <span ng-hide="relType.aIsToB == relType.bIsToA">
            <h6>
                {{ relType.bIsToA }}
                <a ng-click="showAddDialog(relType, 'B')">
                    <i class="icon-plus-sign edit-action"></i>
                </a>
            </h6>
            <span ng-repeat="rel in relationshipsByType(relType, 'B')" class="relationship">
                {{ rel.personB.display }}
                <a ng-click="showDeleteDialog(rel)">
                    <i class="icon-remove delete-action"></i>
                </a>
            </span>
        </span>
    </div>

</div>
<script type="text/javascript">
    // manually bootstrap angular app, in case there are multiple angular apps on a page
    angular.bootstrap('#relationships-app', ['relationships']);
</script>

Finally the JS that controls this page's behavior:

relationships.js (from the coreapps module)

The current, latest version of this code (with fewer comments) can be found at relationships/list.gsp and relationships.js.

Step 3 - Use an Extension to link to your screen from the patient summary

In this example, the piece of data that we're adding (relationships to other persons in the system) is at the level of the patient, and not any particular visit or encounter. Therefore we would like to add a link to it in the "overall actions" sections of the patient summary:

Since relationships are a core part of the system that we want to include out of the box in the reference application, in this example we add this extension to the coreapps module. If you are building add-on functionality, you would want to implement this in your own module.

We add the following to the overallActions_extension.json file in the coreapps module. See App Framework Developer Documentation if you want detailed documentation on this structure.

Projects