Building a FHIR Server on an Existing Application: Step-by-Step Guide

Robert Worden

rpworden@me.com

December 2013

Abstract: This guide describes the steps to build a FHIR server on any existing healthcare application which stores its data in a relational database. For those applications, you can build a read-only FHIR server without writing any procedural code, but by mapping the database onto FHIR resources, and writing a few other small configuration files.

For a server to update its data in response to http PUT requests, the same mappings can be used in conjunction with application business logic. This approach is supported by an Open Source mapping and transformation toolset. We assume you have read the accompanying white paper: ‘Building FHIR Servers on Existing Application Databases’ , which explains the overall mapping approach to building a FHIR server..

IntroductionThe paper explains the steps required to build a FHIR server on an existing application database, using mapping tools which can be downloaded from www.OpenMapSW.com . The steps in the process are as follows:

1. Download, install and configure the mapping tools:a. Download Eclipse Modelling Editionb. Download and install the mapping toolsc. Import the sample FHIR project into the Eclipse workspaced. Configure the mapping tools to connect to the application database

2. Map the Application Database onto FHIR resources:a. Make an empty Mapping setb. Capture the database structure in the mapping setc. Find or make the Ecore class model for a FHIR resourced. Make mappings from the database to a FHIR resourcee. Test the mappings

3. Write the other configuration files required:a. Create the server tableb. Create the resource tablec. Create the search tabled. Create resource narrative template filese. Create a header page to test the searches

4. Install the FHIR server under Tomcat:a. Create the folder structure for the servers

b. Populate the folders with jar files, mappings, and configuration files5. Test the FHIR server:

a. Run the supported FHIR searches and inspect the resultsb. Queries and round-trip tests

These steps are described in detail below. Some familiarity with the Open Source Eclipse Tooling framework is assumed, and the descriptions refer to the Mapping tool Eclipse Help files for further detail.

In the instructions which follow, file names and locations which you choose will be denoted in angle brackets, such as <base folder>.

Warning: the FHIR adaptation of these mapping tools is work in progress, and detailed instructions may change with new releases of the tools.

Download, Install and Configure the Mapping tools:

Download and Install the Eclipse Modelling EditionThe Eclipse modelling edition can be downloaded from http://www.eclipse.org/downloads/ . It is named ‘Eclipse Modelling Tools’ and is one of the largest Eclipse downloads – currently 292 MB.

It can be installed by unzipping the download to some location which will be called <base folder>. When you start Eclipse, you will be invited to create an Eclipse workspace, where Eclipse projects and Mapper projects will reside. Initially this workspace contains no projects.

Download and Install the Mapping ToolsThe mapping tools which you require to make a FHIR server can be downloaded from http://www.openmapsw.com/downloads/downloads.htm. The tools can be installed by unzipping the downloaded file into <base folder>/eclipse; the Mapper plugin files should then be found in <base folder>/eclipse/plugins.

Start Eclipse, and select the menu item Window >Open Perspective >Other. You should be offered the option ‘Mapper’. Select it to open the perspective (set of windows) which you will use for mapping projects to build FHIR servers; you have then successfully installed the mapping tools.

You should also download the FHIR Server Pack. When unzipped into a location which will be called <server pack>, this file contains three top-level folders:

a. FHIR: this is a sample of the folder structure you will need to install in the Tomcat webApps folder to run the FHIR server (you should be able to copy this folder into the webapps folder of a tomcat installation to get a working demo FHIR server)

b. OpenEyes : this is a sample of the kind of Mapper project used to create the mappings for a FHIR server.

c. com.openMap1.mapper.userConverters : this is an Eclipse plugin project, used to create one of the Mapper plugins, which you may need to modify and reinstall (in order to connect to your application database – see below)

Import the sample FHIR project into the Eclipse workspaceSelect the Eclipse menu option File > Import > Existing Projects into Workspace. In the resulting dialogue, navigate to the folder <server pack> where you unzipped the FHIR server pack. You will then be given the option to import two projects – FHIRProject, and com.openMap1.mapper.userConverters. Import both of them into the Eclipse workspace. You will see both projects in the left-hand Navigator view of Eclipse.

