Making a help page

I have been working on the following ticket. The request was to improve upon what was already on the help page (which pretty much was nothing).  So, I went through the entire OpenMRS wiki and picked out top candidates for links that I wanted to include in the help page.  I ended up splitting the help page into three sections of links.  This included links on what OpenMRS is, links to OpenMRS guides, and links to information on getting in contact with the OpenMRS team.  Here is a view of what my help page ended up looking like.

 

 The actual coding for this work was not too difficult.  It included simple HTML but also I needed to learn how to make this work within the Spring Framework that is implemented with OpenMRS.  After a bit of research, I found that in general, code goes into the .jsp files and text (for the web pages) goes into a .properties file.  So, in the .jsp file, you may have something like this...

<ul>
    <li><a href="https://wiki.openmrs.org/x/GwAJ"><spring:message code="help.user.text"/
</a></li>

And then there is a corresponding property in the .properties file such as the following....

help.user.text=User's Guide 

This is simple enough but I ran into a special situation where links that had text around them would have to be handled differently. The solution to this ended up being to pass parameters to the .properties file like so..

<li><spring:message code="help.about.text" arguments="<a href='https://wiki.openmrs.org/x/3gNN'>,</a>"/></li> 

And the corresponding property in the properties file would look something like this...

help.about.text={0}High Level Introduction{1} to OpenMRS 

(where '0' and '1' represent arguments)

The final effect that this would give would be to display the following line.

High Level Introduction to OpenMRS

I submitted a patch for this page a couple of days ago but the developers had some feedback to give me before committing it. This feedback was given via Crucible, a very neat code review tool. This allowed for the developers to hi-light specific lines in my code and make comments on it. See the following screen shot for an example.

 


I submitted a patch last night which addressed the issues which were brought up to me and I expect that it will be accepted pending an ongoing discussion regarding this ticket. A few OpenMRS developers have been debating whether or not links should be put into the .properties file or if they should be in the .jsp file. On the side of keeping the links in the .jsp file, this approach seems to be much better from a design stand point. But, on the side of keeping the links in the .properties file, there is an argument that links can be localized and therefore should be placed here so that translators can later work with them.

  

Sprinting

My group recently ran into some confusion about what we should be working on with OpenMRS.  Apparently the development team is switching to using SCRUM-ish sprints.  Specific tasks are assigned to each weeks sprint.  So, this led to my group trying to figure out if we could still work with tickets that we found on JIRA.  Josh reached out to someone at OpenMRS and apparently it is fine for us to work on whatever tickets we want to work on.  So, that is good news.

In other news, the tickets that our group previously planned on working with did not quite work out.  We chose tickets that were too old and were no longer relevant. So, we have chosen a new set of tickets that have very recently been created.  We have each picked a ticket from JIRA that we will work on.  I am working on making a help page for OpenMRS which will have some general information about OpenMRS as well as some information on how to get help including the mailing lists, the IRC and the wiki.  

   

Feasibility study

Today is the deadline, that my group assigned for us to complete our feasibility study and research on the following bug - trunk 1868.  The bug indicates that when an admin changes the requirements for a password, such as whether or not the password needs at least one number, the message that appears when the user is forced to change his/her password is always the same "Must be at least 8 characters long, contain an uppercase character, and contain at least one number".

The first thing I attempted to do was to recreate the bug.  The global security properties can be found by navigating to the "Administration" section of the dashboard and by then selecting "Manage Global Properties".  I edited the password requirements as so....

I then created a new user (under the "Administration" tab) and selected the option to force the user to change his/her password.  When, I logged in as the user I saw the following...

So, clearly the bug is not present in my version of OpenMRS (1.9).  I took another look at the bug and realised that the "affected version" was listed as 1.6.  Now I am left a little bit confused.  A fix has clearly been made for this bug but a patch has not been submitted.  Perhaps, this old bug has just gotten lost or maybe its just unnecessary to address problems with older versions of OpenMRS.  I'm unsure of how to proceed from here.  I'll need to discuss it with my group members and perhaps the OpenMRS team.

OpenMRS Development Plan

