diff --git a/content/millennium/dstu2/infrastructure/document-reference.md b/content/millennium/dstu2/infrastructure/document-reference.md index 5bd4fbfeb..478de579e 100644 --- a/content/millennium/dstu2/infrastructure/document-reference.md +++ b/content/millennium/dstu2/infrastructure/document-reference.md @@ -9,19 +9,10 @@ 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. -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"} +Additionally, this resource supports writing an unstructured document. +References to [`implicitRules`], [`modifierExtension`], and [`relatesTo`] are NOT supported and will fail a create request. For fields supported on write, see the [create](#create) section. The following fields are returned if valued for clinical documents: @@ -41,6 +32,23 @@ The following fields are returned if valued for clinical documents: * [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 (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"} + + +<%= disclaimer %> + +### Errors + +The common [errors] and [OperationOutcomes] may be returned. + ## Terminology Bindings <%= terminology_table(:document_reference, :dstu2) %> @@ -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) %> @@ -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. Defaults to `10` and a maximum of `100` documents can be returned. -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 references, 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. @@ -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: @@ -108,8 +115,11 @@ 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. +- If no mappings are available for LOINC codes when returning `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. ### Authorization Types @@ -130,12 +140,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. @@ -144,8 +148,9 @@ 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]). +- 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]). ### Authorization Types @@ -189,21 +194,19 @@ strict-transport-security: max-age=631152000 vary: Origin,User-Agent,Accept-Encoding x-content-type-options: nosniff x-frame-options: SAMEORIGIN -x-request-id: 9c7510c0-0bb5-4148-b37e-51a774c4091b +x-request-id: 111111111111111111111111111111111111 x-xss-protection: 1; mode=block -<%= disclaimer %> - ### Errors -The common [errors] and [OperationOutcomes] may be returned. Additional [OperationOutcomes] may be returned in the following scenarios: +In addition to the common [OperationOutcomes], the following Outcome can be returned for this operation: HTTP Status | Cause | Severity | Code -------------|------------------------------------|-----------|--------------- 422 | Body contained relatesTo | error | not-supported -## Operation: docref +## Operation: $docref Argonaut operation for querying DocumentReferences for the supplied parameters: @@ -211,7 +214,7 @@ Argonaut operation for querying DocumentReferences for the supplied parameters: _Implementation Notes_ -* The [DocumentReference.relatesTo] modifier element is not supported and will not be returned. +* The [`relatesTo`] modifier element is not supported and will not be returned. ### Authorization Types @@ -226,14 +229,21 @@ _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: -- 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 records from the beginning of time are included. + - If `end` is not provided, then all records up to the current date are included. + ### Headers @@ -250,15 +260,9 @@ 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 +[`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 [`reference`]: http://hl7.org/fhir/DSTU2/search.html#reference @@ -267,7 +271,6 @@ The common [errors] and [OperationOutcomes] may be returned. [`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