Reporting Framework Integration Project

Background

OpenMRS reporting is much more of a chore than it should be. Data sets have to be built and exported, then read in statically by a reporting framework. There needs to be a better way to integrate with open source reporting frameworks, such as Eclipse BIRT, that allows users to access an OpenMRS implementation directly, without having to export data sets.

Goals

• To build a working ODA driver to be used within Eclipse BIRT report designer that allows direct access to an OpenMRS installation.
• To build up the Logic Web Service so that the ODA driver can access data, implemented via an OpenMRS REST Module.

Design

Definitions

BIRT

BIRT refers to the Eclipse Business Intelligence and Reporting Tool framework, which provides runtime design and report APIs that developers can use to perform reporting use cases. The BIRT framework also includes a WYSIWYG report designer as well as access to an implementation of the report engine through a convenient web interface.

ODA

ODA refers to the Open Data Access framework, which provides a common way for applications to access data from custom data sources (as well as standard sources, e.g. JDBC, CSV, XML). The Open Data Access framework provides a level of abstraction for data retrieval, allowing a user to access different types of data sources through the same interface, despite the original format of the data.

ODA driver

An ODA driver is a plugin that implements the Open Data Access plugin API, allowing Eclipse BIRT to access the custom data source. It includes support for establishing a connection, accessing meta-data, and executing queries to retrieve data.

Specifications

• For specifics on how the Logic Web Service works, see Logic Web Service User Guide.

• For specifics on how the BIRT ODA Plugin works, see BIRT ODA Plugin User Guide.

• The Logic Web Service should not be designed around BIRT specifically, but rather designed as purely a web-accessible portal to the Logic Service. Other reporting frameworks and other applications should be able to interact with it as well.

• The ODA User Interface will query the user for the URL to their OpenMRS installation, their username, and their password when setting up a data source.

• The ODA User Interface sets up a data set of the data source by querying the user for a patient filter (a drop-down list), and a list of tokens. Tokens are selected by token tag and moved into a "selected tokens" box.

Logic Web Service Code Overview

LogicWSUtil

Mainly serves as a place to deal with authentication to OpenMRS.

Important methods: allowUser(), allowRemoteAddress()

RestServlet

The HTTP Servlet that extends javax.servlet.http.HttpServlet. It takes requests and authenticates them, then passes them onto the corresponding Resource, each representing an api function.

Important methods: handleRequest(), passesAuthentication()

RestResource

Represents a resource and api function. Consists of one main method that each resource must implement.

Important methods: handleRequest()

FilterResource

Represents the resource of getFilters. Gets a list of filters from the CohortService and ReportService and returns them in an XML format.

Important methods: handleRequest()

TokenTagResource

Represents the resource of getTokenTags. Gets a list of token tags from the LogicService and returns them in an XML format.

Important methods: handleRequest()

TokenResource

Represents the resource of getTokens. Gets a list of tokens for a specific tag if provided with a tag=TAG argument, or gets all tokens if provided with no argument. Returns these in an XML format.

Important methods: handleRequest(), getDataType()

DataResource

Represents the resource of getData. Sends back data generated from the LogicService in a table-like XML format. Gives a list of columns, and then the row data for each of these columns. In place of row data, an error may be generated if the user doesn't possess the right privileges. Accepts parameters of filter, filterType, and a number of token arguments.

Important methods: handleRequest()

Others

Base64, LogicWebServiceActivator, LogicWSAdministrationAdvisor, AdminList: Base64 is a public domain implementation of Base64 encoding used for HTTP BASIC authentication parsing. The others are classes that allow this to work as a plugin to OpenMRS.

BIRT ODA Plugin Code Overview

Connection

Represents a connection to the OpenMRS server that can be opened and closed. A connection must be open for any work to happen inside the ODA driver.

Important methods: open(Properties), setURLConn(URL), checkProperties(), canAccessAPI()

DataSetMetaData

Represents some metadata about the ODA driver and what it supports (e.g., extra parameters).

Important methods: none

Query

