...

Introduction

This document describes the plugin for loading SPRs from the HL7 messages. The goals of the plugin are as follows:

1. Receive HL7 messages sent to OpenSpecimen via a port (HL7 v2.1, message type ORU / R03)
2. Every night, process all the HL7 msgs received and extract SPR text from it
3. Lookup for a participant with the access number in OpenSpecimen database using APIs
4. If found, attach the SPR with the patient.
5. If not found, store the HL7 in an "unprocessed" queue
6. Every night, retry the failed HL7 messages to see if it can be attached to a patient (in case the accession number was updated on a later date)
7. Send a summary email of failed messages to the administrator

Technical details

1. HAPI SDK to process HL7 messages
2. OpenSpecimen REST APIs to read/write data

Handling SPR addendum

In case Using this plugin, OpenSpecimen can be integrated with pathology systems like CoPath or Cerner via HL7. The plugin loads the text Surgical Path Reports (SPRs) and links with the visit object in OpenSpecimen based on the accession number. 

Prerequisite

Data for the "Surgical Pathology Number" field on the Visit page should be entered by the biobank staff. This value is used by the plugin to link the SPR to the right visit.

Working

1. The plugin receives the HL7 messages on a pre-determined port. 19090 by default.
2. The messages supported are ORU R01 and R03.
3. The messages are processed in real-time. The SPR report is uploaded if a matching visit is found based on the accessing number in the message.
4. If a matching visit is not found, it is stored in the database as "PENDING". A retry is performed for X number of days to find a matching visit where X is configurable.
5. A summary email of the failed messages is sent every night to the administrators.

FAQs

How is addendum to SPRs handled?

When the SPR is edited, it gets overridden on top of the existing overwritten with the new SPR. The assumption is that in case of addendum, the new message sent contains the older content and the new content.

...

complete SPR.

How are errors handled?

An email is sent after every run night in case any message failed loading. All error messages are reprocessed for X number of days (where X is configured by the super admin). 

Audit

Every message received and processed is maintained in an audit table in the OS database. This can be used for getting includes statistics for how many messages received, processed, error, success, etc.