OpenMRS Radiology Module is a module adding capabilities of a Radiology Information System (RIS) onto the open source enterprise electronic medical record system OpenMRS

Project status
OpenMRS Radiology Module is not yet officially released to the OpenMRS modules. The API and UI are not yet stable and subject to frequent changes.

1. Overview

The most important URLs are

Host and Port configuration

This guide assumes that your

Please adjust the URLs accordingly.

2. Installation

To setup OpenMRS with the OpenMRS Radiology Module you have to options

2.1. "Manual"

Follow installation instructions of

and execute all the necessary steps yourself.

2.2. Docker

Follow instructions at

which will do most of the steps for you.

3. Deployment

Deployment of the Radiology Module consists of deploying all necessary dependencies and then the module itself into OpenMRS.

You need to login to your OpenMRS instance as administrative user and go to the Administration, Manage Modules page and add the modules shown in the following sections.

3.1. Module Dependencies

The Radiology Module currently depends on the

  1. OpenMRS Webservices REST module - version 2.15-SNAPSHOT

  2. OpenMRS Legacy UI module - version 0.3.1

You can get the Legacy UI at OpenMRS modules. The Webservices REST with the feature needed for the Radiology Module have not been released yet, you either have to compile it yourself or just until a release has been made you can get it at https://github.com/teleivo/tmp-dependencies-openmrs-module-radiology.

3.2. Module Package

Since there has not been an official release yet you need to compile the Radiology Module yourself.

Please follow the instructions at https://github.com/openmrs/openmrs-module-radiology.

4. Configuration

At this point I expect you to have OpenMRS 2.0 installed and OpenMRS Radiology Module deployed.

You still need to do a little configuration of the OpenMRS Radiology Module.

4.1. OpenMRS Radiology Module

Follow the steps as shown to finish configuration of the OpenMRS Radiology Module.

4.1.1. Radiology Concept Classes

Before you can start to enter radiology orders you need to define the orderable procedures within your facility.

To do that you need to go to the Administration, Settings page and select "Radiology" in the menu on the left side.

The setting that needs to be specified is called "Radiology Concept Classes" as shown below

radiology settings

You can enter any list of OpenMRS concept class UUIDs.

Its easy to find these UUIDs via "Manage Concept Classes" link in the admin page

admin concept classes

Click on any concept class you whish to configure, for example "Test"

concept test

And copy the UUID you see greyed out at the bottom

concept test uuid

Paste this concept class UUIDs into the "Radiology Concept Classes" settings field and hit "Save".

5. Requirements

This documents shall serve as a requirement for ongoing development and a documentation of how things are implemented by the Radiology Module.

The Radiology Module aims to adhere to best practices defined by the IHE Radiology Technical Framework.

The Radiology Module shall partially implement the following integration profiles:

  • Radiology Scheduled Workflow (SWF)

the word partially is used above since Radiology Module will not perform all transactions required by the IHE Radiology Technical Framework.

The Radiology Module acts as the following actors:

  • Order Placer (OP)

  • Department System Scheduler/Order Filler (DSS/OF)

the module does not provide DICOM Modality Worklist services as attributed to actor 'Department System Scheduler/Order Filler' by IHE, this service has to be provided by an external system (like a PACS, as for example done by dcm4chee).

The Radiology Module implements or acts in the following transactions:

  • RAD-2 Placer Order Management

  • RAD-3 Filler Order Management

  • RAD-4 Procedure Scheduled

  • RAD-13 Procedure Update

since the Radiology Module acts as 'Order Placer' and 'Department System Scheduler/Order Filler' transaction 'RAD-2' and 'RAD-3' are basically merged. There is no need for the 'DSS/OF' to update/notify the 'OP' on creation, revision, cancellation of orders, since these actions will always originate at the 'OP'.

5.1. Terms

The following explains the meaning of terms used in this document to establish common ground

5.1.1. Radiology Order

DEFINITION

A radiology order is a radiological test ordered by a referring physician for a specific patient.

CONTEXT

The radiology order is sent to the radiology department for execution.

COMPONENTS

