R6 Ballot (2nd Draft)

Publish-box (todo)

10.2.11.2 Operation $docref on DocumentReference

Orders and Observations icon Work Group Maturity Level: 3Trial Use Compartments: N/A

This operation is used to return all the references to documents related to a patient.

The operation requires a patient id and takes the optional input parameters:

  • start date

  • end date

  • document type

  • on demand

  • profile

and returns a Bundle of type "searchset" containing DocumentReference resources for the patient. If the server has or can create documents that are related to the patient, and that are available for the given user, the server returns the DocumentReference resources needed to support the records. The principle intended use for this operation is to provide a provider or patient with access to their available document information.

This operation is different from a search by patient and type and date range because:

  1. It is used to request a server to generate a document based on the specified parameters.

  2. If no parameters are specified, the server SHALL return a DocumentReference to the patient's most current summary

  3. If the server cannot generate a document based on the specified parameters, the operation will return an empty search bundle.

Unless the client indicates they are only interested in 'on-demand' documents using the on-demand parameter, the server SHOULD return DocumentReference instances for existing documents that meet the request parameters. In this regard, this operation is similar to a FHIR RESTful query.

The canonical URL for this operation definition is

 http://hl7.org/fhir/OperationDefinition/DocumentReference-docref

Formal Definition (as a OperationDefinition).

URL: [base]/DocumentReference/$docref

This is not an idempotent operation

In Parameters:
Name Scope Cardinality Type Binding Profile Documentation
patient 1..1 id

The id of the patient resource located on the server on which this operation is executed. If there is no match, an empty Bundle is returned

start 0..1 dateTime

The date range relates to care dates, not record currency dates - e.g. all records relating to care provided in a certain date range. If no start date is provided, all documents prior to the end date are in scope. If neither a start date nor an end date is provided, the most recent or current document is in scope. The client SHOULD provide values precise to the second + time offset.

end 0..1 dateTime

The date range relates to care dates, not record currency dates - e.g. all records relating to care provided in a certain date range. If no end date is provided, all documents subsequent to the start date are in scope. If neither a start date nor an end date is provided, the most recent or current document is in scope. The client SHOULD provide values precise to the second + time offset.

type 0..1 CodeableConcept FHIR Document Type Codes (Required)

The type relates to document type e.g. C-CDA Clinical Summary of Care (CCD) = LOINC 34133-9: Summary of episode note, and International Patient Summary (IPS) = LOINC 60591-5: Patient summary document. If no type is provided, the summary document, if available, SHALL be in scope, and all other document types MAY be in scope. It is at the server's discretion how to respond if multiple types are provided. The server MAY return documents to any of the specified types. The server's CapabilityStatement should document its behavior and what types it supports

on-demand 0..1 boolean

This on-demand parameter allows client to dictate whether they are requesting only 'on-demand' or both 'on-demand' and 'stable' documents (or delayed/deferred assembly) that meet the query parameters

profile 0..* canonical

This parameter allows the client to request documents according to a specific profile using the profile's canonical reference. It is at the server's discretion how to respond if multiple profiles are provided. The server MAY return documents to any of the specified profiles. The server's CapabilityStatement should document its behavior and what profiles it supports.

Out Parameters:
Name Scope Cardinality Type Binding Profile Documentation
return 1..1 Bundle

The bundle type is "searchset"containing DocumentReference resources.

Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

The server either returns a search result Bundle containing at least one DocumentReference, or it returns an error.

10.2.11.2.1 Examples

Request: Example of $docref on a DocumentReference


POST /open/DocumentReference/$docref
[some headers]

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
      "name": "patient",
  	  "valueId": "Patient/example"
    },
    {
      "name": "on-demand",
      "valueBoolean": "true"
    }
  ]
}

Response: Results from $docref


HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "Bundle",
  "id": "26419249-18b3-45de-b10e-dca0b2e72b",
  "meta": {
    "lastUpdated": "2012-03-18T03:28:49Z"
  },
  "type": "searchset",
  "total": 1,
  "entry": [{
    "fullUrl": "http://server/path/DocumentReference/example",
    "resource": {
      "resourceType": "DocumentReference",
      "id": "example",
      .. snip ...
    }
  }]
}

 

For more information about operations, including how they are invoked, see Operations.