Reporting Module - Road Map

The current setup we have is using BIRT reporting, however I am interested in learning more about the future roadmap for core reporting modules.

There is a need for us to make a choice on whether to keep BIRT, or move to a new platform (not sure which), but my thinking at this time is to stay as close to the OpenMRS core roadmap as close as possible so that we reduce the amount of maintenance work down the road.

Dear @ssmusoke,

There are a list of community supported modules at…

If you stick to modules on that list, you should be ensured a good support path moving forward. Notice that BIRT is not on that list.

The community recommended reporting module is the “Reporting Module”. So, that would be your best option moving forward. There is a ticket for integration of BIRT as a report renderer into the Reporting Module…

Maybe you can rally support in the community to get BIRT integrated into the Reporting Module. @mseaton is the one to convince.

Hope this helps.

1 Like

My recommendation for the long term would be to:

  • Start using the Reporting module to build underlying report elements, and get away from SQL

  • pick a tool (BIRT, Jasper, etc) that is appropriate for your local teams to create the UI layouts of reports

  • use the Reporting REST module as the way of letting your reporting tool pull data from OpenMRS (avoiding direct SQL calls to the database)

At present the Reporting REST module is quite primitive, so this approach will have some growing pains, but I think in the long run this will grow significantly. (At least it’s what I’m pushing people towards.)

Hi @ssmusoke,

Sorry for the late response here, but just want to second the comments make by @arbaughj and @darius.

The reporting modules that many of us have focused on developing out over the last few years can roughly be categorized as:

  • reporting: This provides the primary interfaces and APIs for querying for data. It has a limited 1.x-based UI for building queries and reports, but this is not it’s strength. It’s strength is in the underlying API that it provides, and in the many well-tested and implementation-driven queries that it supports out of the box. It also provides access to simply using native SQL to get data out, but in a way that hides this behind an abstraction layer so that at a later point in time this can be switched to another implementation of the query if desired.

  • reportingrest: As Darius describes, this module provides a restful api on top of the reporting module. It is still rather immature, but is something that strategically we want to invest more in, in order to facilitate the development of more sophisticated reporting tools in our latest UIs. It is quite possible that this module will be integrated directly into the reporting module in the future.

  • reportingui: This module has intended to provide an initial set of tools in the 2.x UI for running reports and doing ad-hoc analysis, built upon the reporting module API and using restful services provided by reportingrest.

In terms of reporting roadmap, this is relatively quiet at the moment as there are no groups that are pushing particularly hard on any new tool or API development.

At PIH, we have been focusing our attention mostly on incremental improvements to the API to enable us to more effectively write reports using code in our distribution modules. This has meant that we have put less of an emphasis on more general-purpose user interfaces for more easily authoring reports, creating data exports.

That being said, my hopes and aspirations are very much to create more modern tools that can be used by implementations that lack strong developer capacity to author and produce reports, data exports, and other analyses more easily.


Thanks @mseaton for this update. I added the reportingui module and started it. I see it added a “Reports” App to the home screen, but nothing appears when I click on it. Is there any documentation for the reportingui you mentioned?

@arbaughj, I’ve never written any docs on the reportingui module. @darius do you know of any documentation on this?

I just wrote some anemic documentation here:

@arbaughj, you may be interested to see the Run Reports page, but there’s currently no way for you to actually publish your reports to the page without writing a module (so that you can do extension json).

@arbaughj, Actually, I just realized that there is a way that you could add extensions through the UI…

Basically, you would go to “Manage Apps” you can add your own copy of the Reports app whose code is here:

Then, you would add additional json objects under “extensions”. Specifically, you’d copy the thing that’s currently attached to dataExports (see ) and:

  • set your own id, label, requiredPrivilege, and url (presumably the url should be “reportingui/{uuid}”)
  • remove the “featureToggle” property

Good luck!

Thanks @darius for the documentation and possible configuration method without programming. I’ll give it a try when I get a chance.

@darius Thanks, I followed your steps and it worked well using the new Reporting UI.

@mseaton & @darius In general, do you let some admin configure this directly on the (production) instance, or do you bring the preconfigured reports via a module? If the latter, would you have some snippets to share?


