BC Client Registry FHIR Implementation Guide
1.0.0 - Build CI
BC Client Registry FHIR Implementation Guide
1.0.0 - Build CI
BC Client Registry FHIR Implementation Guide - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Note
This specification is currently published as a Draft Standard on the ministry GitHub and is not intended for implementation. Feedback is welcome but readers should understand that there is more work to be done in testing the profiles and operations defined in this guide. For more information, please see the Future Plans page in this guide.
The approach to design a FHIR interface to the Client Registry was to keep the interactions as similar as possible to the current system. Any necessary additions and improvements were also considered for inclusion. Namely:
There are a number of assumptions that were made at the start of design:
The main outcomes from the design process were as follows:
These items are new to the Client Registry interface and subject to change as they are reviewed and evolve.
| Proposal | Description |
|---|---|
| Add Patient interaction | Some of the features normally done through the Revise Patient interaction are now part of Add Patient. Specifically, ‘force create’ and newborn interactions are now done with Add Patient. |
| Partial Update interaction | A Partial Update interaction allows users to logically delete, add or change part of the Patient resource. This is useful when a stakeholder doesn’t need (or persist) certain Patient attributes, but today, must query and then echo back these attributes in a Revise Patient interaction. The exact operations allowed by the Client Registry is to be determined. |
| Business dates feature | Attributes will have business dates that haven’t been present in V3. |
All interactions will primarily use the Patient resource. The Patient resource is ideal to represent clients as the Patient resource has many of the necessary attributes but will require some extensions. Patients also are recommended for enterprise master patient indices by the HL7 group and is in a Normative state, i.e. stable and ready for implementation. See FHIR standards evolution for a description of Normative.
Four Patient profiles are used: the main profile ClientRegistryPatient - used also the search profile in the search operation (GetDemographics and FindCandidates), the merge profile MergePatient and finally the PatientUpdate for partial updates, e.g. updating just address or just telephone.
PHN is a sensitive Patient attribute and although considered for the Paitent Resource ID this idea was discarded. A non-PII surrogate Resource ID has been created which this guide will call the surrogate PHN. It is a universal uniuqe identifier (UUID) and Patient Resources will be populated with this UUID.
There are several extensions that are applied to the Patient resource. The list below is an overview, more details on the extensions can be found by following the links on the Patient resource snapshot page .
| Extension Name | Description |
|---|---|
| bc-business-period-extension | A Period extension for the business effective dates. |
| bc-validation-status-extension | A code that represents the address validation status. This will be part of every Patient.address |
| bc-death-verified-flag-extension | An extension that indicates a verified death. |
| bc-*-history-extension | The set of history extensions are necessary to add historical records to the Patient resource such as gender. |
| bc-gender-identity-extension | An extension that houses the gender identity codeable concept. |
| bc-sourceId-extension | The source identifier code. |
| bc-identifier-status-extension | The status of an identifier, e.g. active, merged. |
The Client Registry doesn’t recognize all the standard FHIR codes for some attributes that must be supported, see the table below which indicates the supported codes.
| Attribute | Supported Codes |
|---|---|
| Patient.name.use | Only usual, official or nickname from NameUse value set. |
| Patient.telecom.use | Only home, work, mobile from the ContactPointUse value set. |
| Patient.telecom.system | Only phone or email from the ContactPointSystem value set. |
| Patient.address.type | Only postal or physical from the AddressType value set. |
| Patient.identifier.system | See the section on identifiers |
The following table maps the FHIR codes to Client Registry codes.
| FHIR Code Type | FHIR Code | HCIM Equivalent |
|---|---|---|
| Name.use | usual | declared |
| Name.use | official | card |
| Name.use | nickname | preferred |
| Telecom.use | home | home |
| Telecom.use | work | work |
| Telecom.use | mobile | mobile |
| Telecom.system | phone | phone |
| Telecom.system | ||
| Address.type | postal | mailing |
| Address.type | physical | physical |
| Gender | other | undifferentiated |
| Gender | unknown | unknown |
| Gender | male | male |
| Gender | female | female |
The Client Registry will use the FHIR Operations pattern to exchange information. These are the Operations that Client Registry FHIR will support:
| Operations |
|---|
| https://…./Patient/$FindCandidates |
| https://…./Patient/$GetDemographics |
| https://…./Patient/$RevisePatient |
| https://…./Patient/$RevisePatient.Async |
| https://…./Patient/$PartialUpdatePatient |
| https://…./Patient/$PartialUpdatePatient.Async |
| https://…./Patient/$AddPatient |
| https://…./Patient/$AddPatient.Async |
| https://…./Patient/$MergePatient |
| https://…./Patient/$MergePatient.Async |
| https://…./Patient/$PatientNotification |
The Async suffix informs the Client Registry FHIR server to perform the operation in an asynchronous manner. The profiles and examples used in the Async versions of the Operations are identical to the synchronous Operations.
The body of the request message will vary depending on the business context however all message bodies will consist of a Bundle with at least a Parameters resource and may have Patient and RelatedPerson resources in other Bundle entries.
The Bundle profile for the request depends on the type of request.
| Operations | Request Bundle Profile | Response Bundle Profile |
|---|---|---|
| $FindCandidates | Find Candidates request profile | Find Candidates response profile |
| $GetDemographics | Get Demographics request profile | Get Demographics response profile |
| $RevisePatient | Revise Patient request profile | Revise Patient response profile |
| $RevisePatient.Async | Revise Patient request profile | Revise Patient response profile |
| $PartialUpdatePatient | Update Patient profile | Update Patient response profile (uses revise) |
| $PartialUpdatePatient.Async | Update Patient profile | Update Patient response profile (uses revise) |
| $AddPatient | Add Patient request profile | Add Patient response profile |
| $AddPatient.Async | Add Patient request profile | Add Patient response profile |
| $MergePatient | Merge Patient request profile | Merge Patient response profile |
| $MergePatient.Async | Merge Patient request profile | Merge Patient response profile |
| $PatientNotification | Patient Notification request profile | N/A |
Response resources are wrapped in Bundles. A search operation like Get Demographics or Find Candidates will be a searchset Bundle that echoes back the search parameters by including an extra Parameters resource in the Bundle.
The surrogate PHN can be used to query for Patients.
https://…./Patient/UUID
Two operations related to UUID are also available
| Restful |
|---|
| GET https://…./Patient/UUID/$HistoryPatient |
| GET https://…./Patient/UUID/_elements=identifier |
$HistoryPatient is equivalent to the $GetDemograhpics with the withHistory parameter.
_elements=identifier is equivalent to the $GetDemographics with the idenifiersOnly parameter.
This guide touches on some of the business and conformance rules regarding use of the Client Registry. However this guide is not the source of conformance or business rules and the audience is referred to British Columbia’s Health Information Exchange web site for details on the Client Registry system and access to Client Registry.
Each interaction is a FHIR Operation using a Bundle. The Bundle entries will consists of parameters, patients, etc.
The table below is only showing the standard parameters included in each Bundle; each Operation may have more parameters such as withHistory. More detailed information regarding each Operation can be found in the Operation definitions.
| Parameter Name | Parameter Value | Comments | IN, OUT, both |
|---|---|---|---|
| message id | parameter.value[string] | Message (unique) id | both |
| create time | parameter.value[dateTime] | Creation date of message | both |
| request message id | parameter.value[string] | Message (unique) id from request message | OUT |
| sender | parameter.value[Identifier] | Message sender | OUT |
| enterer | parameter.value[Identifier] | UserId for message | OUT |
| requestParameters | parameter.value[MetadataParametersIn] | For searches this is included in the response and echoes back the search IN parameters. |
There are three searches available for Client Registry FHIR, two flavours of Find Candidates and one Get Demographics. The operations are:
| Search Operations | Description |
|---|---|
| https://…./$FindCandidates | Searching for Patients that match the search criteria |
| https://…./$GetDemographics | Searching for a single Patient |
Find Candidates may return zero or more candidates, while Get Demographics is designed to return zero or a single matching Patient. These searches are expected to provide the required information to confirm a person’s identify.
More details can be found here, Search page.
Add, Revise, Update and Merge Patient are maintain transactions that are closely related and therefore are described in the same section. They use the same FHIR structure and similar resources; merge uses additional parameters.
| Add, Revise, Update and Merge Operations | Description |
|---|---|
| https://…./$RevisePatient | Updating a Patient |
| https://…./$RevisePatient.Async | Updating a Patient asynchronously |
| https://…./$PartialUpdatePatient | Updating a specific Patient attribute |
| https://…./$PartialUpdatePatient.Async | Updating a specific Patient attribute asynchronously |
| https://…./$AddPatient | For newborns or to ‘force create’ a Patient |
| https://…./$AddPatient.Async | The asynchronous version of AddPatient |
| https://…./$MergePatient | Resolving duplicate Patients records (same individual) |
| https://…./$MergePatient.Async | Resolving duplicate Patients records (same individual) asynchronously |
These business transactions will allow the user to:
More details can be found here, Add, Revise, Update and Merge page.
Distributions will use a stakeholder client endpoint for the $PatientNotification operation. The FHIR structure of the interaction is the same as RevisePatient.
See Patient Notifications for more details.
The asynchronous versions of Add, Revise, Update and Merge Operations share the same request and response profile as the synchronous version.
The FHIR asynchronous pattern is not followed by this FHIR implementation. The existing pattern the Client Registry uses today will be mimicked. I.e.
This implementation of FHIR will follow the standard FHIR error handling. E.g. return an OperationOutcome in a Bundle with the appropriate HTTP status code. Users are expected to monitor the http status codes and the OperationOutcome resources for issues.
HTTP 200 (OK) will be returned in all cases where the request was successful. This includes a search that was a valid FHIR Operation but did not match any Patients. The only exceptions when a Patient is first created, the status code response is 201 (Created).