Denodo HL7 FHIR Service - User Manual

Last modified on: 09 Jul 2021

Please note: This software is currently in BETA.

Overview

FHIR® (Fast Healthcare Interoperability Resources) is a standard describing data formats and elements, known as resources, and an application programming interface (API) for health care data exchange. The standard was created by the HL7® (Health Level Seven International) health-care standards organization.

The Denodo HL7® FHIR® component consists of:

Denodo Virtual DataPort templates: denodo_hl7_fhir_templates.vql script that defines interfaces for some HL7 FHIR resources.

Denodo web service application: web service that reads the interface views created by the templates and translates that into the HL7 FHIR standard web service format (JSON).

Note: “FHIR” and “HL7” are registered trademarks of HL7 http://www.hl7.org

Installation and Configuration

The Denodo HL7 FHIR Service is distributed as a DenodoConnect that can be downloaded from the Support site.

This Denodo HL7 FHIR Service distribution consists of:

Command-line executable scripts for Windows and Linux (/bin folder)

Configuration files: application.properties and log4j2.xml(/config folder)

Java libraries (/lib folder)

Denodo HL7 FHIR Service application jar: denodo-hl7fhir-service-<version>-jar

Denodo driver jar: denodo-vdp-jdbcdriver-dist-<version>-full.jar

If you need to use a JDBC driver corresponding to a Denodo update different to the one that is distributed, you only need to replace this jar.

Virtual DataPort templates (/vql folder)

For installing it just download the .zip file and extract the service into the desired folder.

In order to run it, you need at least Java 8 and the environment variables JAVA_HOME and PATH correctly configured.

After running the script in the /bin folder, you can use the Denodo HL7 FHIR Service at: http://localhost:8080/

Denodo HL7 FHIR Service running

Configuration

The Denodo HL7 FHIR Service allows you to configure the following properties at the resources/application.properties file:

spring.datasource.driver-class-name=com.denodo.vdp.jdbc.Driver

spring.datasource.url=jdbc:vdb://{VDP_HOSTNAME}:{VDP_PORT}/{VDP_DATABASE}

spring.datasource.username={DATASOURCE_USERNAME}

spring.datasource.password={DATASOURCE_PASSWORD}

spring.datasource.driver-class-name: The Virtual DataPort driver.

spring.datasource.url: The database URI to access Denodo from the HL7 FHIR Service. Default VDP database is hl7_fhir (the one created by importing the templates script).

spring.datasource.username: Username to access the VDP database.

spring.datasource.password: Password to access the VDP database.

Importing templates

The denodo_hl7_fhir_templates.vql script file contains interfaces for each one of the following HL7 FHIR resources:

AllergyIntolerance
CarePlan
Condition
Device
DiagnosticReport
DocumentReference
Goal
Immunization
MedicationRequest
MedicationStatement
Observation
Patient
PractitionerRole
Procedure
Provenance

Please note: importing this script will create a database called hl7_fhir in your Virtual DataPort installation, and will drop any existing database previously existing with that exact name.

You only have to import the the denodo_hl7_fhir_templates.vql file using the Import option of the VDP Administration Tool:

Import option in VDP

Import wizard in VDP

Refresh

After the import operation finishes, refresh the Server Explorer by selecting File > Refresh and you will be able to see the interfaces:

Interfaces for HL7 FHIR resources

The hl7_fhir database contains two folders:

common interfaces: most of the interfaces of this folder represent complex types used by some HL7 FHIR resources fields.

main resources: this folder contains the interfaces which represent the HL7 FHIR resources.

Note that all the interfaces are unimplemented, you must set the implementation of each one using your own views.

Implement a FHIR Resource interface

Interface views are a special type of derived views that consist only of a definition of fields and a reference to another view. You have to set the implementation view in order the queries work properly. The implementation view must have the same number of fields and with the same type.

The denodo_hl7_fhir_templates.vql script defines also some new data types:

registerdatetime: a register with a value of type datetime

registerstring: a register with a value of type string

registertime: a register with a value of type time

arraydatetime: an array of registerdatetime registers

arraystring: an array of registerstring registers

arraytime: an array of registertime registers

Make sure your implementation views make use of these types when necessary.

In order to set the implementation of an interface you just need to edit the interface, select the Implementation tab and drag and drop the implementation view to this window.

Set implementation view of Patient interface

Endpoint Operations

The Denodo HL7 FHIR Service implements the read by id and search operations of HL7 FHIR RESTful API, both without parameters, for the following resources:

AllergyIntolerance
CarePlan
Condition
Device
DiagnosticReport
DocumentReference
Goal
Immunization
MedicationRequest
MedicationStatement
Observation
Patient
PractitionerRole
Procedure
Provenance

read Operation

This operation follows the syntax: http://localhost:8080/<resource_name>/<resource_id>.

For example, if we want to see the details of a care plan with id is “colonoscopy”, the url to be invoque will be: http://localhost/CarePlan/colonoscopy

read CarePlan HL7 FHIR resource by id

search Operation

This operation follows the syntax: http://localhost:8080/<resource_name>.

The Denodo HL7 FHIR server implements only this operation, without search parameters. It really works as a list operation.

For example, if we want to list all the patients of our database, the url to be invoque will be: http://localhost/Patient

search all Patients HL7 FHIR resource