Profiles & Operations Index > Operation: Retrieve Patient Summary
Operation: Retrieve Patient Summary
The Retrieve Patient Summary operation is an HTTP GET request to retrieve a specified Patient Summary document bundle. This operation is expected to follow a Search Patient Summary operation; Retrieve Patient Summary will then be used to access the desired Patient Summary bundle.
Scope
This transaction involves a request by an Ontario Patient Summary Document Consumer for a specified Patient Summary Bundle. This may be a request for the current version of the Patient Summary Bundle (Read) or a specific past version of that same Patient Summary Bundle (vRead). In both cases, the desired Bundle is identified by the target server's record ID for that Patient Summary Bundle. The request is received by the Ontario Patient Summary Responder which returns the requested record.
For example, an Electronic Medical Record (EMR) user finds a list of available Patient Summary documents for a patient (Search Patient Summary). Based on this list, the EMR user selects an individual Patient Summary document to view, and the EMR uses the ID of the desired Patient Summary to retrieve it from the repository for display.
Note: the PS-ON Document Consumer is not expected to consume and store data from the patient summary into discrete fields within the application. This specification does not define how the patient summary should be stored and/or integrated into the PS-ON Document Consumer once it has been retrieved.
Interaction Diagram
Actor: Ontario Patient Summary Document Consumer
Role: Requests a specific Patient Summary document bundle based on a known resource ID from the Ontario Patient Summary Document Responder.
Actor: Ontario Patient Summary Document Responder
Role: Returns a specific Patient Summary document bundle corresponding to the resource ID specified by the Ontario Patient Summary Document Consumer.
Specification
This specification is based on the FHIR R4 Read and vRead operations.
Patient Summary Retrieve Request
The Read operation will return a Bundle resource containing the Patient Summary Composition and linked resources.
GET [base]/Bundle/[id]
Patient Summary Retrieve Response
- Bundle (PS-ON)
- OperationOutcome
Patient Summary Version-Specific Retrieve Request
The vRead request will return a Bundle resource containing a specific past version of a Patient Summary Composition and linked resources, corresponding to the specified version ID (vid):
GET [base]/Bundle/[id]/_history/[vid] {?_format=[mime-type]}
Patient Summary Version-Specific Retrieve Response
- Bundle (PS-ON)
- OperationOutcome
Example Read Query
Retrieve a Patient Summary Bundle With Specified ID
[base]/Bundle/PSON-example-Bundle-01
Example Read Response
{
"resourceType": "Bundle",
"id": "PSON-example-Bundle-01",
"identifier": {
"system": "http://ex-ps-identifier-system.org",
"value": "urn:uuid:175bd032-8b00-4728-b2dc-748bb1501aed"
},
"type": "document",
"timestamp": "2021-12-11T14:30:00+01:00",
"entry": [
{
"fullUrl": "urn:uuid:d792b9de-b97a-4319-b34c-a3fe012ddfa2",
"resource": {
"resourceType": "Composition",
"id": "d792b9de-b97a-4319-b34c-a3fe012ddfa2",
"identifier": {
"system": "urn:oid:2.16.724.4.8.10.200.10",
"value": "0c625f31-6354-4625-baaf-09e8fe26eaef"
},
"status": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "60591-5",
"display": "Patient Summary Document"
}
]
},
...
OperationOutcome & Consent Blocks
When an OperationOutcome is returned to indicate that the resource is blocked by a patient consent directive, the following elements will be populated:
- OperationOutcome.issue.severity=warning
- OperationOutcome.issue.code=suppressed (from req valueset http://hl7.org/fhir/R4/valueset-issue-type.html)
Expected Behavior
See
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 | A patient summary bundle matching the specified identifier is found. Returns the matching Patient Summary Bundle. | |||||
200 OK | A patient summary bundle matching the specified identifier is found, but a consent block is in place, preventing disclosure of patient data. Returns an OperationOutcome resource indicating that there is a consent block on the patient's record that prevents disclosure of patient data. | warning | suppressed | |||
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 | ||
404 Not Found | No Patient Summary matching the specified identifier is found. Returns an OperationOutcome resource indicating an issue. | error | not-found | |||
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 | Patient Summary 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 |