Skip to content
This repository has been archived by the owner on May 7, 2024. It is now read-only.

Updated DocumentReference DSTU2 Resource #998

Merged
merged 8 commits into from
Nov 16, 2023
Merged

Updated DocumentReference DSTU2 Resource #998

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
caaccea
Updated DocumentReference DSTU2 Resource
kckeim Oct 9, 2023
90321ad
$docref Implementation notes consolidation
kckeim Oct 9, 2023
7dc168c
typo - references -> reference
kckeim Oct 9, 2023
b52efac
Update document-reference.md
kckeim Oct 24, 2023
579fcde
Update document-reference.md
kckeim Oct 25, 2023
1f707e4
Update 'ID' in document-reference.md fields
amcginn Nov 16, 2023
3e9ac00
Formatting-related changes to standards
kckeim Nov 16, 2023
54e6852
Merge branch 'DocumentReferenceDSTU2-docs-migrate' of https://github.…
kckeim Nov 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 64 additions & 80 deletions content/millennium/dstu2/infrastructure/document-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,38 +9,46 @@ title: DocumentReference | DSTU 2 API

## Overview

The DocumentReference resource is used to reference a clinical document for a patient within the health system. This resource supports reading Continuity of Care Documents (CCD), returning a list of clinical documents, and a reference to retrieve a document as a PDF. Additionally, this resource supports writing an unstructured document. References to implicitRules, relatesTo, and modifierExtensions are NOT supported and will fail a create request.
The DocumentReference resource is used to reference a clinical document for a patient within the health system. This resource supports reading Continuity of Care Documents (CCD), returning a list of clinical documents, and a reference to retrieve a document as a PDF. When retrieving document links and metadata, this resource will refer to the [`Binary`] resource for downloading the complete document.