My team has created a general timeline for what we would like to accomplish during the rest of this semester.  We have about six weeks to work with.  We have made the goal of tackling at least four small bugs/features (including the one I have already discussed).  First thing we will accomplish in our timeline is to submit a patch for the changes we've implemented in reference to the following feature request (Preferred ID ).  The rest of our time will be divided into three iterations.  The start of the iteration (about four days) will begin with a detailed study on the bug/feature for the iteration as well as a feasibility study.  During this period, we may choose to pick something else to work on.  Once we have decided to work on the bug/feature and have assigned the ticket to us on JIRA we will have about ten days to complete work on the bug/feature.

As of right now, we plan on working on the following bug during the first iteration (change password).  For our second and third iterations we plan on dealing with the following wish list.  During our 'feasibility study' period we will decide on which features from this wish list we will work on during the iteration.

For a detailed look at our timeline see this

If at first you don't succeed...

CRASH

My team has been relentlessly working on adding this feature to OpenMRS (https://tickets.openmrs.org/browse/TRUNK-256).  On the second day of working on this, tragedy struck.  I lost access to my Ubuntu install.  At the time, I was using Ubuntu via Wubi. Wubi does not really create a separate partition for Ubuntu to run on.  It actually stores the data on the Windows partition and creates the appearance of a dual boot system.  This is good for testing out Ubuntu, but is not recommended for serious use.  Also, it has proven to cause problems.

I am still not 100% sure of what happened but I have a theory.  This problem began after my laptop battery died in the middle of my doing work on my Ubuntu install.  After failing to gain access to my Ubuntu install, I logged into windows and perused the Ubuntu folder that Wubi creates.  I noticed that root.disk was missing.  This file - as I understand it - serves as the data storage for Ubuntu.  So, it seems like, due to my laptop dieing in the middle of my session, a disk error occurred which caused this file to disappear.  I attempted to run chkdsk and checked for the file in Windows 7's hidden C:/found directory.  But it was gone for good.

So what was left to be done? I installed Ubuntu on its own partition.  This actually was kind of tricky because apparently HP computers with Windows 7 come preinstalled with four partitions already in use.  So that leaves you with.....that's right....ZERO partitions to use as you please (seems like someone is trying to discourage dual booting other OSs onto computers).  Nevertheless, I fought back against this tyranny on my hard drive by liberating one of the partitions.  I wiped the HP Tools partition.  After some research, I came to the conclusion that this partition was unnecessary and that I could do without it. (I backed it up though of course)

REDEMPTION

After again going through the process of setting up my Ubuntu install to be ready to develop for OpenMRS, I was back in the game of implementing our feature.  In short, we have been successful.  It's amazing how complex it was to just make sure that a user clicks on a radio button.  In adding this feature, I researched java-script as well as the Java Spring Framework MVC.  Learning about this framework felt like learning a new language.  We needed to find where the validator was for the patient submission form and edit it to reflect this feature.  We also needed to modify the model (the Patient class) and create a new error to be thrown if the radio button was not selected.  The functionality of the page now matches the feature request.  If the user does not select a preferred ID then when the user attempts to save the form, an error will be given to the user which tells him/her that he/she must pick a preferred ID.  My team still needs to figure out how to submit this code for review.  I plan on emailing the dev list today.

To conclude today's blog, my team is technically behind schedule.  But honestly, I could not be more happy with our progress.  My team picked a challenging project that was outside of our comfort zone.  This has required us to do a large amount of research and work in order to contribute. We are now making tangible progress, and we are learning a lot.

"Sine labore nihil"

A bug in our sights

It's time to make a real contribution to OpenMRS.  My team is going to start by resolving a bug.  I started the search for the bug by querying JIRA for all bugs that were marked "ready for work".  This gave me 174 bugs.  So, I began to read through many of them and read the titles of all of them.  I found that the majority of the bugs required a deep knowledge of OpenMRS that no one in my team possesses.  I only found a handful of bugs which I could understand and seemed doable.  Here's the bug that we are currently going with (bug).

The bug seems more like a feature request to me but I could be wrong.  The requirement is that when filling out a patient creation form, the user must select a preferred ID for the patient by selecting the corresponding radio button.  Well, after about 10 seconds of Googling I found a way to require a radio button to be selected via JavaScript.

function checkRadio (patientForm, preferedRBs) {
var radios = document[patientForm].elements[preferedRBs];
for (var i=0; i <radios.length; i++) {
if (radios[i].checked) {
return true; }
}
return false;
}

function valFrm() {
if (!checkRadio("frm1","OpenMRSIDs"))
alert("You didnt select a preferred ID");
else
alert("You selected an id, good job");
}

The problem with this is that OpenMRS already has a mechanism in place for alerting the user when they leave a required field blank.  What we need to do is find the code that handles this.  I attempted this for several hours yesterday.  I viewed the source of the web page and viewed the java-script for the page.  Nothing jumped out at me.  The plan for now is to keep searching for how OpenMRS handles this and - if necessary - reach out to the OpenMRS dev team for help.  More on this to come...         

OpenMRS Bugs

 

As I have previously mentioned, OpenMRS uses JIRA for bug tracking.  I had never heard of it before using OpenMRS but I am really liking it.  Its easy to navigate and it has some really nice graphics for statistics such as number of bugs reported vs bugs resolved over time.  So, for the first part of my bug tracking exercise I have been tasked with finding the oldest bug in the issue tracker that has not been resolved.  Here it is (bug).  I have little to no idea of what the bug actually is.  The entire bug description is fifteen words.  The bug was reported by Ben Wolfe.  From what I can tell, he is a key contributor to OpenMRS.  He's always in the IRC, he is often responding on the dev mailing list and I see his signature on many different OpenMRS contributions.  I have a feeling that when core developers write bug reports they write enough so that the other core developers will get the drift of what the issue is and no more.

This bug was reported back in 2006 so why in the world hasn't there been any action on it?  The priority on it is even 'should'.  The bug report suggests that a research module be created (is this even a bug anyway?).  There are only two comments on it.  Here's an interesting one...

"PIH has created a number of modules for specific research projects, double entry reconciliation, etc. Would be nice to review each of these and see what could be incorporated into a more generic module to support common research project needs."

Upon some research, I found that PIH (Partners in Health) also creates electronic medical records systems.  So, the proposed solution is advising to reuse some already implemented code instead of making it from scratch.  Could be a good idea.  But there are no other comments below this one and the status is still marked 'ready for work'.  This bug seems doomed to linger indefinitely in JIRA limbo.

The next part of the assignment was to create a bug tracker account.  I have had one since the beginning of the project so I'll just say that the process was simple and quick.

Next up on my bug tracking adventure is to reproduce a bug in OpenMRS.  This one sounded easy enough(Chrome Problem).  The issue is that in chrome, an image which is supposed to be used as a link actually contains two links within the image.  If you click on the top portion of the image, then you will be taken to the correct link but if you click on the bottom portion of the image you will be taken to the link that is under the link that you intended to click on.  This was easy to recreate in chrome and it sounds like a fix is close at a hand.  The bug status is marked 'Code Review'.

The final task I have is to attempt to triage five bugs in OpenMRS.  This may prove difficult as even the newest bugs have already been prioritized, commented, given a status, given a priority and some even have already been assigned to a developer.  This project seems to have many prolific contributors who jump on bugs quickly.  I'm going to attempt to watch the bug tracker for a little bit (refreshing the page periodically) and if a new bug pops up I will attempt to beat the other developers to it.

DILIGENCE!

 

Getting, Building, Running OpenMRS

Our team is making some real progress in our efforts to contribute to OpenMRS.  One of our members has successfully made contact with an OpenMRS representative.  The rep inquired how many people we have to work on the project as well as what our time line is.  The idea being that he/she will be able to point us towards some work depending on these variables.

I have successfully checked out the OpenMRS code, built it, and deployed OpenMRS on my local machine.  Setting up my computer to be ready to develop on OpenMRS involved installing many different things that I had no experience with.  Luckily, the OpenMRS website contains a plethora of great information on getting it up and running.

The instruction guide led me to install a subversion plug-in for Eclipse called Subclipse.  Subclipse made it very easy for me to check out the OpenMRS code straight from Eclipse.  Building the project required the installation of a Maven plug-in for Eclipse called m2eclipse.  After installing the plug-in, I just needed to make a new Maven run configuration for the project with the goal "clean install -DskipTests".


Installing and running the actual OpenMRS web app was rather difficult.  It involved installing and configuring MySQL as well as Tomcat6.  I had never used Tomcat before, so this part of the process was especially difficult.  But through the scientific process of Googling tomcat errors followed by reconfiguring, I was eventually able to get Tomcat up and going and then able to deploy OpenMRS on it.

How to contribute to OpenMRS

In the past few days, our team has been searching for the best ways to start to contribute to OpenMRS.  They are using JIRA for issue management.  There is a list of the popular issues here.  I think we could potentially work on many of these.  As an example, here is one issue that caught my eye (open issue).  There is also a list of "unassigned" projects here.  I realized while looking through the OpenMRS website that they have a mentor system in place where each project is assigned a developer(s) and a mentor.  This kind of system could be very useful to people who are new to OpenMRS such as our team.  Apparently, one of our team members has already reached out to OpenMRS and we are now awaiting a reply.

Recently, I have been doing some research on the background and history of OpenMRS.  The founders include Paul Biondich, Burke Mamlin, Hamish Fraser , and Chris Seebregts.  Three of them met at a Medinfo conference and the fourth joined later on.  OpenMRS grew out of a need to scale up treatment of HIV in Africa.  Originally, hospitals would use paper systems, Excel spreadsheets, or poorly designed databases.  OpenMRS was introduced as a software platform which allows people with no programming knowledge to create customized medical record systems.  A core ideal of OpenMRS is that it be a general purpose medical record system that can support the full range of medical treatments.

If you would like to give OpenMRS a test run, check out the demo here.  Log in with username: admin and password: test

OpenMRS

Our group has made a decision.  We are going to be working with OpenMRS this semester and I am rather excited about it.  The scope of the project and the vision behind it makes contributing an exciting prospect.  My team members and myself are taking the first steps necessary to get involved in the project.  This includes joining the project's mailing list and accessing the project's  IRC.  I just joined the developers mailing list today and I have been amazed with all of the discussion that has transpired already.  For example, earlier during the day a contributor pointed out a date input problem with OpenMRS.  Apparently if you are using date format "dd/mm/yyyy" and enter in the date "01/23/2010", the system accepts the date but stores it as "01/11/2011". Additionally if you enter the date "01/01/09" it gets stored as "01/01/0009".  Throughout the day I've been following along, as a variety of contributors have discussed possible fixes to this bug.

I have never used IRC before but it seems easy enough to get the hang of.  You can access the OpenMRS chat room directly through their website but I also wanted to do it via a client.  I ended up installing a Firefox plug-in named Chatzilla.  The only tricky part about using the IRC client was figuring out how to navigate to the OpenMRS chat room.  Apparently ResNet (the wired campus network) blocks the necessary ports needed to connect with an IRC client.  But I successfully connected to the OpenMRS chat room once I switched to an external network.  Once I got down the common IRC commands, I scanned the IRC logs for interesting conversation.  I found a variety of communications from joke telling to the discussing of up coming meetings.  There is still more to be done to be fully ready to contribute to OpenMRS but I intend to reach that point in the coming days.

I recently read The Cathedral and the Bazaar and found it to be a very persuasive case for open source, bazaar style development.  It seems though that this bazaar  style of development is not suited for all projects.  The author even points out that a precondition to using this development strategy is to already have something to work with.  In other words, it is difficult to use the bazaar development style in creating a project from the ground up.  But where this strategy works, it seems to do so extraordinarily well and the reasons for its success are obvious.  These bazaar styled projects have an overflowing tap of resources.  Hundreds or even thousands of world wide contributors can help guide a project to success.  Contributors can hand pick projects that interest them to get involved with and these contributors are motivated (usually) by the desire to obtain reputation or by the need to "scratch an itch" to see progress in a project.  So, you end up with a plethora of contributors who are motivated to do what they do best - design,code,test,debug,and document.  Sounds like a pretty good strategy.

Choosing a project

Our team has now begun the process of selecting an open source project which we will contribute to.  With so many choices it can be intimidating to scale down candidate options.  But throughout our search, I have looked for a couple of key factors that should be present in our final project.  One such factor is explicit information on the project's website on how to get involved.  The other thing I'm looking for is a project that would actually be of interest to our team.  At the moment, I have two 'favorite' projects.  I would enjoy working on either of the two.  The first is OpenMRS (http://openmrs.org/)  OpenMRS is an open source medical record system.  It's core purpose is to aid the delivery of health care in developing countries.  This project is very important to these developing countries that can now have access to such technology that would normally be way out of their price range if they were to consider a proprietary version.  The other project is Plone (http://plone.org/).  It is an open source content management system which prides itself on being elegantly minimalistic.  It has good info on getting involved and is also a viable option.  I will have to discuss these options with my other group members but by the end of the week we will have selected our project.