Configure the mapping tools to connect to the application databaseYou need the mapping tools to be able to connect by jdbc to the application database, both at design time (when you are using the Eclipse tools to create and test the mappings) and at run time (when the FHIR web service is running under Tomcat). The following way of doing so is probably not the neatest way, but it works.

We assume that:

A. The jdbc connect string, which is used to connect to the application database, has some distinctive first part, which enables client applications to know which jdbc driver class they need to load, in order to connect to the database.

B. You have a java jar file (which will be called <driver.jar> ) containing the jdbc driver class.

Proceed as follows:

1. In Eclipse choose the menu option File > New > Other>Plugin from existing jar archives.2. Make a new Eclipse plugin project, to be called <driverPlugin>, from the jar file <driver.jar>3. Open the java project com.openMap1.mapper.userConverters, and expand its folder

structure to show:

Double-click MANIFEST.MF and go to the ‘Dependencies’ tab:

Under ‘required plugins’, add the plugin project <driverPlugin> which you have just created from <driver.jar>.

Then open DBConnect.java (found in the folder shown above) with the Java editor, and scroll down the java source until you see the following code:

private static String[][] jdbcParam = { {"jdbc:odbc:","sun.jdbc.odbc.JdbcOdbcDriver","odbc"}, {"jdbc:jtds:sqlserver:","net.sourceforge.jtds.jdbc.Driver","SQL Server"}, {"jdbc:interbase:","interbase.interclient.Driver","Interbase"}, {"jdbc:oracle:thin:","oracle.jdbc.driver.OracleDriver","Oracle"}, {"jdbc:Cache:","com.intersys.jdbc.CacheDriver","InterSystems"}, {"jdbc:mysql:","com.mysql.jdbc.Driver","mySQL"}, {"jdbc:derby:","org.apache.derby.jdbc.ClientDriver","Derby"} };

This string array tells the mapping tools which jdbc driver needs to be loaded, depending on the start of the jdbc connect string. If the connect string prefix and driver class which you need are not in the String array jdbcParam, add them as an extra row in the array.

Then save all changes, build all projects (without errors), and deploy the two plugin projects <driverPlugin> and com.openMap1,mapper.userConverters. This is done by the Eclipse menu option File > Export > Deployable Plugins and Fragments. Deploy both plugins as archive (zip) files, and then install both plugins by unzipping them into your Eclipse installation. The ‘userConverters’ plugin will replace the previous version which you installed with the mapping tools.

You should now be able to connect the mapping tools to your application database, as described below.

When you are developing the FHIR server, you may wish not to work with the actual application database – even though you can do the development using read-only access to the database (e.g. maybe there is not a test version of the database for you to play with; maybe you will just not be given access to any database). In that case, you may need to take a data extract from that database, and an SQL schema of that database, to create your own local mini-copy of the database, e.g. on an open source DBMS, with small numbers of records for development purposes. These steps are not covered in this guide.

Map the Application Database onto FHIR resources:Making mappings between the application database structure and the class model for a FHIR resource is the most substantial task involved in creating a FHIR server. Mappings are declarative statements of how the database represents information in the FHIR resource. Being declarative, they are simpler to create, understand and debug than code; but there is a significant learning curve to learn how to make and test mappings.

There is extensive documentation about how to make and use mappings in the Eclipse Help files supplied with the mapping tools. To access this documentation, use Help> Help Contents and then look near the bottom of the list for the two mapper help folders:

These Help files are illustrated by large numbers of screenshots. Unfortunately, for some unknown reason, those screenshots do not show in recent versions of Eclipse. If anyone can help me fix this problem I shall be very grateful.

In spite of the outstanding clarity of these Help files, we would recommend that you either take a one-day mapping workshop from Open Mapping Software (www.OpenMapSW.com) or engage them to work with your staff in developing the first mappings, for skills transfer.

