OpenMRS Exercise

Set up the development environment

  1. Download and install Apache Tomcat 6.0.16.
    • Download the .tar.gz file. TAR files are similar to ZIP files, in that a single TAR file consists of many files "glued" together. The .gz suffix indicates that the file has been compressed with gzip. Use the following command to extract the TAR file:
      $ gzcat apache-tomcat-6.0.16.tar.gz | tar xvfB -

      This command says to uncompress apache-tomcat-6.0.16.tar.gz, and send then extract the files from the resulting uncompressed TAR file. This will create the directory apache-tomcat-6.0.16 which contains the tomcat web server package. Since tomcat is written in Java, it does not need to be compiled. We recommend that you execute this command in your home directory, or even better in a directory called apps in your home directory, just to keep things organized.

  2. Configure Eclipse.
    • Hopefully EasyEclipse Java Server is already installed. If not, unpack the file you copied into your account yesterday. Again, we recommend that you do so either in your home directory or (preferably) in the apps subdirectory. To configure Eclipse, start it up, then select Window->Preferences and configure Tomcat as follows:
      1. In the Tomcat pane, select "Version 6.x" and set "Tomcat home" to the apache-tomcat-6.0.16 directory from the previous step.
      2. In the Tomcat Manager pane, set the "ManagerApp username" to "tcmanager" (no quotes) and "ManagerApp password" to abcd1234. Click on "Add to tomcat-users.xml."

      Unfortunately, uploading a web app (like OpenMRS) to the tomcat server from within Eclipse does not seem to work. In this configuration step, we have set up Tomcat itself to allow you to upload the web app from the Tomcat Manager web app; for that, you must have a Tomcat user with the right permissions, which is what we did in step 2. Now start Tomcat by clicking on the fourth button from the left in the Eclipse toolbar.

  3. Install OpenMRS from the OpenMRS Subversion repository. Do this by creating a new Subversion project. Use as the server and navigate to openmrs/trunk. Build the WAR (web app archive) file by right-clicking on build.xml and selecting Run As->Ant Build. This will build the web app but not install it on the Tomcat server.
  4. Configure the OpenMRS runtime properties as follows:
    1. Create the directory .OpenMRS in your home directory.
    2. With a text editor, create the file in .OpenMRS.
    3. Add the following lines to

    What this step does is to tell the web app (once you finally access it) where the database is located and what (MySQL) username and password to use to access it. We won't actually use the database for this exercise, but OpenMRS will not run without this being properly configured.

  5. Install the web app into Tomcat:
    1. Open a web browser and point it to http://localhost:8080/manager/html. You will be prompted for a user name and password; enter tcmanager and abcd1234.
    2. Navigate to the bottom of the Manager page to "Select WAR file to upload." Browse to openmrs/dist/openmrs.war in your Eclipse workspace.
    3. Click on "Deploy."
  6. See if all has worked properly by pointing your browser at http://localhost:8080/openmrs. You should get the OpenMRS login screen; you can log in with Username admin and Password test.

Create a Logo Message Module

  1. Create a new module called LogoMsg module. Follow the instructions at through step 4.
  2. Your module should provide content at the org.openmrs.navigation.homepage extension point (see for a discussion of extension points). Provide the content by writing a class that extends org.openmrs.module.Extension and provides the content by overriding getOverrideContent to return a String such as "The H-FOSS Edition." Don't forget to modify config.xml to register your module for this extension point. Build your module by right-clicking on build.xml and selecting "Run As->Ant Build." This will create a file with an .omod extension in the dist directory of your module project.
  3. Install your module in the web app as follows:
    1. Copy the .omod file to .OpenMRS/modules (create the directory if it does not exist).
    2. Reload the OpenMRS web app by going to the Tomcat manager, finding openmrs, and clicking on "Restart."
  4. Restart OpenMRS by pointing your browser to http://localhost:8080/openmrs.
  5. Repeat these steps until the OpenMRS logo is replaced with "The H-FOSS Edition."

Make a better Logo Message Module

It would be much nicer to add a message after the standard logo than to wipe it out. Figure out how to do so. This involves making a new extension point in the core presentation file web/WEB-INF/view/index.jsp. After doing so, you will need to rebuild the OpenMRS web app and re-deploy it through the Tomcat manager. An ideal solution to this problem would have the following features:

  1. The class you use to add content at the extension point provides that content via a method other than getOverrideContent; for example, see web/WEB-INF/view/admin/index.jsp for how the org.openmrs.admin.list extension point requires classes that register for it implement certain methods.
  2. Instead of hard-coding a message in your class that registers for your new extension point, instead read it from the file; I think System.getProperty should be helpful here. I really don't know if this is possible---I haven't tried it.