Its main components are

  • patient

  • urgency

  • start date

  • orderable (what kind of test should be done? i.e. "CT of the Abdomen" or "R/O Pulmonary Embolism")

  • orderer (referring physician or other doctor requesting the order)

  • order reason free text or from a standardized code scheme

  • corresponding requested procedure (created by the radiology department)

SPECIAL TERMS

SCHEDULED: A radiology order is 'scheduled' if its corresponding requested procedure is 'scheduled'.

IN PROGRESS: A radiology order is 'in progress' if its corresponding requested procedure is 'in progress'.

READY FOR REPORTING: A radiology order is 'ready for reporting' if its corresponding requested procedure is 'ready for reporting'.

COMPLETED: A radiology order is 'completed' if its corresponding requested procedure is 'completed'.

5.1.2. Requested Procedure

DEFINITION

A requested procedure is a unit of work which results in a radiology report.

CONTEXT

The requested procedure follows an incoming radiology order. The radiology department decides how the radiology order is going to be exectued in terms of radiological procedures. Each requested procedure will get one radiology report.

COMPONENTS

Its main components are

  • one corresponding radiology order

  • requested procedure (i.e. "CT ABDOMEN WITH IV CONTRAST"; usually coming from a standardized code scheme such as SNOMED CT or RadLex Playbook)

  • one or more scheduled procedures which drill down the requested procedure into schedulable/executable steps

  • one or more performed procedures

  • one radiology study

  • one radiology report

SPECIAL TERMS

SCHEDULED: A requested procedure is 'scheduled' if all of its scheduled procedures are 'scheduled'.

IN PROGRESS: A requested procedure is 'in progress' if it has at least one performed procedure.

READY FOR REPORTING: A requested procedure is 'ready for reporting' if all of its scheduled procedures are 'completed'; if it has at least one 'completed' scheduled procedure and the other scheduled procedures are 'discontinued' or it has only 'discontinued' scheduled procedures and at least one performed procedure.

COMPLETED: A requested procedure is 'completed' once a radiology report has been created.

5.1.3. Scheduled Procedure

DEFINITION

A scheduled procedure is the smallest unit of work which is scheduled and performed.

CONTEXT

The radiology department defines how requested procedures are split up into units of work. Scheduled procedures are there to reserve resources (imaging modality, performing technicians, …​) and reflect the steps needed to actually do the work requested in the requested procedure. As an example if a requested procedures involves several imaging modalities than these resources need to be scheduled (reserved) and thus split up into several scheduled procedures.

COMPONENTS

Its main components are

  • corresponding requested procedure

  • scheduled procedure (i.e. "CT ABDOMEN WITH IV CONTRAST" usually coming from a standardized code scheme such as SNOMED CT or RadLex Playbook)

  • modality type (CT, MR, US, …​)

  • modality (CT01, MR01, …​)

  • scheduled start date

  • scheduled start time

  • corresponding performed procedure

SPECIAL TERMS

SCHEDULED: A scheduled procedure is 'scheduled' as soon as its 'scheduled start time', 'scheduled start date' and 'modality' are set.

COMPLETED: A scheduled procedure is 'completed' once it has a corresponding performed procedure.

5.1.4. Performed Procedure

DEFINITION

Is the smallest unit of work that has actually been performed which will result in radiological images.

CONTEXT

A performed procedure is the actual work done at an imaging modality resulting in radiological images.

COMPONENTS

Its main components are

  • corresponding requested procedure

  • corresponding scheduled procedure (optional, since it happens that procedures are done without being scheduled first)

  • performed procedure (i.e. "CT ABDOMEN WITH IV CONTRAST" usually coming from a standardized code scheme such as SNOMED CT or RadLex Playbook. can defer from the scheduled procedure)

  • performed start date

  • performed start time

  • performing physician

5.1.5. Radiology Study

DEFINITION

The radiology study holds actual radiological images.

CONTEXT

The radiology study represents what is called study by the DICOM standard. The use of a radiology study in the Radiology Module is to generate a Study Instance UID which will propagate vie the DICOM Modality Worklist provided by the PACS to the imaging modality. The imaging modality will put the Study Instance UID in the images it creates. This allows the Radiology Module to access the DICOM study and its images in the PACS via the Study Instance UID.

