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
| Official URL: http://hlth.gov.bc.ca/fhir/client/OperationDefinition/bc-patient-find-candidates | Version: 1.0.0 | |||
| Active as of 2024-05-03 | Computable Name: FindCandidatesByExample | |||
This operation is used to query for a patient. The response can contain 0 or more Patients.
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 Find Candidates query is a FHIR Operation.
The request is a Bundle with Resources for message meta data, a Patient to match against and possibly a RelatedPerson representing the Mother with a PHN Identifier. The response is a Bundle with Resources for Patient’s that matched, response meta data, operation outcome resources and if using mother’s PHN RelatedPerson resources.
This is a ‘search by example’ and the Patient resource may be populated with various values and combinations of values. Those values are matched against the Client Registry.
Please refer also to the Identifiers page to find more details regarding how to use Identifier in your query.
For optimal searching and to be conformant with Health Information Exchange standards please review the Client Registry conformance standards found here. Those documents specify combinations of values that are best suited to find your Patients.
URL: [base]/Patient/$FindCandidates
Input parameters Profile: FindCandidatesRequestBundle
Output parameters Profile: SearchResponseBundle
Parameters
| Use | Name | Scope | Cardinality | Type | Binding | Documentation |
| IN | FindCandidatesRequestBundle | 1..1 | Bundle | The FindCandidates operation request Bundle. | ||
| OUT | SearchResponseBundle | 1..1 | Bundle | The FindCandidates operation response Bundle. |
The response may not include any Patients if none matched the criteria. If there are patients returned, the Bundle.entry.search.score (i.e. entry for the Patient resource) will contain the Client Registry score.
If multiple Patients match they will all be returned.
If the search used mother’s PHN then RelatedPerson resources are returned which include (a) the mother’s identifier and (b) a reference to the related Patient in the response Bundle. There may be multiple Patients returned, and therefore also multiple RelatedPersons, one per Patient (e.g. twins). See an example here.
| Cardinality | Resource Type | Comment |
|---|---|---|
| 1..1 | MetadataParametersIn | See profile. |
| 0..1 | ClientRegistryPatient | See profile. |
| 0..1 | RelatedPerson | This a standard FHIR resource, not profiled by the Client Registry. |
| Cardinality | Resource Type | Comment |
|---|---|---|
| 1..1 | MetadataParametersOut | See profile. |
| 1,,1 | OperationOutcome | An OperationOutcome resource that has warnings and errors regarding the operation requested. |
| 0..* | ClientRegistryPatient | See profile. |
| 0..* | RelatedPerson | This a standard FHIR resource, not profiled by the Client Registry. |
Besides the two mandatory name-value pairs, see here, Find Candidates has one more, see below.
| Name | Type | Cardinality | Notes |
|---|---|---|---|
| identifiersOnly | boolean | 0..1 | Instruct the Client Registry to return Patient Identifiers only when true. If not present, defaults to false. This is located in the Parameters entry of the Bundle. |
Besides the mandatory parameters, the request search parameters are echoed back in the MetadataParametersOut resource with a parameter named requestParameters (which is a MetadataParametersIn resource).
| Name | Type | Cardinality | Notes |
|---|---|---|---|
| requestParameters | MetadataParametersIn | 1..1 | The request parameters are echoed back.. |
If the request is to return a Patient based on the mother’s PHN, then the request Bundle must have a RelatedPerson resource with the mother’s PHN as an Identifier. No Patient is required in this case. There is an example request here.
Searching with the FindCandidates operation will match names of all use codes that the Client Registry supports no matter the name.use value provided in the request. Name.use may be left blank.
See Find Candidates request example.
See Find Candidates mother’s PHN request example.
See Find Candidates response example.
See Find Candidates mother’s PHN response example.