fdawgs / yh-fhir-listeners

Yeovil Hospital's Mirth Connect FHIR Listener channel for use with InterSystems' TrakCare PAS (v2020 MR6.11)

Note This repository is unmaintained as of 2023-05-03 as I am no longer employed by Somerset NHS Foundation Trust.

Yeovil Hospital - SIDeR FHIR Listener endpoints

Yeovil Hospital's Mirth Connect FHIR Listener channel for use with InterSystems' TrakCare PAS (v2020 MR6.11)

Overview

Purpose

This repo outlines the steps that have been taken to provide the technical deliverables required by the SIDeR programme, alongside the issues that were encountered during development, and how to deploy the resulting Mirth Connect channel.

Logs documenting the work undertaken to deploy these endpoints can be found in docs/worklogs.

The intended audience for this page are team members of the Solutions Development team at Yeovil Hospital, alongside technical partners and developers from other stakeholders in the programme should they wish to use this and adapt it to implement in their own systems.

This documentation is written under the assumption that the reader has prior experience using Mirth Connect.

Background

NHS Somerset (SOMICB) started the SIDeR project to link up all main clinical and social care IT systems used in Somerset to improve and support direct care. Black Pear Software Ltd. (BP) is the technical partner that supports the project.

Stakeholders (as of 2022-11-01) are:

• Children's Hospice South West (CHSW)
• Devon Doctors (DD)
• Dorothy House Hospice (DHH)
• GP practices within Somerset (GPs)
• Somerset County Council (SCC)
• Somerset NHS Foundation Trust (SFT)
• South Western Ambulance Service NHS Foundation Trust (SWASFT)
• St Margaret’s Hospice (SMH)
• Yeovil Hospital (YH)

Deliverables

Care Connect RESTful FHIR API endpoints

Black Pear have built a single-page web application for a shared care record, which will retrieve data relating to a patient from each stakeholder that can do so, and amalgamate it into this record. The record is not stored in a cache anywhere and is built on the fly. Care providers can then access this record through a contextual link (an embedded link within the PAS). Clients using the web app need to be able to make GET requests to RESTful HL7® FHIR® API endpoints to retrieve a set of seven FHIR resources that adhere to their respective NHS Care Connect API profiles to populate the record.

Contextual link

A contextual link needs to be added to our PAS to allow care providers access to the shared record. Refer to Interoperability patterns - Contextual launch in the SIDeR wiki for more information.

Prerequisites

• Mirth Connect v3.12.0 (including supporting database instance)
• The latest release of yh-fhir-authentication-service (for securing endpoints with HTTPS, OAuth, and bearer tokens)
• Node.js >=18.12.1 (optional, for development)

Setup

This Mirth Connect channel has been tested on a Mirth Connect instance (v3.12.0) running on Windows 10 and Windows Server 2019, with an instance of SQL Server 2019 being used as the database backend for Mirth Connect.

Perform the following steps before deployment:

1. Download and extract the latest release asset
2. Navigate to the extracted directory
3. Install the FHIR Connector extension (dist/fhir-3.12.0.yh001.zip) in Mirth Connect
4. Import the FHIR Listener channel (dist/FHIRListener.xml) into Mirth Connect
5. Declare variables listed in the channel description, in the configuration map
6. Run the SQL queries found in dist/sql to create lookup tables

Known issues and caveats

Issues with InterSystems' TrakCare PAS (used by YH) and staff misuse of the PAS have affected how the data is presented in the endpoints and how searches can be performed.

Data quality

• AllergyIntolerance resources:
  • Unable to provide SNOMED codes for allergies and intolerances in AllergyIntolerance resources due to there being free text inputs in TrakCare
  • Low recordings of allergy and intolerance data in TrakCare:
    • 350,513 non-deceased patients with records in TrakCare as of 2020-11-19
      • 34,405 patients have ‘No Known Allergy’ recorded (9.8%)
      • 13,139 patients have one or more allergies recorded (3.7%)
  • Due to the above issues, Paul Foster (CCIO at YH) on 2020-11-19 suggested we do not provide AllergyIntolerance resources (functionality is still present in the channel, however)
• Condition resources:
  • Unable to provide Condition resources as conditions are held in SimpleCode, not TrakCare
• DocumentReference resources:
  • Unable to provide DocumentReference resources as these are held in Patient Centre, not TrakCare
• Encounter resources:
  • Discharge/end dates for outpatient Encounter resources are not provided due to poor data quality. Staff in outpatients misuse these input fields in TrakCare to mark when “all admin has been completed for that outpatient encounter” and not when the encounter has finished
  • Unable to provide clinician contact details for Encounter resources due to the following:
    • In TrakCare a care provider has a mobile number field against them, but it is rarely populated
    • There is no internal contact number field in TrakCare
    • If you want to reach say, a gynaecology consultant, you need to manually search a list on YH’s intranet for their secretary’s extension number, and there is no indication as to how current the list is
    • Teams do not have a contact number
• Patient resources:
  • Unable to provide SNOMED codes for religious affiliation as these are not in TrakCare (NHS Data Dictionary coding is provided, however)
  • Unable to provide GP surgery/organisation name value for inline Organization FHIR resource as this data is also not held in TrakCare; using GP consultant name as a placeholder
  • A sizeable number of patient records without postcodes

Search saveats

• Every search request to a FHIR resource endpoint that is NOT the Patient FHIR resource endpoint MUST have a patient search parameter, this is to stop intentional or unintentional DOS attacks due to long-running SQL queries:
  • GET [baseUrl]/AllergyIntolerance?criticality=[code] will return a 500 error
  • GET [baseUrl]/AllergyIntolerance?patient=[id]&criticality=[code] will work