Make an Empty Mapping SetMappings define the relationship between a data structure (in this case, a relational database) and a UML logical model (in this case, the class model for a FHIR resource, expressed in Eclipse EMF Ecore). Before you can start making the mappings, therefore, you need to capture both the data structure and the class model. The mappings themselves (which bridge between the data structure and the class model) are captured in a file called a mapping set, distinguished by the file extension ‘.mapper’. You make an empty mapping set first; then capture the database structure in it; then connect it to the FHIR class model. Then you can start making mappings.

First make a new Mapper Project in which the mapping set, and other files needed for the FHIR server, will reside. Do this by File >New >Other>Mapper Project. The project will be named <NewProject>, and is created with the standard mapper project folder structure:

Now make a new mapping set in the ‘MappingSets’ folder of this project. Do this by File>New>Other>Mapping Set. The mapping set will be called <mappings>.mapper, and a dialogue asks you what to call it. Save it in the MappingSets folder of the new mapper project.

The new mapping set will show in this folder, and will also be displayed in the central editor pane of Eclipse, as follows:

Do the following:

Open the ‘Properties’ view in the bottom pane of the Eclipse window Select the second ‘mappings’ node of the mapping set. Using the dropdown menu, change the property ‘structure type’ to ‘RDBMS’ Edit the property ‘structure URL’ to be the jdbc connect string for the application database. Save these changes

Capture the database structure in a mapping setThe mapped structure must reflect the table structure of the application database. This table structure can be captured automatically in one of two ways:

1. You can read an SQL file which defines the table structure, if one is available.2. You can connect to the database by jdbc and extract its structure to the mapping set

The first method is described here. An icon for the new mapping set <mappings>.mapper appears in the MappingSets folder of the mapper project, where you put it, in the Navigator view of Eclipse. Right-click on this icon and select the menu option Mapper > Attach Structure Definition>XML Schema or RDBMS. There is then a file dialogue allowing you to select the SQL file for the database. Select it, and save the changes in the mapper file.

After you do this, the mapping set (as shown in the central editor pane) has a tree structure which mirrors the structure of the database. Expand the tree structure to show some of it:

Here:

The top ‘database’ node represents the whole database. The nodes beneath it (such as SILVER.NUMBER_IDS) each represent a table in the database

(the table name may ‘NUMBER_IDS’ may be preceded by a schema name such as ‘SILVER’ –you may need to remove the schema names by editing the node in the mapper editor)

Each ‘record’ element beneath a table name represents one record in the table. Each node beneath a ‘record’ node (such as ‘RM_PATIENT_NO’, etc.) represents one column

or field in the record.

So the structure of the database is captured as a tree. These are the nodes to which you will attach mappings, using the mapper editor, to state that those nodes represent features in a FHIR resource class model.

If the database structure has large numbers of tables which you know are completely irrelevant for the FHIR resource you will be mapping to, you can delete those table nodes in the mapper editor, and save the changes.

Find or make the Ecore class model for a FHIR resourceIt may be that the EMF Ecore class model for the FHIR resource you intend to map has already been made, and exists in the sample FHIR project which you imported into the workspace. Look inside the ‘ClassModels’ folder of this project:

The file name is the resource name, followed by ‘.ecore’. If the resource you need is there, copy this file and paste it into the ‘ClassModel’ folder of your new mapper project. If not, proceed as follows:

Open the Structures/Source sub-folder of the sample FHIR project, and you will see a long list of resource names:

Open the sub-folder for the resource you need, and find the file <resource>-spreadsheet.xml:

This is just reconnaissance, to ensure you know where to go in what follows.

Make another empty mapping set (which later you will throw away) by using File > New > Other > Mapping Set; call it <throwaway>.mapper. Right-click the icon for this mapping set, and choose the menu option Mapper>Attach Structure Definition > FHIR profile. When a dialogue asks you to ‘Select FHIR profile’ , go to the resource folder Structures/source/<resource> and select the file <resource>-spreadsheet.xml.

There may then be some warning messages for missing referenced resources; but the end result will be to create the Ecore model you want, called <resource>.ecore, in the ClassModel folder of the new project. You will need to refresh the project to see the new Ecore file. You can now delete <throwaway>.mapper.

