FINAL REPORT GSOC-2017 [Generic Tagging Mechanism]

Generic Tagging Mechanism

---

Primary mentor : Wyclif Luyima
Backup mentor : Burke Mamlin
Student : Jai Tatia
Project wiki : Link To Wiki

---

Overview
OpenMRS has always lacked a mechanism that allows users to annotate domain objects with simple text labels/tags, these labels can be useful in various ways e.g to group data and generating work queues. The goal of this project was to provide a tagging mechanism in OpenMRS that cuts across all domain objects.

---

Objectives

There were changes made to the objectives midway based on feedback from the community.

• To create a generic robust Api which will interact with the database and can be used for tagging OpenMRS Objects. (COMPLETED)
• To create a Rest Resource to expose the module and to be able to make Rest Calls to obtain tagging related data. (COMPLETED)
• To create a UI fragment extension to the second Column Fragment of the clinician facing patient dashboard, for performing simple functions such as adding, removing and viewing tags. (COMPLETED)
• To add a feature where-in clicking on a tag redirects to a page where all Patients having that tag are listed. (COMPLETED)

---

Implementation
The following pages cover the implementation details, including rest calls and the user interface.
http://wiki.openmrs.org/display/docs/Generic+Tagging+Module
https://wiki.openmrs.org/display/docs/Generic+Tagging+Module+-+Technical+Documentation
https://wiki.openmrs.org/display/docs/Generic+Tagging+Module+-+User+Guide

Video Presentation:  https://youtu.be/v6fJNYRR0_c

Commit History

https://github.com/openmrs/openmrs-module-tag/commits/master?author=jtatia

Main Project Link

https://github.com/openmrs/openmrs-module-tag

---

Other Resources

Project Documentation: https://wiki.openmrs.org/display/docs/Generic+Tagging+Module
Talk Discussion: https://talk.openmrs.org/t/rest-api-for-generic-tagging/11522

Blog History

• WEEK 12 [16th August – 22nd August]
• WEEK 11 [9th August – 15th August]
• WEEK 10 [ 2nd August – 8th August]
• WEEK 9 [26th July – 1st August]
• WEEK 8 [19th July – 25th July]
• WEEK 7 [12th July – 18th July]
• WEEK 6 [5th July – 11th July]
• WEEK 5 [28th June – 04th July]
• WEEK 4 [21st June – 27th June]
• WEEK 3 [14th June – 20th June]
• WEEK-2 [07th June – 14th June]
• WEEK -1 [30th May – 6th June]
• Community Bonding Period
• Google Summer Of Code

WEEK 12 [16th August – 22nd August]

This was the final week of GSOC before the evaluation week begins. For this period i added a feature where clicking on a tag redirects a user to a page which lists all patients with that tag.

This week will mainly be spent on cleaning up the code, getting rid of any bugs and completing the documentation.

WEEK 11 [9th August – 15th August]

We are almost at the end of the GSOC period. Just one more week to go. This week I focused on cleaning up my UI code. A couple of asynchronous features weren’t working so i worked on getting them to work. Other than that i made corrections based on my mentors review. I also submitted a pr for changing the module structure which was merged.

There is one small feature left, which i plan to work on after the current pr gets merged, hopefully by tomorrow. The feature shouldn’t take too much time.I then plan on working on the documentation and debugging my code.

WEEK 10 [ 2nd August – 8th August]

There was major progress this week with regards to the UI Fragment that was to be added to the clinician facing patient dashboard. After major hacking, the angular resource was completed and the controller is almost at completion. Now all tags added to a patient can be viewed.

Tags can be deleted :-

And Tags can be added:-

A couple of features are left that should be done within the next week. I will then finally move on to documentation, testing and finally making the module ready for the final evaluation.

WEEK 9 [26th July – 1st August]

This week involved working on the UI Fragment for the clinician facing patient dashboard. The fragment will be backed by an angular app. The angular controller will render data by calling methods from an angular service, which in return Uses $resource and $promise for asynchronous data fetching. We make use of the rest resource by making rest calls to obtain data.

The UI Fragment Will Look like below:

I also made a video as my mid-term presentation to describe the work done till now.

WEEK 8 [19th July – 25th July]

This week involved studying AngularJs, which will be needed to create the UI Fragment, for the clinician facing Patient Dashboard. I learnt everything that will be required which includes:- Modules, Directives, Controllers, Databinding, Service, Filter, Http, etc.

Apart from this, I also begin to setup the module along with a reference application distribution, so that i can view the ui changes.
This required me to do the following :-

