Organization read
Profiles & Operations > Organization Read
Organization Read
Organization Read is a simple RESTful interactions. It aligns with the generic RESTful read operation defined in the FHIR core specification. It supports retrieving a single Organization instance by their RESTful resource id.In this implementation, the resource id refers to provider organization EPID in PPR.
Scope
This transaction involves a request by a FHIR Provider RESTful Client for the identification, naming, licensing and contact information associated with a single organization record, identified by the target server's record id for that organization. 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 Organization. To look up information about the referenced organization, the EMR uses the read operation to retrieve the organization'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 Organization / Read Organization Response
Actor: FHIR Provider RESTful Client
Role: Requests a demographic details for a single organization 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 organization 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 STU3 Read operation. It makes use of the following resources:
Provider Organization Read Request
GET [base]/Organization/EPID(Logical ID)
Provider Organization Read Response
The PPR FHIR profiles are developed to constrain value sets and cardinality of data elements in the resources listed above. Since FHIR STU3 does not support all the data elements required for this project, we have introduced a few extensions which can be found here.
Extensions
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 |
|---|---|---|---|---|---|
| Organization | Read | GET | [base]/Organization/[id] | N/A | Organization response |
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 (organization) | R | R: Organization | N/A | N/A | 200,400,500 |
Organization Read Operations
This represents an HTTP GET specifying the id of a single Organization 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 an organization but does not yet have the name, contact, license and other information or wishes to retrieve an updated version of the organization's information, it invokes an Organization 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).
The FHIR Provider RESTful Server shall respond to the query request as described by the following cases and shall behave according to the cases listed below:
| Case | Scenario Description | Response |
|---|---|---|
| 1 | The PPR finds in its information source, organization whose EPID matches the id specified by the FHIR Client Application | HTTP 200 (OK) is returned as the HTTP status code. The matching Organization is returned. |
| 2 | The PPR cannot find a organization whose EPID matches the id specified by the FHIR Client Application. | HTTP 200(OK) is returned as the HTTP status code. An Empty Organization is returned. |
| 3 | PPR cannot validate the request as it does not conform to the specification. | HTTP 400(Bad Request) is returned as the HTTP status code. An OperationOutcome Resource is returned indicating an issue. The client must fix the request and try again. |
| 4 | PPR validates the request but cannot return valid response due to internal issue. | HTTP 500 (Internal Server Error) is returned as the HTTP status code. An OperationOutcome Resource is returned indicating an issue. Client should contact eHealth Ontario for trouble shooting. |
Examples
Examples of organization Read request can be found below
GET [base]/Organization/67890
Examples of a organization read response can be found below