This document describes what (features) the integration of ORTHANC will bring into OpenHospital and how the integrate is going to be made.

Why the integration

The integration is requested by OpenHospital users, for instance a Hospital located in Ethiopia. ORTHANC is a free, open source and lightweight DICOM server for medical imaging. Actually, OpenHospital disposes, in the Desktop version, some basic features to explore DICOM images. The integration of ORTHANC is a better alternative, as it brings more features and could prevent us from redeveloping an entire radiology module in the web version.

Prerequisites

This integration will be the first one, so we can think together about a more suitable way to introduce integrations into OpenHospital. By this I mean that, from the outset, we can define a standard for integrating other software into OpenHospital. That said, it’s not a necessary step. We could start by just integrating one or two softwares and with the experience we’ll be gaining in the process, we'll be able to get a clearer idea of what we're up against.

In addition to this, as stated in this meeting summary, there are some refactoring and some new features we have to develop in preparation of the integration.

Features to develop

For the first version, in the radiology activities of a patient, we’re going to add the following features:

• Display some metrics (number of studies, the date of last study) about patient past studies.

• Show the list of patient past studies with a link to view each study on ORTHANC explorer.

• For each study, show the list of series providing a link to view each series on ORTHANC explorer. For each study, show the list of related instance providing a link to view each instance on ORTHANC explorer.

The UI Mockup shows how the integration will looks like.

Open

OH ORTHANC INTEGRATION

Main flow

As ORTHANC and OpenHospital don’t rely on the same database of patients, we’ll need a kind of synchronization between them to ensure that, for a given patient in OpenHospital, we’re able to retrieve information about his radiographies from ORTHANC.

One solution is to consider OpenHospital as the “main software” which provides patient unique identifier and that identifier will be referenced in the DICOM metadata (using the property patientID available in DICOM file metadata). That way, we’ll be able to retrieve radiology information for a specific patient.

We assume all patient data are added to DICOM images as metadata at the time an X-ray is taken, so the radiologist must provide the “patient ID” of patient stored in OpenHospital as metadata of the DICOM file.

The doctor flow

Open

Doctor who's able to view radiologies can find them in the patient section, as any other data related to patients (visits, therapies…). He can explore patient’s studies, series and instances.

For each series, he can click a button for going to an ORTHANC viewer;

For each instance he can view the preview image and click to a link to ORTHANC.

Technical specifications

ORTHANC leverages a REST API that allows a full access (read and write) to all DICOM resources available on the server. It also integrates a powerful plugin system which can be used to extend and customize the software.

As ORTHANC already provide a REST API to interact with DICOM resources, we will just consume those API to deliver features we need within OpenHospital. The main challenge will be about consuming those APIs securely.

ORTHANC is released, by default, with basic authentication and no access control, but allow users to customize the authentication and the authorization to use their own logic. To have a full access to DICOM resources, from OpenHospital, we’ll need to know which authentication mechanism is implemented in the ORTHANC installation, to be able to authenticate requests. For the authorization, the simpler way is to manage access control in OpenHospital, as Orthanc doesn’t have a default one.

Authentication

We could assume, or define as a prerequisite, that the ORTHANC installation will be using a basic authentication, and implement the authentication mechanism based on the basic authentication. Or instead, we could implement a generic authentication mechanism which could work, no matter which authentication mechanism is implemented in the ORTHANC installation. For both options, we’ll need to have a kind of “OpenHospital user” in the ORTHANC with all privileges, and we will use the credentials of this user to authenticate requests.

Option 1: Implement a basic authentication (Adopted)

The first option we have is to implement a basic authentication. To do this, we will need to store the OH user's credentials (from ORTHANC) in the OpenHospital settings, and use them to authenticate requests we will be sending to the ORTHANC REST API server.

Basically, we will need to add the following settings:

• ORTHANC_BASE_URL used to define the base URL of the REST API resources.

• ORTHANC_USERNAME used to store the username of “OpenHospital user“ on the ORTHANC installation.

• ORTHANC_PASSWORD used to store the password of “OpenHospital user“ on the ORTHANC installation.

• ORTHANC_EXPLORER_URL used to store the URL of the explorer.

Option 2: Implement a generic authentication mechanism

The second option consists of developing an authentication mechanism which takes into consideration many types of authentication, like Basic Authentication, OAuth, …

In addition to the new settings mentioned above, we’ll need to add:

• ORTHANC_AUTH_METHOD used to saved the authentication method. It could be: BASIC, JWT, …

• ORTHANC_AUTH_URL used to stored the authentication URL

We’ll need to implement the logic for every authentication method.

Authorization

For the authorization the simpler and best option is to authorize request in OpenHospital. For that we have to add new privileges (permissions) related to the Radiology module. When a user from OpenHospital try to use a radiology feature, we check if he is authorized and then we make to the ORTHANC REST API.

The exhausting list of new permissions to introduce will be provided later, during the implementation.

Architecture

The UI will not call directly ORTHANC APIs, it will follow the same flow by calling OpenHospital API, then OpenHospital API will send the request to ORTHANC and provide the UI with result.

The image below shows two architectures. The first one follows the assumption we made, i.e. ORTHANC installation will be using Basic Authentication.

The second architecture uses a third-party solution to encapsulate the integration rules, such as the link between OpenHospital patients and ORTHANC patients, the authentication method, etc.

API

This is the mapping of OpenHospital API to ORTHANC API:

• GET /radiology/{patiendId}/studies → GET /patients/{id}/studies - returns studies related to a patient

• GET /radiology/studies/{studyId}/series → GET /sudies/{id}/series - returns series related to a study

• GET /radiology/series/{serieId}/instances - GET /series/{id}/instaces - returns instances relate to a serie

• GET /radiology/instances/{instanceId}/preview - GET /instances/{id}/render Get an instance preview (JPEG image)