Using the SDK
First create a ref app distribution on a server using

mvn openmrs-sdk:setup

then put the module on watch

mvn openmrs-sdk:watch -DserverId=myserver

finally cd into the created module
then run

mvn clean install mvn openmrs-sdk:run -DserverId=myserver

also put port:xxxx for remote debugging, in IDE

However I seemed to face some kind of liquibase error which I trying to debug.
I also added the required dependencies, in the module along with a JSON file which will help in creating an extension to the secondColumnFragment in the clinician facing patient dashboard.

WEEK 7 [12th July – 18th July]

 

This week involved me continuing my work on the REST API. After another call with my mentor we were able to organize our efforts and finally come up with How the resource will work. This week also involved me cleaning up the restApi Code So that it could be finally merged. It is finally at the end and the code will be merged my today or tomorrow. With that I can start my work on the UI Fragments. I have already recognized the dependencies that will be needed.
The REST Resource will support searching by :-
1) objectType and objectUuid
2)objectType and tagName

WEEK 6 [5th July – 11th July]

In the Design call held on the 5th of July, a discussion was held on the way forward regarding the Generic-Tagging-Mechanism Project. It was decided that instead of working on Angular directives, the first step would be to add this mechanism to the clinician facing patient dashboard. The plan is to create a fragment in the tagging module and to provide an extension point to the secondColumnFragment in the clinician facing patient dashboard :-

Apart from that several changes were decided for the Rest Resource. I added searching capability by 3 parameters objectType, objectUuid, and tagName. Depending on which parameters are provided a List of tags will be returned. I also started cleaning up the Rest Api code according to the Code Review. The representation was also modified.

For full representation
GET .../v1/tag?tag=my-favorites?v=full

[

{
“uuid”: “uuid-of-tag-object”,
“tag”: “my-favorites”,
“objectType”: “patient”,
“objectUuid”: “…/patient/uuid-of-tagged-patient”,
“auditInfo”: “”
},
{
“uuid”: “uuid-of-tag-object”,
“tag”: “my-favorites-of-all”,
“objectType”: “concept”,
“objectUuid”: “…/patient/uuid-of-tagged-concept”,
“auditInfo”: “”
}
]

WEEK 5 [28th June – 04th July]

The best part of this week, was to know that i had managed to pass the 1st evaluations. 1/3rd period of the time allotted was over, and i am glad that i have been able to adhere to the timeline. A lot of changes have been made to the original time-line. Adding Rest resources to expose the module and working on Angular directives, was something that was planned on later, since we felt that an AngularJs directive would be more useful than a UI fragment. There was just one teeny tiny problem , I had no experience with AngularJs.
This however made the project even more interesting. I for one love the learning curves involved in projects, and the challenges that come with it. With this in mind, I invested my time in understanding AngularJs with focus on directives.

What we aim on achieving is to have an angular directive that one can include on a form for an OpenmrsObject that allows a user to view/add/remove tags. They would take in the following arguments:

viewOnly (boolean): Specifies if the user can only view or can view and also add/remove tags
objectUuid (String): The uuid of the OpenmrsObject
objectType (String): The fully qualified java class name of the domain object

Some good sources for AngularJs:-
https://docs.angularjs.org/tutorial ( for basics)
https://docs.angularjs.org/guide (developers guide)

WEEK 4 [21st June – 27th June]

The start of week 4 meant the completion of the Java API, which was finally merged into the main repository. It all marked the completion of my Phase – 1 task, a few days ahead of schedule. The next task involves exposing the module via the REST API.
This required some feedback from the community. We had decided on creating a Rest Resource :- TagResource, that returns Tag Objects. However there was still a discussion required around creating a seperate resource which returns OpenMRS Objects. The problem was that not all Users have the privelige to view all OpenMRS Objects. A workaround this would be to create a new privelige which allows one to view all OpenMRS Objects returned by the REST API.

Apart from this, this week tasks involved :-
1)Adding Webservices.rest dependencies.
2) Adding a new TagResource class, which overrides basic save, delete , get methods.
3)Creating a corresponding REST controller if required.
4)Creating Unit Tests to test the Rest Api’s working.

The first task above all other was to understand how REST works. REST stands for Representational State Transfer. And a REST API is an API that adheres to the principles of REST and does not require the client to know anything about the structure of the API. Rather, the server needs to provide whatever information the client needs to interact with the service. It basically uses URL’s to perform a fixed set of operations { GET, PUT, POST, DELETE}.