High-Level Specification

Overview

Out of the box, BIRT supports the following data sources: JDBC, flat file, scripted, web service, and XML. A developer can create a BIRT Open Data Access (ODA) plugin and abstract the data source so that underlying tables (columns) can be virtually any set of data that can be accessed via Java. The plugin engine is responsible for querying the data source for data and the tables/columns do not necessarily have to map to database tables/columns.

The OpenMRS ODA plugin is a data access tool used by the BIRT Report Engine and Report Designer. The plugin is comprised of a UI component and a query component. The UI component is used within the Eclipse BIRT Designer to allow OpenMRS users to more easily select the "tables" and "columns" that they want to use within their report without additional coding. The query component implements the ODA run-time extension and is the piece that is responsible for retrieving the data. OpenMRS will provide a web service to respond to the queries from the ODA.

In this project, a student will extend our existing BIRT ODA plugin, as well as the OpenMRS Logic REST API. The ODA plugin interfaces with OpenMRS through the Logic Service REST API to expose OpenMRS cohorts and tokens (similar to the way a JDBC driver would expose tables and columns). The main goals of the project are to improve the functionality and performance of the plugin, as well as to extend the REST API to integrate with the latest version of the Logic Service. The Logic Service REST API is also responsible for returning data in response to queries made by the ODA plugin.

Requirements

ODA Functionality

• CRITICAL - Add modifier support (FIRST, LAST) for each selected token
  • User should pick the tokens they want and then as a next step refine what the data set will look like by applying modifiers
• CRITICAL - Support extra columns: getting the date of each CD4 COUNT in one column and the actual number representing the CD4 COUNT in another column, both accessed from the same token
• HIGH - Allow users to search for specific tokens
• HIGH - Improve user interface
  • With new features added, the old one will become too crowded
• HIGH - Add ability to explode multi-value column
  • (i.e. CD4 COUNT) - done within the logic service
• MEDIUM - Persist data set definition on the openmrs server automatically
  • We want to be able to (at some point -- maybe report design file upload) suck the dataset definition out of the report design and save
• LOW - Make it easy to install the ODA plugin
  • Use the Help -> Software updates feature of Eclipse if possible.
• LOW - Persist/upload report design to the openmrs server automatically as a dataset definition in OpenMRS. This way we can share data set definitions with other reports.

Logic Service REST API

• CRITICAL - Add more token support to the logic service
  • This includes other Logic data sources like Program Workflow, Drug Orders
• CRITICAL - Needs to handle all methods available within the logic service API
  • Examples include: FIRST, LAST, LESS THAN, GREATER THAN
• HIGH - Constrain concept tokens that are returned to ODA plugin by whether they actually return data (i.e concept questions, not concept answers).

Performance

• MEDIUM - Cache tokens in BIRT for searching/filtering by tags

Deliverable

An improved ODA plugin and Logic Service REST API that can be used to define data sets and pull data (securely) from any instance of OpenMRS.

Implementation Details

ODA UI From GSOC '07

ODA UI From GSOC '08

The following are screenshots from the actual implementation.

Select Tokens

The user first selects a filter and then applies a token tag and chooses the desired tokens by moving the tokens from the left to the right box. The user also has the option of searching amongst these tokens:

Modify Tokens

The "Modify Tokens" screen displays the selected tokens that the user choose. Aggregrate information can be applied in front of each of the tokens (when using stacked and flat data styles). Each of these tokens can be selected and the various modifiers can be applied. The user clicks the checkbox to enable a particular modifier and can apply appropriate arguments. The user can also change the order that the modifiers are applied by using the up and down arrows to the right of the modifier box:

Split Tokens

The "Split Tokens" page allows the user to choose other information regarding their selected tokens besides just the value:

View OpenMRS Query

The "View OpenMRS Query" page shows the actual query that will be sent to the Logic Web Service and allows the user to toggle between the three available data sets: Most Recent (default), Stacked, and Flat:

Preview Results

Here's a sample data preview of the "most recent" data style:

GSOC '08 Accomplishments

• Implemented ODA Mock Logic Web Service (REST) to allow us to work on the ODA plugin without the unnecessary complexity of integration with the real Logic Web Service (REST) and Logic Service.
• Authored the BIRT ODA Plugin Developer's Guide.
• Modified the BIRT ODA Plugin Project Page, including an improved Overview, Project Requirements (with priority), Functional Requirements, and Mockups of ODA plugin screens.
• Implemented new token search functionality to allow user to search among available tokens.
• Implemented new data query functionality that gives the user ability to build complex Logic queries using the syntax: AGGREGATE X {TOKEN} OPERATOR OPERAND
• Refactored ODA plugin UI to make it more intuitive.
• Enhanced Logic Web Service to support all of the new ODA functionality like splitting tokens, adding aggregrates and modifiers, and providing three different data styles.
• Wrote test cases for the Logic Service and Logic Web Service projects.
• Debugged issues and submitted bugs with the Logic Service and Logic Web Service projects.
• Wrote HTTP Unit test cases for Logic REST API.
• Implemented splitting of Result object into separate columns: value, obsdate, encounter, etc.
• Merged trunk into logic branch in order to take advantage of new functionality in trunk (including report api changes).
• Created Javadocs for all Logic Web Service and ODA classes.
• Cached tokens for improved performance so that searching amongst tokens is done all on the client side.
• Created three simple reports that show off the three different data styles the ODA can generate.

Future Enhancements

• Research instantiating a new EvaluationContext and use that for the lifetime of a particular ODA connection. A static cohort definition or a search that takes no parameters will work fine with no evaluation context. If you have a search that takes parameters, you need to have an evaluation context, but you also have to put relevant parameter values into that context. The EvaluationContext allows for caching of searches, and for passing in parameter values.
• When doing a data preview in the data set wizard, limit the cohort by x patients so that the data preview is quicker.
• Research into doing a tree view for token selection. Each node would be a token tag and the leaves would be the tokens that fall under that tag.
• "Find tokens" should behave asynchronously (as you type in the search box, the token list should refresh)
• Parameterization of the dataset. Specifically, be able to add parameters for the modifier arguments.
• When the Logic Service supports more complicated queries, the precedence of the different modifiers will need to be considered. The existing modifier interface allows the user to indicate precedence by moving their modifiers up and down, but the actual query passed to the Logic Service may need to be altered to indicate precedence.
• Look into forcing the user to choose their data style upon initial creation and not be able to later change it. The first page could say: "How do you want to orient your data" and provide a sample of what the datasets will look like. This may save some headaches for those expecting the reports to continue working once they "transform" their datasets.
• Have the Logic Web Service provide the list of token aggregrates and modifiers instead of hard coding them in the ODA.

Resources

Related OpenMRS pages:

• BIRT ODA Plugin Developers Guide
• Last year's (2007) BIRT ODA Plugin Use Guide
• Logic Service Technical Overview

Blogs and Google docs:

• Rudd's Blog (GSOC 2007 OpenMRS ODA)
• Google doc from GSOC 2007
• Kevin's Blog (GSOC 2008 OpenMRS ODA)
• Google doc from GSOC 2008

For more information on Open Data Access, please see the Eclipse Data Tools Project:

• Data Tools Project
• ODA Overview (HTML) | (PDF)
• For Implementation Details

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

• SWT javadoc
• Understanding Layouts in SWT
• How to create a simple SWT application
• SWT Snippets