COMPONENTS

Its main components are

  • study ID

  • study instance UID (unique identifier of the study)

5.1.6. Radiology Report

DEFINITION

The radiology report is made by a radiologist which documents all findings made by reading the study’s images.

CONTEXT

Once a requested procedure is 'ready for reporting' a radiologist can claim the requested procedure for reporting and create the report.

COMPONENTS

Its main components are

  • corresponding requested procedure

  • report status (claimed, completed, discontinued)

  • report date

  • radiologist writing the report

  • report text

SPECIAL TERMS

CLAIMED: A radiology report is 'claimed' if a radiologist has claimed to work on a requested procedure that is 'ready for reporting'.

COMPLETED: A radiology report is 'completed' once a radiologist has set the reports status to 'completed'.

5.2. User Roles

The following describes the user roles interacting with the Radiology Module.

5.2.1. Administrator - AD

Administrator of the Radiology Module configures orderables, DICOM UID org root used for DICOM Study Instance UID generation, DICOM web viewer details and other OpenMRS related settings.

5.2.2. Referring Physician - RP

Doctor ordering a radiological test to be done on a patient.

5.2.3. Scheduler - SC

Provider who schedules (sets date, time and location/modality) requested imaging procedures.

5.2.4. Performing Technician - PT

Technologist performing the imaging procedures on the patient. To get the scheduled procedures (his TODO list) he has to perform he can either find it in the Radiology Module or at the modality through querying the DICOM Modality Worklist from the PACS.

5.2.5. Radiologist - RA

Radiologist creates radiological reports for completed requested procedures.

5.3. User stories

The following user stories define the interactions of the users with the Radiology Module.

User stories are defined in following scheme: "As a <user role/> I <want/can/need> <action> so that <achievement/goal>."

read about user stories in 'Mike Cohn - User Stories Applied'

5.3.1. Referring Physician - RP

CREATE ORDER
STORY

As a referring physician I want to create a radiology order.

ACCEPTANCE CRITERIA

  • Verify that a referring physician can enter a new radiology order by entering

    • patient

    • an orderable from concepts (i.e. "R/O pulmonary embolism")

    • urgency [choose from EMERGENCY, ROUTINE, ON SCHEDULED DATE; defaults to ROUTINE]

    • date and time

    • orderer from providers (in case I am not an RP, but a data clerk with RP permissions entering the order for an RP)

    • order reason as free text

    • order reason from concept

    • a comment for the fulfiller of the order

  • Verify that a referring physician needs to enter a patient, orderable, urgency and orderer

  • Verify that a referring physician only needs to enter an order date and time if urgency is set to ON SCHEDULED DATE

  • Verify that a non-referring physician cannot create a radiology order

creating a radiology order does not create a requested procedure, this transaction represents the 'Order Placer' sending an order request to the 'Department System Scheduler/Order Filler' in terms of IHE actors. In other terms, any department allowed to create radiology orders sends a request for a radiology order to the radiology department, but does not interfere with the exact details of how the order is going to be executed/reported/billed. These details are a matter of the radiology department.
DISCONTINUE ORDER
STORY

As a referring physician I want to discontinue a radiology order.

ACCEPTANCE CRITERIA

  • Verify that a referring physician can discontinue a radiology order by entering

    • discontinuation reason (i.e. incorrect orderable ordered, patient refused to continue treatment, …​)

    • provider who ordered the discontinuation

  • Verify that a referring physician needs to enter discontinuation reason and provider

  • Verify that a non-referring physician cannot discontinue a radiology order

  • Verify that a referring physician cannot discontinue the radiology order if it is 'in progress', 'ready for reporting' or 'completed'.

A radiology order can be discontinued even if it already has a requested procedure with scheduled procedures, but only as long as there is no performed procedure. The existing requested procedure and its scheduled procedures will be discontinued.
LIST ORDERS
STORY

As a referring physician I want to see a list of radiology orders so that I can navigate to a specific radiology order’s order form or its patient dashboard form or its corresponding requested procedure’s form.