Represents a query to the Logic Web Service. Only represents the actual query, not the results of said query. A query is represented as a String, and nothing else. A query must be first prepared, then it can be executed. executeQuery() is never called until prepare() is.

Important methods: prepare(String queryText), executeQuery()

ResultSet

Represents a set of results organized in table format. Results will be read one row at a time, in order. Old rows are not accessed again, so that once next() is called to move to the next row, the old row need not be available. Columns within the current row can be accessed in any order.

Important methods: next(), getString(int columnNum), getString(String columnName)

ResultSetMetaData

Represents metadata associated with the columns in a result set (such as number of columns, column names, types, etc.)

Important methods: getColumnType()

Filter

Represents a patient filter. Can be either static (an org.openmrs.Cohort) or dynamic (an org.openmrs.reporting.PatientFilter).

Important methods: constructor(String, Integer, String)

Token

Represents a Logic Service token. Supports precision (the maximum number of decimal digits) and scale (the maximum number of digits to the right of the decimal point).

Important methods: constructor(String, String, Integer, Integer)

XMLParser

A class that exists simply for the OpenMRS Logic Web Service. All connections to the Logic Web Service go through this class. It creates URL connections, and parses the XML using the DOM tools.

Important methods: getFilters(), getFilterMap(), getTokenTags(), getTokens(), getTokenMap(), getData(), getStream(), getCall()

CustomDataSetWizardPage

Represents the custom data set definition page where the user defines the filter and tokens they wish to use. Creates objects to display and the functions that are used when they are interacted with.

Important methods: createPageControl(), populateFilters(), populateTokenTags(), populateColumns(), addColumns(), removeColumns(), initializeControl(), validateData(), savePage()

Others

Activator, Driver, Base64: Each Activator class exists to make the plugins function as Eclipse plugins. Driver is only for the link to the ODA framework, and also for a possible implementation of logging. Base64 is a public domain implementation of Base64 encoding used for HTTP BASIC authentication to the Logic Web Service.

Important methods: none

Plans for the Future

• Constrain concept tokens by whether they actually return data (i.e concept questions, not concept answers)
• Token search
• Cache tokens in BIRT for searching/filtering by tags
• Improve user interface -- with new features added, the old one will become too crowded
• Add more token support to the logic service
• 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
• Add ability to explode multi-value column (i.e. CD4 COUNT) - done within the logic server
• Logic web service needs to handle all methods available within the logic service API (FIRST, LAST, LESS THAN, GREATER THAN, etc).
• the next oda driver should support changing from the default datatype of a token (e.g., numeric -> text so we get "Five" instead of 5)
• 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
• Persist/upload report design to the openmrs server automatically
• Persist data set definition on the openmrs server automatically

GSoC 2007 Schedule

Week 1

Installed/deployed OpenMRS on both my linux box and Powerbook running OS X. Started setting up an Eclipse environment for development.

Week 2

Tried to find API documentation and other literature on ODA plugins. Played with an existing ODA plugin (for flat files like CSV) to start learning how the API works. Started learning about OpenMRS modules as well.

Weeks 3

Created a bare bones ODA driver that would be the base of the eventual plugin, and documented how to do so. Started learning how an ODA driver works, and documented the lifecycle of a driver and its functions. Committed a small change to the REST Module to make it work.

Week 4-5

Implemented much of the runtime part of the driver. Continued to develop specs for the driver and UI, as well as the functionality of the REST Module.

Week 6

Implemented the interface to the REST Module within the runtime driver, and finished the rest of the runtime driver, creating a functional driver, but lacking a UI.

Week 7

Started work on updating documentation, and started work on the UI, going through code for other ODA UIs, and reading articles about it.

Weeks 8-9

Implemented the first version of the User Interface.

Week 9-11

Implemented the functionality needed within the Logic Web Service, making several changes to the XML and way the Logic Web Service works with the Logic Service. Negotiated features such as token tags and access to datatypes. Finalized how to work with cohorts for now. Finished documentation.

Rudd's Blog

<xfeeds titlecolour="#B0C4DE" contentcolour="#eeeeee" feedlimit="5" totallimit="10"> http://ruddzw.wordpress.com/feed/ </xfeeds>