Additionally, this resource supports writing an unstructured document.
For fields supported on write, see the [create](#create) section.

The following fields are returned if valued for the docref operation (CCD read):

* [DocumentReference id](http://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"}
* [Subject (patient)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"}
* [Document type](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.type){:target="_blank"}
* [Index date/time (when document reference created)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.indexed){:target="_blank"}
* [Status (current)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"}
* [Format](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.format){:target="_blank"}
* [ContentType and URL (fully qualified link to the Binary CCD)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"}

The following fields are returned if valued for clinical documents:

* [DocumentReference id](http://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"}
amcginn marked this conversation as resolved.
Show resolved Hide resolved
* [Subject (patient)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"}
* [Subject](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"}
* [Document type](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.type){:target="_blank"}
* [Document description/title](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.description){:target="_blank"}
* [Authenticator/verifying provider](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.authenticator){:target="_blank"}
* [Create date/time](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.created){:target="_blank"}
* [Indexed date/time](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.indexed){:target="_blank"}
* [Status (typically current)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"}
* [Document status (typically final or amended)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.docStatus){:target="_blank"}
* [Status](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"}
* [Document status](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.docStatus){:target="_blank"}
* [Content](https://hl7.org/fhir/dstu2/documentreference-definitions.html#DocumentReference.content){:target="_blank"}
* [Attachment](https://hl7.org/fhir/dstu2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"}
* [Content type](https://hl7.org/fhir/dstu2/datatypes-definitions.html#Attachment.contentType){:target="_blank"}
* [URL (fully qualified link to the document)](https://hl7.org/fhir/dstu2/datatypes-definitions.html#Attachment.url){:target="_blank"}
* [URL](https://hl7.org/fhir/dstu2/datatypes-definitions.html#Attachment.url){:target="_blank"}
amcginn marked this conversation as resolved.
Show resolved Hide resolved
* [Title](https://hl7.org/fhir/dstu2/datatypes-definitions.html#Attachment.title){:target="_blank"}
* [Patient encounter](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.context.encounter){:target="_blank"}

The following fields are returned if valued for the $docref operation (CCD read):

* [DocumentReference id](http://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"}
* [Subject](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"}
* [Document type](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.type){:target="_blank"}
* [Index date/time](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.indexed){:target="_blank"}
* [Status](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"}
* [Format](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.format){:target="_blank"}
* [ContentType and URL](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"}


<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

## Terminology Bindings

<%= terminology_table(:document_reference, :dstu2) %>
Expand All @@ -51,11 +59,6 @@ Search for DocumentReferences that meet supplied query parameters:

GET /DocumentReference?:parameters

_Implementation Notes_

* Search results are currently limited to published clinical documents.
* Contents of the document are found by following the Attachment URL. See more information on the [Binary resource] to determine what Authorization scopes are required, and how to set the Accept header when downloading document contents.

### Authorization Types

<%= authorization_types(provider: true, patient: true, system: true) %>
Expand All @@ -64,17 +67,27 @@ _Implementation Notes_

Name | Required? | Type | Description
-------------|----------------------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`_id` | This, or one of `patient` or `subject` | [`token`] | The logical resource id associated with the resource. Example: `_id=7891`
`patient` | This, or one of `_id` or `subject` | [`reference`] | The patient to which the document reference belongs. Example: `patient=12345`
`subject` | This, or one of `_id` or `patient` | [`reference`] | The subject of the document reference. Must represent a Patient resource. May use the :Patient modifier. Example: `subject=Patient/12345 or subject:Patient=12345`
`encounter` | No | [`reference`] | The encounter to which the document reference belongs. Must represent an Encounter resource. May include a single or comma separated list of references. Example: `encounter=4567`
`created` | No | [`date`] | A date/time the referenced document was created. Must use the `ge` and `le` prefixes. Example: `created=ge2017-01-07&created=le2017-02-05`
[`_count`] | No | [`number`] | The maximum number of results to return.
`_id` | This, or one of `patient` or `subject` | [`token`] | The logical resource id associated with the resource. Example: `12345`
`patient` | This, or one of `_id` or `subject` | [`reference`] | The patient to which the document reference belongs. Example: `12345`
`subject` | This, or one of `_id` or `patient` | [`reference`] | The subject of the document reference. May use the :Patient modifier. Example: `Patient/12345`
`encounter` | N | [`reference`] | The encounter to which the document reference belongs. Example: `12345`
`created` | N | [`date`] | A date/time the referenced document was created. Example: `created=ge2017-01-07&created=le2017-02-05`
[`_count`] | N | [`number`] | The maximum number of results to return.

Notes:
_Implementation Notes_

- The `_id` parameter may not be provided at the same time as the `patient`, `subject`, `encounter`, `created`, or `_count` parameters.
- When the `created` parameter is provided:
- Search results are currently limited to published clinical documents.
- Contents of the document are found by following the Attachment URL.
- See more information on the [`Binary`] resource to determine what Authorization scopes are required, and how to set the `Accept` header when downloading document contents.
- When searching with the `_id` parameter:
- It must not be provided with any other parameters.
- When searching with the `subject` parameter:
- It must appear once, and must represent a Patient resource.
- It can be provided either with or without the :Patient modifier. Example: `subject=Patient/12345` or `subject:Patient=12345`
- When searching with the `encounter` parameter:
- It must appear once, and must represent an Encounter resource.
- It can be provided with either a single reference, or a comma-separated list of references. Example `encounter=1234` or `encounter=1234,5678`
- When searching with the `created` parameter:
- It must be provided twice, once with the `ge` parameter and once with the `le` parameter.
- The two provided date/times may not be equal and must form a closed range.
- If one `created` parameter includes a time, both must include a time.
Expand All @@ -94,12 +107,6 @@ Notes:
<%= headers status: 200 %>
<%= json(:dstu2_document_reference_docref_search) %>

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

## Retrieve by id

List an individual DocumentReference by its id:
Expand All @@ -108,8 +115,8 @@ List an individual DocumentReference by its id:

_Implementation Notes_

* Contents of the document are found by following the Attachment URL. See more information on the [Binary resource] to determine what Authorization scopes are required, and how to set the Accept header when downloading document contents.
* If no mappings are available for LOINC codes when returning DocumentReference.type codings, an unknown data absent reason will be returned in place of the LOINC codes. This is to follow the [Argonaut profile's](http://www.fhir.org/guides/argonaut/r2/StructureDefinition-argo-documentreference.html) required binding for type. When available, Proprietary codings will be returned in addition to the data absent reason.
- Contents of the document are found by following the Attachment URL.
- See more information on the [`Binary`] resource to determine what Authorization scopes are required, and how to set the `Accept` header when downloading document contents.

### Authorization Types

Expand All @@ -130,12 +137,6 @@ _Implementation Notes_
<%= headers status: 200 %>
<%= json(:dstu2_document_reference_docref_bundle_entry) %>

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

## Create

Create new documents. Currently limited to unstructured clinical notes or documentation. For example, a document with display formatting or styling can be written, but a CCD cannot.
Expand All @@ -144,8 +145,8 @@ Create new documents. Currently limited to unstructured clinical notes or docume

_Implementation Notes_

* The modifier elements [implicitRules], [modifierExtension] and [relatesTo] are not supported and will be rejected if present.
* Currently only XHTML formatted documents are supported. You can validate your document using any available strict XHTML 1.0 validator (eg: [w3 validator] or this [html5 validator]).
- Currently only XHTML formatted documents are supported.
- You can validate your document using any available strict XHTML 1.0 validator (eg: [W3C Markup Validation Service] or [Nu Html Checker]).

### Authorization Types

Expand Down Expand Up @@ -187,32 +188,19 @@ cache-control: no-cache
location: https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference/5789254
strict-transport-security: max-age=631152000
vary: Origin,User-Agent,Accept-Encoding
opc-request-id: /11111111111111111111111111111111/11111111111111111111111111111111
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-request-id: 9c7510c0-0bb5-4148-b37e-51a774c4091b
x-request-id: 11111111-1111-1111-1111-111111111111
x-xss-protection: 1; mode=block
</pre>
amcginn marked this conversation as resolved.
Show resolved Hide resolved

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned. Additional [OperationOutcomes] may be returned in the following scenarios:

HTTP Status | Cause | Severity | Code
-------------|------------------------------------|-----------|---------------
422 | Body contained relatesTo | error | not-supported

## Operation: docref
## Operation: $docref
amcginn marked this conversation as resolved.
Show resolved Hide resolved

Argonaut operation for querying DocumentReferences for the supplied parameters:

GET /DocumentReference/$docref?:parameters

_Implementation Notes_

* The [DocumentReference.relatesTo] modifier element is not supported and will not be returned.

### Authorization Types

<%= authorization_types(provider: true, patient: true, system: true) %>
Expand All @@ -226,14 +214,20 @@ _Implementation Notes_
Name | Required? | Type | Description
----------|-----------|---------------|-------------------------------------------------
`patient` | Y | [`reference`] | A reference to the patient whose document references are required. Example: `12345`
`type` | Y | [`token`] | The document reference type, can be a list of comma separated values. Example: `http://loinc.org|34133-9`
`start` | N | [`date`] | The start of the date range from which document reference records should be included. If not provided, then all records from the beginning of time are included. Example: `2014-09-24T12:00:00.000Z`
`end` | N | [`date`] | The end of the date range till which document reference records should be included. If not provided, then all records up to the current date are included. Example: `2016-09-24T12:00:00.000Z`
`type` | Y | [`token`] | The document reference type. Example: `http://loinc.org\|34133-9`
`start` | N | [`date`] | The start of the date range from which document reference records should be included. Example: `2014-09-24T12:00:00.000Z`
`end` | N | [`date`] | The end of the date range till which document reference records should be included. Example: `2016-09-24T12:00:00.000Z`

Notes:
_Implementation Notes_

- The `type` parameter must include both a system and a code. (e.g. `&type=http://loinc.org|34133-9`)
- The `start` and `end` parameters must be valid [dateTime]s with a time component. They must have prefixes of `eq` or nothing.
- The `type` parameter:
- It must include both a system and a code. (e.g. `&type=http://loinc.org\|34133-9`)
- It may be a single system and code, or a comma-separated list.
- The `start` and `end` parameters:
- They must be valid [dateTime]s with a time component.
- They must have prefixes of `eq` or nothing.
- If `start` is not provided, then all previous records up to the `end` date are included.
- If `end` is not provided, then all records between the `start` date and the current date are included.

### Headers

Expand All @@ -250,24 +244,14 @@ Notes:
<%= headers status: 200 %>
<%= json(:dstu2_document_reference_docref_bundle) %>

<%= disclaimer %>

### Errors

The common [errors] and [OperationOutcomes] may be returned.

[implicitRules]: http://hl7.org/fhir/DSTU2/resource-definitions.html#Resource.implicitRules
[modifierExtension]: http://hl7.org/fhir/DSTU2/domainresource-definitions.html#DomainResource.modifierExtension
[relatesTo]: http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.relatesTo
[html5 validator]: https://html5.validator.nu/
[w3 validator]: http://validator.w3.org/#validate_by_upload+with_options
[Nu Html Checker]: https://html5.validator.nu/
[W3C Markup Validation Service]: https://validator.w3.org/#validate_by_upload+with_options
[`reference`]: http://hl7.org/fhir/DSTU2/search.html#reference
[`token`]: http://hl7.org/fhir/DSTU2/search.html#token
[`_count`]: http://hl7.org/fhir/dstu2/search.html#count
[`number`]: http://hl7.org/fhir/dstu2/search.html#number
[`date`]: http://hl7.org/fhir/DSTU2/search.html#date
[dateTime]: http://hl7.org/fhir/DSTU2/datatypes.html#dateTime
[DocumentReference.relatesTo]: http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.relatesTo
[errors]: ../../#client-errors
[Binary resource]: ../binary/#authorization-types
[`Binary`]: ../binary/#authorization-types
[OperationOutcomes]: ../../#operation-outcomes
Loading