ACCEPTANCE CRITERIA

  • Verify that a referring physician can see a list of radiology orders with following columns

    • radiology order id

    • patient id + full name (hyperlink to patient dashboard form)

    • radiology order orderable

    • radiology order urgency

    • radiology order start date

  • Verify that a referring physician can navigate to a radiology order’s form via its radiology order id value

  • Verify that a referring physician can navigate to a patient’s dashboard form via its patient id + full name value

  • Verify that a referring physician can filter the list by

    • patient name or id

    • radiology order start date

REVISE ORDER
STORY

As a referring physician I want to revise an existing radiology order.

ACCEPTANCE CRITERIA

  • Verify that a referring physician can revise a radiology order by

    • TODO

  • Verify that a non-referring physician cannot revise a radiology order

  • Verify that a referring physician cannot revise the radiology order if it is 'in progress', 'ready for reporting' or 'completed'.

A radiology order can be revised even if it already has a requested procedure with scheduled procedures, but only as long as there is no performed procedure. The existing requested procedure and its scheduled procedures will be discontinued since they might no longer match the orderable. The radiology department will need to create a new requested procedure with its scheduled procedures for the revised order as if it was a new order.
FILTER ORDER LIST BY STATUS
STORY

As a referring physician I want to filter the list of radiology orders by its status so I can get only orders that are 'in progress', 'ready for reporting', 'completed'.

ACCEPTANCE CRITERIA

  • TODO

5.3.2. Scheduler - SC

LIST SCHEDULED PROCEDURES
STORY

As a scheduler I want to see a list of scheduled procedures so that I can see what procedures have been and what procedures still need to be scheduled.

ACCEPTANCE CRITERIA

  • Verify that a scheduler can see a list of scheduled procedures with following columns

    • scheduled procedure id

    • scheduled procedure start datetime

    • scheduled procedure’s imaging procedure

    • scheduled procedure’s modality type

    • corresponding performed procedure id

  • Verify that a scheduler can filter the list by

    • patient name or id

    • scheduled procedure start datetime

    • scheduled status; already scheduled or not

  • Verify that a scheduler can navigate to a scheduled procedure’s form via its scheduled procedure id value

SCHEDULE SCHEDULED PROCEDURES
STORY

As a scheduler I want to schedule an existing scheduled procedure so that it can be performed by a performing technician.

ACCEPTANCE CRITERIA

  • Verify that a scheduler can schedule a scheduled procedure by setting its scheduled procedure start datetime

  • Verify that a scheduler can see a header with radiology order information if the corresponding requested procedure has a radiology order. The radiology order header should show

    • patient

    • order number

    • accession number

    • order orderable

    • order urgency

    • orderer

    • order start date

  • Verify that a scheduler can only schedule a scheduled procedure if it is not 'scheduled' or 'completed'

DISCONTINUE SCHEDULED PROCEDURE
STORY

As a scheduler I want to discontinue a scheduled procedure.

ACCEPTANCE CRITERIA

  • Verify that a scheduler can discontinue a scheduled procedure by entering

    • discontinuation reason (i.e. equipment maintenance, patient did not arrive)

    • provider who ordered the discontinuation

  • Verify that a scheduler needs to enter discontinuation reason and provider to discontinue a scheduled procedure

  • Verify that a non-scheduler cannot discontinue a scheduled procedure

  • Verify that a scheduler can discontinue the scheduled procedure if it is 'scheduled'

  • Verify that a scheduler cannot discontinue the scheduled procedure if it is 'completed'

5.3.3. Performing Technician - PT

CREATE REQUESTED PROCEDURE
STORY

As a performing technician I want to create a requested procedure with scheduled procedures for a radiology order so that it can be scheduled by the scheduler.