This is due to YH not having direct control over the underlying databases of the PAS, so cannot add indexes or make appropriate performance tweaks to support searches without also filtering by a patient.

Contributing

Contributions are welcome, and any help is greatly appreciated!

See the contributing guide for details on how to get started. Please adhere to this project's Code of Conduct when contributing.

Acknowledgements

• Adam Wiles (YH) - Procedure FHIR resource advice
• Anthony Smith (YH) - Logo design
• David Suckling (YH) - TrakCare database table structure and frontend support
• Dunmail Hodkinson (BP) - HL7 FHIR STU3 specification adherence and best practices advice
• George Dampier (YH) - MedicationStatement FHIR resource advice
• Jessica Male (YH) - TrakCare frontend support
• Julian Matthews (SFT) - Bug reports
• Jon Simpson (YH) - MedicationStatement FHIR resource advice
• Neil Hayes-Webster (YH) - SQL query optimisation
• Nicolas Noblet (YH) - SQL query optimisation, TrakCare database table structure advice
• Will Jehring (BP) - HL7 FHIR STU3 specification adherence advice

License

yh-fhir-listeners is licensed under the MIT license.

yh-fhir-listeners's Issues

Read request to MedicationStatement endpoint takes up to 170 seconds to return results

Describe the bug

Making a GET request to the MedicationStatement endpoint takes an excessive amount of time (avg 170 seconds) to return results.

To Reproduce

Steps to reproduce the behavior:

1. Make GET request to [baseUrl]/MedicationStatement/[id]

Expected behavior

For the requested resource to be returned in less than 5 seconds, which is the time is takes to return a result when making a read request for AllergyIntolerance, Patient, and Flag resources.

Desktop (please complete the following information)

• OS: Windows
• Version Windows 10

Additional context

The excessive time is due to the content of the dynamic WHERE clause in the SQL used to retrieve this data.

Generate new test patient records

Add lookup table to map YDH to SNOMED codes for flags

Add support for 'email' search param to Patient resource endpoint

Describe the solution you'd like
Add support for 'email' search param to Patient resource endpoint as documented here:
https://nhsconnect.github.io/CareConnectAPI/api_entity_patient.html#21-search-parameters

Add Pharmacy Order Number identifier to MedicationStatement resources

Read request to Flag FHIR resource endpoint results in error 400

Describe the bug

Read request to Flag FHIR resource endpoint results in error 400.

To Reproduce

Steps to reproduce the behavior:

1. Make GET request to following [baseUrl]/Flag/[id]
2. See error

Expected behavior

A single Bundle FHIR resource to be returned with a single Flag FHIR resource inside.

Desktop (please complete the following information)

• OS: Windows
• Version Windows 10

Add support for 'phone' search param to Patient resource endpoint

Describe the solution you'd like
Add support for 'phone' search param to Patient resource endpoint as documented here:
https://nhsconnect.github.io/CareConnectAPI/api_entity_patient.html#21-search-parameters

Exposed Username and password in URI

Potential security breach.
See /docs/worklogs/contextual_link.md

Add support for 'type' search param to AllergyIntolerance resource endpoint

Describe the solution you'd like
Add support for 'type' search param to AllergyIntolerance resource endpoint as documented here:
https://www.hl7.org/fhir/STU3/allergyintolerance.html#search

Read request to Encounter endpoint takes up to 50 seconds to return results

Describe the bug

Making a GET request to the Encounter endpoint takes an excessive amount of time (avg 50 seconds) to return results.

To Reproduce

Steps to reproduce the behavior:

1. Make GET request to [baseUrl]/Encounter/[id]

Expected behavior

For the requested resource to be returned in less than 5 seconds, which is the time is takes to return a result when making a read request for AllergyIntolerance, Patient, and Flag resources.

Desktop (please complete the following information)

• OS: Windows
• Version Windows 10

Additional context

The excessive time is due to the content of the dynamic WHERE clause in the SQL used to retrieve this data.

Add support for 'date' search param to Flag resource endpoint

Describe the solution you'd like
Add support for 'date' search param to Flag resource endpoint as documented here:
http://hl7.org/fhir/stu3/flag.html#search

Add TypoCI config file

Read request to MedicationStatement FHIR resource endpoint results in error 400

Describe the bug

Read request to MedicationStatement FHIR resource endpoint results in error 400.

To Reproduce

Steps to reproduce the behavior:

1. Make GET request to following [baseUrl]/MedicationStatement/[id]
2. See error

Expected behavior

A single Bundle FHIR resource to be returned with a single MedicationStatement FHIR resource inside.

Desktop (please complete the following information)

• OS: Windows
• Version Windows 10

Add support for 'identifier' search param to Flag resource endpoint

Describe the solution you'd like
Add support for 'identifier' search param to Flag resource endpoint as documented here:
http://hl7.org/fhir/stu3/flag.html#search

Add support for 'criticality' search param to AllergyIntolerance resource endpoint

Describe the solution you'd like
Add support for 'criticality' search param to AllergyIntolerance resource endpoint as documented here:
https://www.hl7.org/fhir/STU3/allergyintolerance.html#search

Add paging functionality

Refer to https://www.hl7.org/fhir/STU3/http.html#paging

Add examples for global map variables

Add support for Condition FHIR resource

Is your feature request related to a problem? Please describe.
https://nhsconnect.github.io/CareConnectAPI/api_clinical_condition.html

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Add estimated discharge date to Encounter.period.end

Add support for Procedure FHIR resource

Is your feature request related to a problem? Please describe.
https://nhsconnect.github.io/CareConnectAPI/api_clinical_procedure.html

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.