Northern Region Eclair Orders and Results FHIR API

Overview

Orders and Results API provides easy and secured real-time search and retrieve patients, diagnostic reports and observations that are centrally stored in the Northern Region Eclair Clinical Data Repository (CDR).

This API, implemented on the serviceRequest endpoint, also provides the ability to update an Éclair system with details of a service request that has occurred or has a confirmed occurrence date and time.

The API is based on the following FHIR standards:

• FHIR specification version 4.1 (refer to: http://hl7.org/fhir/R4/)
• Ministry of Health NHI and HPI FHIR Implementation Guide for Patient and Practitioner
• FHIR NZBase specifications (refer to: http://build.fhir.org/ig/HL7NZ/nzbase/branches/master/index.html)

This API is based on the following version of the Sysmex Eclair Orders and Results FHIR API:

• Latest Version: 1.5
• Last updated: 10 May 2023
• Vendor Documentation is found here: https://northernregion.sharepoint.com/sites/hA-RegionalVendorAggregation/Shared%20Documents/Forms/AllItems.aspx?ga=1&id=%2Fsites%2FhA%2DRegionalVendorAggregation%2FShared%20Documents%2FSRTD%2DAPI%20Development%2FOrders%20and%20Results%20API%20and%20MOH%20Findings%20Report%2FSysmex%20Vendor%20Documents%2FDeveloper%20Guide&viewid=49a3290d%2Ddbb2%2D4b5d%2Dbda7%2D9e883d40b8dc

Use-Cases

• Retrieve the latest lab test results (i.e., Observations) for a specific lab test
• Retrieve the last [x] number of results for a specified lab test(s)
• Retrieve a result for a particular date or date range
• Retrieve reference range for lab test(s)
• Retrieve and filter lab test results using lab result codes, medication level
• Retrieve the name and details of a clinician
• Post Orders (i.e., Service Requests)

Retrieval Query Parameters

• Retrieve one or more Patient resources:
  • search by NHI or internal patient ID
  • search by partial patient name
• Retrieve one or more DiagnosticReport or Observations resources using:
  • search by report ID, facility ID and optionally test code
  • search by NHI or internal patient ID
  • filter by code
  • filter by date range
• Retrieve a Practitioner using CPN

The following parameters are supported for performing queries on the available FHIR resources.

See http://hl7.org/fhir/R4/searchparameter-registry.html for further information.

Important Notes

Capabilities and Limitations

1. Patient, DiagnosticReport, Observation and Practitioner resources could be retrieved from Eclair utilising NHIs and test codes as search parameters
2. Results which meet Patient OPTED-OFF rule criteria are not presented in returned resource bundles.
3. ServiceRequest (order) resources can be POSTed successfully to Eclair as long as a matching Eclair v.2 StyleSheet is installed. If there is no style-sheet the Eclair FHIR API will return a 422 (Unprocessable Entity) response.
4. Search by test codes linked in Eclair to external codes will return results recorded against all linked local codes.
5. Search by local codes having no linkage to external codes in Eclair can be used as a query parameter to retrieve results from that lab only.
6. The data could be returned sorted, counted and limited by query parameters.
7. The resources returned by requests to the API had audit records written in Eclair, with caveat that the audit record only references MULEECLAIRFHIRAPI rather than the resource requester (consuming system or logged in user). The audit record can be linked to the requester by searching the Eclair proxy log using the request DateTime and the client from the audit record i.e. client 0cf2f2dc-414f-4c2b-8983-cf33a3cf98fb
8. Query response returned were comparable with same/similar search issued to Web Eclair.
9. Default rate limit applied to this API is 1 request per second; Consumer of the API must request on the API onboarding form if a different rate limit must be applied for the consumer system

Known API Issues

No recorded known issues for this API.

Known Eclair Data Issues

1. Eclair Get Patient request returns a patient address element "State" having incorrect data, i.e., bore no relevance to the patient's actual address. Consumers are highly discouraged from requesting Eclair Patient Demographics data. Instead, Consumers are advised to use the Northern Region Patient FHIR API.

Explanation of Test Code Use

Key to ensuring that data could be processed via GET and POST statements was understanding how to retrieve data from the Eclair dataset. Diagnostic Reports and Observations are retrieved from Eclair by using a code as a search parameter. There are three options for codesets which can be referenced:

LOINC Codeset

LOINC is the global test code standard. Source: https://loinc.org/

NZPOCS Codeset

NZPOCS is the New Zealand-specific LOINC-approved codeset. It consists of the full LOINC codeset plus an additional 54 NZ specific codes. Source: https://www.tewhatuora.govt.nz/publications/hiso-100042022-new-zealand-pathology-observation-code-sets/ (8-Aug 2022 publication)

Local Codeset

Systems which send test orders and results to Eclair may create their own local test codes.

Eclair External Codeset

The Eclair External Codeset consists of codes from LOINC, NZPOCS and Eclair proprietary External codes as setup within Eclair. A result for any (LOINC, NZPOCS, Local) test code that is mapped to the Eclair External Codeset can be retrieved by issuing a GET request referencing the external code as a parameter.

Local Codes Linked to External Codeset

In Eclair the local code can be linked to an external code. Requesting DiagnosticReports by

1. Local Code - will return only DiagnosticReports created against the local code

2. External Code - will turn all DiagnosticReports created against any of

   • the Local Code
   • other Local Codes linked to the same External Code

Local Codes NOT Linked to External Codeset

In Eclair, if the local code is not linked to an external code, then DiagnosticReport Request by

• Local Code - will return only DiagnosticReports created against the local code