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

Retrieve PSON

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

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

Example Read Query

Retrieve a Patient Summary Bundle With Specified ID

[base]/Bundle/PSON-example-Bundle-01

Example Read Response

Link to response bundle

{
    "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"
                        }
                    ]
                },

...

When an OperationOutcome is returned to indicate that the resource is blocked by a patient consent directive, the following elements will be populated:

Expected Behavior

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 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