BIRT ODA Plugin Developers Guide

[edit]

Overview

This article is meant to guide any developers that are interested in changing or enhancing the OpenMRS BIRT ODA. For information on how to use the BIRT ODA, please see the BIRT ODA Plugin User Guide.

[edit]

Setup Development Environment

[edit]

Install BIRT

To test changes made to the BIRT ODA, you will want to install the latest version of Eclipse BIRT. For Windows, you can select the All-in-One link on the BIRT download page. The designer for Linux can be obtained by following the More Downloads link on the BIRT download page.

To install BIRT within an existing Eclipse installation, follow these instructions to install BIRT via Eclipse's Update Manager.

Make sure you install at least version 2.3.1 of BIRT. Version 2.3.1 is required for the ODA Drivers to function properly.
[edit]

Checkout the BIRT ODA Plugin

An ODA Plugin consists of both a runtime and a user interface (UI) component. You will want to check both out via SVN in your BIRT Eclipse installation. The runtime component can be checked out at http://svn.openmrs.org/openmrs-contrib/eclipse/plugins/birt-oda-plugin/org.eclipse.datatools.connectivity.oda.openmrs/ and the UI component can be checked out at http://svn.openmrs.org/openmrs-contrib/eclipse/plugins/birt-oda-plugin/org.eclipse.datatools.connectivity.oda.openmrs.ui/.

[edit]

ODA Components

The javadocs for the different ODA classes can be generated or viewed online here.

[edit]

Runtime

The runtime component is what will actually be used when you run your report as oposed to when you are creating your data source and data set as part of your report design.

Some notes about the classes that do most of the "work":

  • Connection - Authorizes the connection using the provided OpenMRS path, username, and password.
  • Query - Prepares and calls the XmlParser to get the final data used in the report given the different parameters (token, tag, filter, etc.) for the OpenMRS query. A ResultSet is returned.
  • ResultSetMetaData - Provides various information to BIRT about the tokens like labels, data types, etc.
  • XMLParser - Handles all of the interactions with the Logic Web Service to get the tokens, tags, filters, data, etc.
  • Token - Represents an individual token selection and stores information like the token name, data type, aggregation information, modifier information, and splitter information.
  • QueryBuilder - Helper class for building up and breaking down the Logic Web Service query based on the stored query and runtime Token information.
[edit]

UI

The UI component is the GUI part of the ODA that allows the user to interact and provide connection information as well as interface to create an OpenMRS query with the desired tokens and modifiers.

Some notes about the UI classes that do most of the "work":

  • Data set wizard pages:
    • TokenSelectionPage - Provides the interface for the user to choose the desired filter and tokens for the query. The tokens can be narrowed down by using the token tags and search feature.
    • ModifierPage - Allows the user to provide aggregate and modifier information for each selected token.
      • AggregateRow - Storage and interface handler for aggregate information for each token.
      • Modifiers - Storage and interface handler for modifier information for each token.
    • SplitterPage - Allows the user to decide how to "split" their selected tokens. For instance, not only provide the value of the token, but the Observation Location, Observation Date, Encounter Location, Encounter Type, etc.
      • SplitTokenCheckBox - Storage and interface holder for each unique token/splitter combination.
    • ViewQueryPage - Shows the user the Logic Service Query built so far. Also allows the user to toggle between the different data style (most recent, stacked, and flat).
  • InformationHolder - In-memory storage for all query information so that each data set page has the most up-to-date information about the user's selections.
  • CustomDataSetWizard - Overrides DataSetWizard so that TokenSelectionPage is the only page displayed when first creating the data set.
  • Utils - Helper class for building up and breaking down the Logic Web Service query based on the stored query and runtime Token information.


The interface uses The Standard Widget Toolkit (SWT) for rendering graphics. The following are some helpful resources on SWT:

[edit]

Running

[edit]

In the Development Environment

To run the ODA within your Eclipse development environment, simply right-click your org.eclipse.datatools.connectivity.oda.openmrs.ui project and choose Run As -> Eclipse Application. This will open a new Eclipse application where your changes to the BIRT ODA should be reflected when creating a data set or data source and running the report.

[edit]

Deploying as part of BIRT

To create the distributable jars for other to install and use:

  1. Switch perspectives to the Plug-in Development perspective.
  2. Go to File --> Export and select "Deployable plug-ins and fragments" from the box under Plug-in Development and click next.
  3. In the Available Plug-ins and Fragments box, select both org.eclipse.datatools.connectivity.oda.openmrs and org.eclipse.datatools.connectivity.oda.openmrs.ui. Select the Destination tab on the bottom and select the Directory option. Type a directory where you wish the plugins to be created.
  4. Click finish and wait for the export to finish. Navigate to the folder that you chose on the last prompt. There should be a folder called "plugins" which will now contain the files org.eclipse.datatools.connectivity.oda.openmrs_x.x.x.jar and org.eclipse.datatools.connectivity.oda.openmrs.ui_x.x.x.jar.
  5. These two jars can be placed under the plugins directory of an Eclipse BIRT installation for the OpenMRS BIRT ODA to be available.
[edit]

Testing

[edit]

Using the Mock Logic Web Service

To make testing of the ODA easy, one can check out the Mock Logic Web Service at http://svn.openmrs.org/openmrs-modules/odamocklogicws/. This allows the developer to decouple the Logic Web Service from the ODA and configure the Mock Logic Web Service to return data as desired or as expected in future releases of the Logic Service API.

The Mock Logic Web Service will need to be modified to work with the current BIRT ODA.
[edit]

JUnit Tests

The BIRT ODA runtime, UI, and Logic Web Service all have JUnit/HttpUnit tests that can be explored and expanded upon to test different functionality.

[edit]

Starting from Scratch

For those that want to start from the beginning instead of using the existing OpenMRS BIRT ODA, you can use the ODA Runtime and Designer projects in BIRT to start with a simple stubbed out ODA.

[edit]

Additional Resources

[edit]

Troubleshooting

  • If you're running into authentication issues with the BIRT ODA Plugin, make sure of two things:
    • The username/password works when authenticating through the web interface.
    • The IP address of the machine using BIRT is added to the Logic WS Allowed IP List global property (logicws.allowed_ip_list).
  • If you're running the BIRT ODA through your development environment (as oposed to deploying as a plugin so that it always part of Eclipse), you can look at the console of the original Eclipse instance that was used to kick off the new Eclipse instance to see logging that has been added throughtout the ODA code.
Retrieved from "http://openmrs.org/wiki/BIRT_ODA_Plugin_Developers_Guide"