ACCEPTANCE CRITERIA

  • Verify that a performing technician can create a requested procedure by entering

    • a requested procedure from a concept (i.e. X-RAY, CHEST)

    • adding one or more scheduled procedures (with imaging procedure from concepts, modality type (CT, MR, US, …​)

  • Verify that the performing technician sees a a summary with radiology order information of the radiology order he is creating the requested procedure for. The summary should show

    • accession number

    • orderable

  • Verify that the performing technician has to add at least one scheduled procedure

  • Verify that when a requested procedure is created a radiology study with a Study Instance UID is is created as well

  • Verify that a non-performing technician cannot create a requested procedure

this story needs clarification. I chose this step to be done by the PT but it could of course be done by someone else. The step could be automated in case we have a mechanism in place that maps all orderables to requested procedures as described by IHE Radiology Technical Framework in 3.4.2 Scheduled Workflow Concepts in Practice see example of "R/O Pulmonary Embolism". The mapping would then be configured by each implemenation.
the use of the requested procedure is to be able refine how the orderable is mapped to an imaging procedure. a different kind of code could be used for orderables and requested procedures. the orderable is closer to what should be done in an abstract sense and the requested procedure closer to the imaging procedure.
DISCONTINUE REQUESTED PROCEDURE
STORY

As a performing technician I want to discontinue a requested procedure so that it will not be performed.

ACCEPTANCE CRITERIA

  • Verify that a performing technician can discontinue a requested procedure by entering

    • discontinuation reason (i.e. equipment maintenance, …​)

    • provider who ordered the discontinuation

  • Verify that a performing technician needs to enter discontinuation reason and provider to discontinue a scheduled procedure

  • Verify that a non-performing technician cannot discontinue a requested procedure

  • Verify that a performing technician can discontinue the requested procedure if it is 'scheduled'

  • Verify that a performing technician cannot discontinue the requested procedure if it is 'in progress', 'ready for reporting' or 'completed'

  • Verify that when the requested procedure is discontinued its scheduled procedures are discontinued as well

TODO

stories are ok until here, need to do more work on the following

===== LIST REQUESTED PROCEDURES

STORY:: As a performing technician I want to see a list of requested procedures
where I can narrow down the results by filtering and navigate to a specific
requested procedure's form.

ACCEPTANCE CRITERIA::

* I can see following columns in the list
* I can filter the list by
** patient name or id
** requested procedure code
** status; not yet performed; performed (has performed procedures?)
* I can navigate to the requested procedure's form by
selecting a hyperlink in a specific requested procedure's row

===== MARK SCHEDULED PROCEDURE AS COMPLETE

STORY:: As a performing technician I want to mark a scheduled procedure as
completed.

ACCEPTANCE CRITERIA::

* when I select the scheduled procedure to complete it I am redirected to the
performed procedure form with all info from the scheduled procedure pre-filled
in the performed procedure's fields
** scheduled procedure start datetime as performed procedure start datetime
** scheduled procedure imaging procedure as performed procedure's imaging
procedure
** performed procedure is linked to the scheduled procedure (read-only)
* I am able to
** enter date and time of completion
** enter provider which performed the procedure
** more?

NOTE: see {ihe-tf-rad-vol2} for 'MPPS In Progress, Simple Case';
1 scheduled procedure step results in 1 performed procedure step

===== ADD NON-SCHEDULED PERFORMED PROCEDURE

STORY:: As a performing technician I want to add a performed procedure which was not
scheduled to a requested procedure.

ACCEPTANCE CRITERIA::

* from the requested procedure form I can add a performed procedure
* I can enter all fields of the performed procedure except the link to the
scheduled procedure

NOTE: see {ihe-tf-rad-vol2} for 'MPPS In Progress, Append Case';
1 scheduled procedure step results in 2 performed procedure step

===== CREATE NON-REQUESTED PERFORMED PROCEDURE

STORY:: As a performing technician I want to create a performed procedure which was not requested.

ACCEPTANCE CRITERIA::

On the requested procedure form

* I create a new requested procedure on the requested procedure form and add a
performed procedure to it as in the case where no scheduled procedure exists.

NOTE: see {ihe-tf-rad-vol2} for 'MPPS In Progress, Uncheduled Case';
0 scheduled procedure step results in 1 performed procedure step

==== Radiologist - RA

===== LIST REQUESTED PROCEDURES

STORY:: As a radiologist I want to see a list of requested procedures which are
completed and thus need reporting.

ACCEPTANCE CRITERIA::

* I can see following columns in the list
* I can filter the list by
** patient name or id
** performed date
** modality type
** performed procedure code
** status; not yet reported; already reported