Typical usage thus far of this module is for all such reports to be automatically set up in code in a module, though you could certainly create reports using the UI if the available report administration options meet your needs.

A useful mechanism for automatically setting up reports which we use in most of our implementation is the “ReportManager” interface provided by the reporting module. An example of this in use can be seen here:

First, define reports using the ReportManager interface, as done here:

  • Then, in the started method of your activator, use the provided reporting module utility methods to set these reports up automatically by calling:



Thanks Mike, this was very helpful. I could successfuly load a custom report based on a parameterized SQL query through my Activator.

However something bugs me while developing this: I can’t modify anything after running the Activator once. At the moment it really is a one-time install unless I change the report’s UUID. And this despite using the same trick as in PIH/openmrs-module-pihmalawi: invoking this removeOldReports() method prior to doing anything else.

@darius Hi, I have a strange issue when I bring my my_reports_app.json via the /app resources folder of my module. The content of the file is the same as the one I used successfuly directly through Manage Apps.

When I load my module I get this error: URL [jar:file:/private/var/folders/k_/k3v3c7hd15b71kjv55zq6j5w0000gn/T/1446042473601.openmrs-lib-cache/myrefapp/myrefapp.jar!/apps/my_reports_app.json]
 cannot be resolved to absolute file path because it does not reside in the file system: jar:file:/private/var/folders/k_/k3v3c7hd15b71kjv55zq6j5w0000gn/T/1446042473601.openmrs-lib-cache/myrefapp/myrefapp.jar!/apps/my_reports_app.json
Would you have any idea why this is happening or what it means?

Hi Dimitri,

The error messages seems to imply that it is looking in a folder called “apps” rather than “app”. Could this be the problem?


Hi Dimitri,

This is the purpose of the “getVersion()” method on the ReportManager. If you look at the way reports are set up using ReportManagerUtil, you’ll see that reports will be overridden only if the version is greater than the version that was in place the last time the report was set up, or if the version ends with “-SNAPSHOT”.

So, while you are developing your report, just make sure you set your version to something like 1.0-SNAPSHOT. Once you are finished and want to release a version and don’t want the extra time at startup to have this recreated each time, you can set this to a fixed version like 1.0.


About the version.

Nice, that is really handy. I didn’t pay attention obviously and had set a version number without -SNAPSHOT in it. I like that feature!

About /apps

Clearly the AppFramework is looking into /apps, as we can see here. And this is where I placed my _app.json file indeed, alongside others that were working perfectly well until now. @darius’s example suggests that it should be in /apps too: /openmrs-module-reportingui/blob/master/omod/src/main/resources/apps/reports_app.json What made you think that the framework was trying to fetch /app, causing an error?

Ah about the /apps error, nevermind, there was a syntax error in my _app.json file. I forgot to enclose it all in array brackets: [...], because when I tested it through the Manage Apps UI I had to remove those. Sorry about this.

All good now! Thanks again.

I was able to add a custom report to the Reporting UI by following @darius’s PERFECT instructions. I updated the initial documentation he created for this module…

When I run the report, and click to open it, I get an error… java.lang.IllegalStateException: Web Renderers not yet implemented

Also, if the report has a location parameter, when you click to run it, it says “Unknown parameter type: class org.openmrs.Location” where the drop-down for locations should be.

@mseaton, Are there tickets for these, or should I create them?

Lastly, is there a tool that will replace the Cohort Builder in Reporting Compatibility Module? The ad-hoc analysis doesn’t seem to quite do it for me.

Thanks, James

@arbaughj, the idea is that the Ad Hoc Analysis tool is supposed to become the cohort builder replacement, however development on it has stalled. (And, there’s one key thing that you can currently only do by writing code, and not by configuration.)

Can you expound more on “doesn’t seem to quite do it”? What are the specific things in Cohort Builder that you can’t yet do in the Ad Hoc Analysis tool?

I was going to look for patients with a certain diagnosis; based on an obs. No big deal. Hopefully our initial reports will cover their needs, and my teaching them how to make reports will keep them going in the future.

I also didn’t like to have to save it before I could see the results. Hum, I’m not sure i saw any results either.

Maybe I’m just used to the way the old tool worked.