Your may want to inspect this class model using an Eclipse editor. To do so, right-click the icon for the .ecore file, and choose the menu option Open with > Sample Ecore Model Editor. You will then see in the centre editor pane the package structure of this class model:

This package view of the resource class model will not be used much. More useful is a tree view of containment associations, which follows the XML tree structure of the FHIR resource. The mapper editor shows that view.

Before making mappings, you need to attach this class model to the mapping set <mappings>.mapper which has the database structure. To do this, right-click the icon for the mapping set, and choose the menu option Mapper > Attach Class Model. Select the resource class model. Then the right-hand ‘Mapped Class Model’ view will show a tree view of the resource, and any other resources it references, inside an AtomFeed class:

This view, which mirrors the XML structure of an AtomFeed containing the resource and any others it references, will always be visible when you are making mappings. The classes are shown in this view; their properties are visible in the lower pane in the ‘Attributes’ view; and their associations are visible in the ‘Associations’ view.

Make mappings from the database to a FHIR resourceThis work requires an understanding of what the mappings are, which will be unfamiliar to most people. What follows is a minimal summary. If you intend to make mappings, you are advised both

to read the mapper Eclipse Help files, and to seek training or support from Open Mapping Software Ltd.

Making mappings is an iterative, test-driven process, so you will rapidly cycle through a map-test-map-test process – making one or two mappings at a time, then immediately testing them to see their effects. It is slightly artificial, as in this guide, to describe mapping and testing in separate sub-sections; but we do so for clarity.

Mappings define the relationships between a data structure (in this case, a relational database) and a UML class model (in this case, the class model for some FHIR resources in an AtomFeed). Mappings state declaratively how each part of the data structure represents some feature of the class model.

There are three types of feature in the class model, which the data structure represents:

1. Objects (instances of the classes)2. Properties of objects3. Associations between objects.

Therefore there are three types of mapping, to define how the database represents these features. There are object mappings, property mappings, and association mappings. Most people are not familiar with association mappings.

As relational databases typically represent associations by matching prime keys and foreign keys in different tables, you will need to learn to make association mappings which express this.

To make mappings, first double-click on the mapping set <mappings>.mapper. This brings up the mapper editor, which shows the data structure tree in the central pane of Eclipse, and the class model in the right–hand class model view:

The procedure for making any mapping is as follows:

In the class model view, select the class involved in the mapping (or one of the two classes involved, for an association mapping)

In the central editor view, right-click the node of the data structure which is being mapped This reveals a small menu of mapping options. Choose one. The new mapping should now show in the central pane, attached to the node of the data

structure If necessary, edit the properties of the mapping in the lower ‘properties’ view Save the changes in the mapping file. Test the new mapping (see below).

We will follow though the first two or three steps of mapping a Patient resource. For a FHIR search, all resources are returned in an AtomFeed. The top ‘database’ node can represent an object of the class AtomFeed. To express this in mappings:

In the class model view, select the AtomFeed class In the central editor view, right-click the ‘database’ node and choose the menu option ‘map

to class AtomFeed’ The new object mapping shows in the central pane (as below) In this case, there is no need to edit the properties of the mapping.

Next you need to decide how objects of the main resource class, Patient, are represented. Usually there is one table in the database, in which each record represents one patient. In this case, the table is the ‘PATIENTS’ table. Proceed as follows:

In the class model view, select the Patient class. In the central editor view, right-click the ‘record’ node below the ‘PATIENTS’ table node. Select the menu option ‘Make chain mapping to Patient’

Making a chain mapping means ‘make an object mapping, and any necessary association mappings to link the object to its containing class, which has already been mapped’. The result is to make both an object mapping (to class Patient) and an association mapping (to the association AtomFeed.patient ).

The mappings mean: ‘every record in the PATIENTS table represents one Patient object , and the association from the AtomFeed object to the Patient object’. The mappings look like:

Next you need to start making property mappings, to show how the database represents properties of the Patient. For simplicity, we choose the property ‘birthdate’, as it is a direct property of the Patient class, rather than being a property of any contained component class or datatype class. To map the property ‘birthdate’, proceed as follows:

