Profiles & Operations > Operation: Retrieve Practitioner
Retrieve Practitioner
Practitioner Read is a simple RESTful interactions It aligns with the generic RESTful read operation defined in the FHIR core specification (http://hl7.org/fhir/http.html#read). They supports retrieving a single Practitioner instance by their RESTful resource id.In this implementation, the resource id refers to practitioner EPID in PPR.
Note that :
Provider Person and Practitioner are used interchangeably in this document, as Practitioner is the name of the FHIR resource used to represent a Provider Person. When used in the context of FHIR, Practitioner will be used in place of Provider Person.
Practitioner Read operation returns the current instance of Practitioner resource.
Scope
This transaction involves a request by a FHIR Provider RESTful Client for the identification, naming, licensing and contact information associated with a single practitioner record, identified by the target server's record id for that practitioner. The request is received by the FHIR Provider RESTful Server which returns the requested record.
For example, an immunization or medication record provides a FHIR "reference" pointing to the Provincial Provider Registry "id" for a particular Practitioner. To look up information about the referenced clinician, the EMR uses the read operation to retrieve the clinician's contact and other information from the registry.
Interaction Diagrams
The following diagram illustrates the high level interaction between a FHIR Provider RESTful Client and FHIR Provider RESTful Server. The Provider transaction will use the following queries and responses:
- Read Pracititioner/Read Pracititioner Response
The resource cannot be rendered.
Actor: FHIR Provider RESTful Client
Role: Requests a demographic details for a single practitioner based on a known resource id from the FHIR Provider RESTful Server. The FHIR Provider RESTful Client populates its local store with information received from the FHIR Provider RESTful Server
Actor: FHIR Provider RESTful Server
Role: Returns demographic information for the single practitioner corresponding to the resource id specified by the FHIR Provider RESTful Client.
NOTE: In this implementation guide, Provincial Provider Registry is the FHIR Provider RESTful Server. All subsequent references of this actor should be interpreted as Provincial Provider Registry.
Specification
This FHIR spec is based on the HL7 R4 Read operation. It makes use of the following resource profiles:
Note: Please note that the following read operation will return only the Practitioner resource
Practitioner Read Request
GET [base]/Practitioner/EPID(Logical ID)
Practitioner Read Response
The PPR FHIR profiles are developed to constrain value sets and cardinality of data elements in the resources listed above. Since FHIR R4 does not support all the data elements required for this project, we have introduced a few extensions which can be found here.
Extensions
PPR Address Confidential Extension
- address-confidential (Address Confidential)
- address-purpose (Address Purpose)
- lhin-code (Local Health Integration Network Code)
- practitioner-deceased (Practitioner Deceased)
- practitioner-restriction (Practitioner Restriction)
- practitioner-qualification-level (Practitioner Qualification Level)
Summary of Supported Operations
The table below shows the allowed transactions for each profile and how they support FHIR endpoints, resources and their corresponding HTTP operations:
| Resource | Transaction | HTTP Operations | URL | Request Body Resource | Response Body Resource |
|---|---|---|---|---|---|
| Practitioner | Read | GET | [base]/Practitioner? | N/A | Practitioner |
The interaction summary table below lists the HTTP status codes that may be returned for the query.
| Interaction | Content-Type | Body | Location | Versioning | Status Codes | Comments |
|---|---|---|---|---|---|---|
| read (practitioner) | R | R: Practitioner | N/A | N/A | 200,400,404,422,500 |
Practitioner Read Operations
This represents an HTTP GET specifying the id of a single Practitioner instance from the FHIR Provider RESTful Client to retrieve the resource from the FHIR Provider RESTful Server.
Trigger Event
When a FHIR Provider RESTful Client has the server's "id" for a practitioner but does not yet have the name, contact, license and other information or wishes to retrieve an updated version of the practitioner's information, it invokes a Practitioner read.
Expected Behaviour
The FHIR Provider RESTful Server shall return the records that correspond to the "id" provided by the FHIR Provider RESTful Client. The FHIR Provider RESTful Server shall respond synchronously (i.e. on the same connection as was used to initiate the request).
See Response Handling page for additional response handling behaviour.
| Legend |
|---|
| code = OperationOutcome.issue.code |
| severity = OperationOutcome.issue.severity |
| details.coding.code=OperationOutcome.issue.details.coding.code |
| details.coding.display=OperationOutcome.issue.details.coding.display |
| details.text = OperationOutcome.issue.details.coding.text |
| HTTP Status | Scenario Description | severity | code | details.coding.code | details.coding.display | details.text |
|---|---|---|---|---|---|---|
| 200 OK | The PPR finds in its information source, a practitioner whose id (practitioner.id) matches the id specified by the FHIR Client Application | HTTP 200 | OK. Returns a Practitioner resources that matches the requested id. | |||
| 404 Not Found | The PPR cannot find a Location whose EPID matches the id specified by the FHIR Client Application. | error | not-found | |||
| 400 Bad Request | Missing security token | error | required | Missing required security token: PIN | ||
| 400 Bad Request | When there was syntactical error such as a missing or invalid header, a missing or invalid URL parameter, a request body that can't be parsed or doesn't conform to the basic FHIR JSON/XML syntax rules, etc. Returns an OperationOutcome resource indicating an issue. The client must fix the request and try again. | error | invalid | Will vary depending on the error | ||
| 401 Unauthorized | Failed authentication | error | security | Authorization is required for the interaction that was attempted | ||
| 406 Not Acceptable | The Accept header requested a format that the server does not support | error | not-supported | |||
| 422 Unprocessible Entity | FHIR validation errors such as invalid code, wrong date format, or violation of LOB defined business rules | Will vary depending on the error | Will vary depending on the error | OH-defined error code | OH-defined errror message | |
| 429 Too Many Requests | Rate Limit | error | throttled | Too Many Requests | ||
| 500 Internal Server Error | PHSD API validates the request but cannot return a valid response due to internal issues. | fatal | exception | Internal Error | ||
| 503 Service Unavailable | Indicates that the services has been temporarily taken down (on purpose) | |||||
| 504 Gateway Timeout | Downstream system(s) did not return timely response | error | timeout |
Examples
Examples of provider person Read request can be found below
GET [base]/Practitioner/12345
Examples of a provider person read response can be found below
Example of Operation Outcome