Jasper Report Module


The purpose of this module is to allow users to generate Jasper Reports from the OpenMRS interface.


  1. Download the latest version from the OpenMRS module repository and add it to your OpenMRS application using the Administration->Manage Modules page.
  2. Go to the Administration->Manage Global Properties and configure the jasperReport.reportDirectory property to point to the directory on your server that the module can use to upload your reports to (you may have to manually create this directory).
    1. Ensure that Tomcat has permissions to read and write to this directory.
  3. You're done!

Work flow

  1. Create a Jasper Report using iReport (Get iReport from JasperForge)
  2. Add all your report files (all the .jrxml and any images or other required files) to a ZIP archive. (create one archive for each different report)
  3. Create a new Jasper Report on OpenMRS and upload your report archive.
  4. Edit the report parameters.
  5. Test the report by generating it.

Create a new report

  1. Select the Manage Jasper Reports link under the "Jasper Reports" section on the Administration page of OpenMRS.
  2. : This will take you a page that will show you all the existing reports in the system and allow you to edit / generate them.
  3. Click the "Add Report" link near the top of the page.
  4. : You should now have a blank form that looks like this:
  5. :
    1. Enter and a name and description for your report.
    2. In the "Top level report file name" field enter the filename of the top level report i.e. the global parent of all sub-reports. (e.g. Pepfar.jrxml)
    3. Use the "Browse..." button to select a the report archive for your report (the ZIP file containing all your report files)
    4. Click the "Save" button.
  6. : Your report archive will now be uploaded to the server and all the report files will be extracted to a directory on the server. You will be taken back to the "Manage Jasper Reports" page.

Edit a report and its parameters

  1. Select the "Edit report" link for the report you want to edit on list of reports on the "Manage Jasper Reports" page.
  2. : You will be take to the report edit form which will look something like this:
  3. :
    1. If you have made changes to the report files you can upload a new report archive.
    2. : When a new report archive is uploaded the parameters from the new and old report are merged as follows:
      1. Any parameters that existed in the old but do not exist in the new are deleted.
      2. Any parameters that do not exist in the old but do exist in the new are added.
      3. Any parameters that are common to both old and new remain unchanged.
    3. Display Name: the name that is used on the report generator page (i.e. the name to show to the user).
    4. Default Value: self explanitory.
    5. : If a parameter is not marked as visible (i.e. it will not be displayed on the generating screen) it is compulsory to have a default value.
    6. Name: the parameter name defined in the report file.
    7. Class: the Java class of the object the report is expecting for that parameter.
    8. Mapped Class: Where the class of a parameter is "java.lang.Integer" you may map that parameter value to another OpenMRS object. This is accomplished by treating the integer value of the parameter as the id of the object.
    9. Visible: Parameters that are marked as visible will be shown on the report generator page.

Generating a report

  1. Select the "Generate link" next for the report you want to generate.
  2. Enter the required parameters.
  3. Click the generate button.

Once you have clicked the generate button you will be taken back to the Report List page. All reports are generated asynchronously so that the user may continue using the system while a report is being generated. Reports that are being generated are listed on the Report List screen until they are complete. Once a report is complete it may be downloaded from the Report List screen.

Working with Subreports

Subreport can be added to a report by including the Subreport file in the ZIP archive that you upload to OpenMRS.

  • In the parent report, configure a parameter called SUBREPORT_DIR. This parameter is passed to the report from OpenMRS and points to the directory in which the report ZIP archive has been extracted to. Note that the path includes a file separator at the end. E.g.
# : "/usr/local/tomcat/OpenMRS/reports/13/"
# : "c:\OpenMRS\reports\13\"
  • Add your Subreport to your report and configure the "Subreport Expression" on the "Subreport (Other)" tab of the Subreport properties dialog as follows (his tells your report where to find the Subreport file):
# : $P\{SUBREPORT_DIR\}\+ "subreport-filename.jasper"


  • Information
    I'm running Windows Vista but iReport 2.0 will not let me save the report file I created.
  • Solution
    Modify your shortcut to run iReport 2.0 in Windows 2000 compatibility mode.


Simon Kelly