In the class model view, select the ‘Patient’ class In the central editor view, right-click the node ‘DATE_OF_BIRTH’ (which denotes that column

of any record in the ‘PATIENTS’ table) Select the menu item Map Property > Patient:birthdate The mapping will appear:

In this case, there is no need for any data format conversion between the database format and the FHIR format. (Mapped nodes are coloured green only after you have closed and reopened the mapping set. )

Carry on like this, mapping all the classes you can in the Patient resource class model, their association, and their properties. This process is not time-consuming, but requires a clear understanding of what the mappings mean and what you are doing. There are many aspects of mapping which we have not touched on here, such as: conditional mappings, fixed property values, data format conversions, and complex association mappings. All these are addressed in the mapper Help files.

In practice, each time you make one, two or three mappings, you will want to test them before going further. This is covered next.

Test the mappingsMappings are intended to enable translation of information from the data structure format (here, the database format) to the class model format (here, the FHIR Patient class model). Mappings are tested by making one of these translations, and examining the results by eye, to ensure the mappings have done what you intended.

The mapping tools provide several ways to test mappings, and we will describe just one of them here. This is to use an object-oriented query tool, provided with the mapping tools. You write simple

queries in the query language, run them against the database (using the mappings to get data from the database and convert it), and inspect the results.

Several examples of the kinds of query you can write are provided in the ‘Query’ folder of the sample FHIR mapper project.

Open this folder and double-click some icon with extension ‘query’ to see what the query looks like. A typical query is:

select Patient.fhir_id Patient.birthDate Patient.name.given.value Patient.name.family.value

You will see that this query is written entirely in terms of the FHIR patient class model – nothing in it depends on the database or the mappings. It asks to display certain properties of the Patient class, or of component classes related to it by associations. The association names are the same as the tag names in FHIR XML.

Queries can also have ‘where’ conditions to select only certain records in the database. The query above has no conditions, so will return all patients represented in the database. It is therefore only suitable for running against a small ‘toy’ database. When you do this (right-click the query text and select ‘run query’), using some small toy database, the query result appears in the lower Query Result view and looks like:

You will see all the properties that have been requested in the query (with some strange column headings – to be fixed). These values have been got from the database using the mappings. Any errors in the mappings will lead to missing data values, missing rows, or crazy values. Running these queries is a sensitive way of testing mappings.

If you are using some real or test database with many thousands of records, queries need to have ‘where’ conditions to limit the number of records returned. For instance:

select Patient.fhir_id Patient.birthDate where Patient.fhir_id = '1'

will return at most one row, because there can be only one patient with a given ‘fhir_id’. You may have mapped the property ‘fhir_id’ to some database internal identifier, which is an indexed primary key or foreign key in most tables; so the SQL queries (which are generated automatically from this query and are run against the database to get the records) will run efficiently.

We have not described here how to connect a query to one or more mapped databases. That is addressed in the mapper help files.

Write the other Configuration Files required:

Create the server tableThe server table is a small csv file ‘servers.csv’ which defines which FHIR servers are provided by this installation – because one web service can be connected to several different application databases by jdbc, to provide a FHIR server for each of them.

You may choose to create this csv file directly using a text editor – or, to see its columns clearly, you may chose to edit an Excel file and then save it as a csv file. We will use this approach for illustration.

The form of the server table is:

For each application database, you need to define:

The name of the FHIR server that it will support Its jdbc connect string (URL) A username and password to connect to it Possibly, a schema name to connect to it

Since the FHIR server stores the user name and password in order to access each database, there need to be adequate access control to the FHIR server itself.

Create the resource tableThe resource table is a small csv file. ‘resources.csv’ which defines which resources are supported by which FHIR server. Its form is shown here:

For each resource supported by a FHIR server, you need to define:

The server name The resource name The Mapper project in which you defined the mappings of the database onto the resource

class model (the whole mapper project folder is included in the Tomcat .war file) The location of the resource mapping set inside the ‘MappingSets’ folder of the mapper

project. The name of a narrative template file for the resource, which will define the form and

content of an auto-generated resource narrative (see below)

Create the search tableThe search table is a small csv file ‘searches.csv’ which defines which FHIR searches are supported on each resource. A typical example is:

For each supported search, you need to define:

The server The resource ‘LHS’ is the form of the left-hand-side of the search condition in the search URL ‘type’ is the type of search, as in the FHIR specification for searches ‘paths’ is a semicolon-separated list of the paths in the FHIR resource class model (or XML)

which need to be traversed in order to test the query condition. For ‘token’ type searches there are two paths.

‘conditions’ is the set of query conditions supported – equality, inequality, etc. ‘solo’ indicates whether a query condition can be used on its own, without other query

conditions. For instance, for any large patient database, queries on gender should have solo = ‘no’ as they will deliver half the database as a result.

The FHIR server then supports searches on any ‘AND’ combination of these conditions, as long as there is at least one condition with solo=’yes’.

For any such search, the FHIR server uses the mappings to automatically convert the search into an SQL query on the database, generating SQL conditions to narrow the result set as much as possible. The appropriate indexes in the database will be applied automatically by the DBMS SQL query strategy, to give efficient searches when tight conditions are supplied.

Create resource narrative template filesA resource narrative template file is a small xhtml-like XML file which defines the form of an automatically generated narrative for each resource, and defines how that form will be filled in by values taken from the resource. A typical example is:

<?xml version="1.0" encoding="UTF-8"?> <div> <p>From silver server</p> <table border="1"> <tbody> <tr repeat="name"> <td>Name</td> <td>$ prefix.value + given.value + family.value</td> </tr> <tr> <td>Date of Birth</td> <td>$ birthDate</td> </tr> <tr> <td>Gender</td> <td>$ gender.coding.code</td> </tr> <tr> <td>Address</td> <td>$,address.line.value + address.city + address.state + address.zip</td> </tr> <tr repeat="identifier"> <td>Id</td> <td>$:system + value</td> </tr> </tbody> </table> <p>.</p> </div>

This is a skeleton of the narrative xhtml, with instructions for how to fill in the values. An instruction is any text value of an element starting in ‘$’. Each instruction is a path in the FHIR class model for the resource, or a set of such paths, with the values at those paths to be concatenated. The separator for concatenation is defined immediately after the ‘$’. Repetitions of xhtml subtrees are defined by the ‘repeat’ attribute.

Create a header page to test the searchesYou may wish, when testing the FHIR server, to have a convenient web page with links for some of the FHIR searches to be tested, rather than typing in those paths on a browser.

Install the FHIR Server under Tomcat:

Create the folder structure for the server farmThe FHIR server pack contains a complete working web application folder, which can be installed in any Tomcat installation to produce a working demo of the two FHIR servers, silver and bronze (they use local toy databases which are managed by embedded Apache Derby, and are stored within the folder).

This folder structure is a model for the folder structure you need to install.

The folder structure is:

FHIR (outer folder; may be renamed)mappings

[mapper project folders containing resource mapping sets]narratives

[narrative template files]serviceDefs

servers.csvresources.csvsearches.csv

WEB-INFlib

[all required jar files]web.xml

testPage.html

Populate the folders with jar files, mappings, and configuration files

A typical set of the required jar files is:

Populate the other sub-folders as above.

Test the FHIR server:

Run the supported FHIR searches and inspect the resultsUse your test web page to issue http GETs to the server and inspect the results. When doing so, be aware that search results are returned as AtomFeeds. Some browsers recognise an AtomFeed and try to do clever things which you do not want them to do. Google Chrome is quite good in this respect, as is the browser supplied in Eclipse.

Even so, the browser is likely to show only the narrative of returned resources. To view the full resource XML, use the ‘Save Target as..’ option of the browser and inspect the XML in some other way; or use a browser option to inspect the source.

Queries and round-trip testsYou can use the mapping tools to run queries against the database, using the FHIR mappings, to run the same queries against resources in FHIR XML, or to run round-trip translation tests between FHIR XML and database-like XML files. See the mapper help files for descriptions of how to do these things.

All these provide extra tests of the mappings which drive the server. Get the mappings right, and the server will operate correctly.