From caacceaf8c19408fc4b03156998d91f6e4239604 Mon Sep 17 00:00:00 2001 From: Kennan Keim Date: Mon, 9 Oct 2023 09:06:37 -0500 Subject: [PATCH 1/7] Updated DocumentReference DSTU2 Resource - Backtick'd a lot of elements throughout the entire page, including some linked elements - Overview paragraph updated - Swapped position of the value field lists (CCD-specific section after the primary list) - Move to single disclaimer + error + outcomes callout towards the top - Adjusted the Create section to account for the "additional" HTTP 422 outcome that can occur - Implementation notes moved under parameters tables - Parameter table + Implementation notes adjustments - Mostly the "search" area that needed attention - Anonymized the x-ref ID for the Create response --- .../infrastructure/document-reference.md | 131 +++++++++--------- 1 file changed, 67 insertions(+), 64 deletions(-) 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 From 90321adccdf68cddd9161aaeaa1cdfecd5c76613 Mon Sep 17 00:00:00 2001 From: Kennan Keim Date: Mon, 9 Oct 2023 09:24:31 -0500 Subject: [PATCH 2/7] $docref Implementation notes consolidation Missed a movement for the notes under the $docref on first commit. List of notes is now consolidated under the Parameters table. --- .../dstu2/infrastructure/document-reference.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/content/millennium/dstu2/infrastructure/document-reference.md b/content/millennium/dstu2/infrastructure/document-reference.md index 478de579e..4f20da248 100644 --- a/content/millennium/dstu2/infrastructure/document-reference.md +++ b/content/millennium/dstu2/infrastructure/document-reference.md @@ -212,10 +212,6 @@ Argonaut operation for querying DocumentReferences for the supplied parameters: GET /DocumentReference/$docref?:parameters -_Implementation Notes_ - -* The [`relatesTo`] modifier element is not supported and will not be returned. - ### Authorization Types <%= authorization_types(provider: true, patient: true, system: true) %> @@ -233,7 +229,7 @@ _Implementation Notes_ `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: - It must include both a system and a code. (e.g. `&type=http://loinc.org\|34133-9`) @@ -243,7 +239,8 @@ Notes: - 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. - +- The [`relatesTo`] modifier element is not supported and will not be returned. + ### Headers From 7dc168c665b7a6eb3dee3491b2787df5c8ce8f9b Mon Sep 17 00:00:00 2001 From: Kennan Keim Date: Mon, 9 Oct 2023 10:27:19 -0500 Subject: [PATCH 3/7] typo - references -> reference --- content/millennium/dstu2/infrastructure/document-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/millennium/dstu2/infrastructure/document-reference.md b/content/millennium/dstu2/infrastructure/document-reference.md index 4f20da248..af755a0e5 100644 --- a/content/millennium/dstu2/infrastructure/document-reference.md +++ b/content/millennium/dstu2/infrastructure/document-reference.md @@ -86,7 +86,7 @@ _Implementation Notes_ - 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` + - 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. From b52efac4ed7083f59140681a197bc18e456dabae Mon Sep 17 00:00:00 2001 From: kckeim Date: Tue, 24 Oct 2023 16:48:29 -0500 Subject: [PATCH 4/7] Update document-reference.md - Made a bunch of changes at Aaron McGinn's request, as follows - Removed parenthetical suggestions around what data comes back in each field towards the top; it's out of character compared to all other resources we have pages for. - Removed Default/Maximum wording that was added for `_count` parameter. It could get changed in the APIs later without a corresponding documentation update. - Removed out-of-character link under $docref out to an Argonaut profile related to LOINC codes coming back for the `type`; we don't really need this here, since the bindings don't change between search and retrieve functions - Improved external links, and made them more visible as far as them being external tools for the XHTML validation services - added `opc-request-id` to the response for the CREATE action. Adjusted x-request-id string to match a UUID format - reworded implementation notes to be more clear - Identified a to-do around re-wording how our 422's / 500's fire with relation to unsupported fields - will discuss and fix morning of 10/25 --- .../infrastructure/document-reference.md | 36 +++++++++---------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/content/millennium/dstu2/infrastructure/document-reference.md b/content/millennium/dstu2/infrastructure/document-reference.md index af755a0e5..d04f82f68 100644 --- a/content/millennium/dstu2/infrastructure/document-reference.md +++ b/content/millennium/dstu2/infrastructure/document-reference.md @@ -17,30 +17,30 @@ References to [`implicitRules`], [`modifierExtension`], and [`relatesTo`] are NO The following fields are returned if valued for clinical documents: * [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"} +* [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"} * [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"} +* [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 (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"} +* [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 (fully qualified link to the Binary CCD)](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"} +* [ContentType and URL](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"} <%= disclaimer %> @@ -72,7 +72,7 @@ Search for DocumentReferences that meet supplied query parameters: `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. + [`_count`] | N | [`number`] | The maximum number of results to return. _Implementation Notes_ @@ -117,9 +117,6 @@ _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 `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 @@ -150,7 +147,7 @@ _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]). + - You can validate your document using any available strict XHTML 1.0 validator (eg: [W3C Markup Validation Service] or [Nu Html Checker]). ### Authorization Types @@ -192,9 +189,10 @@ 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: 111111111111111111111111111111111111 +x-request-id: 11111111-1111-1111-1111-111111111111 x-xss-protection: 1; mode=block @@ -237,9 +235,9 @@ _Implementation Notes_ - 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. -- The [`relatesTo`] modifier element is not supported and will not be returned. + - 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. +- The [`relatesTo`] modifier element is not supported for this operation, and will not be returned. ### Headers @@ -260,8 +258,8 @@ _Implementation Notes_ [`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 From 579fcde58ed3bd1cc54b607114a8a49aff78935c Mon Sep 17 00:00:00 2001 From: kckeim Date: Wed, 25 Oct 2023 12:14:42 -0500 Subject: [PATCH 5/7] Update document-reference.md Removed all call-out language specific to implicitRules, modifierExtension, and relatesTo. These fields are not listed under the CREATE section, because they're not supported, and we already have language which indicates only the listed fields are supported anyways - like all other documentation we have out there. --- .../dstu2/infrastructure/document-reference.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/content/millennium/dstu2/infrastructure/document-reference.md b/content/millennium/dstu2/infrastructure/document-reference.md index d04f82f68..ae32eb08e 100644 --- a/content/millennium/dstu2/infrastructure/document-reference.md +++ b/content/millennium/dstu2/infrastructure/document-reference.md @@ -12,7 +12,7 @@ title: DocumentReference | DSTU 2 API 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. -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. +For fields supported on write, see the [create](#create) section. The following fields are returned if valued for clinical documents: @@ -145,7 +145,6 @@ 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: [W3C Markup Validation Service] or [Nu Html Checker]). @@ -196,14 +195,6 @@ x-request-id: 11111111-1111-1111-1111-111111111111 x-xss-protection: 1; mode=block -### Errors - -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 Argonaut operation for querying DocumentReferences for the supplied parameters: @@ -237,8 +228,6 @@ _Implementation Notes_ - 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. -- The [`relatesTo`] modifier element is not supported for this operation, and will not be returned. - ### Headers @@ -255,9 +244,6 @@ _Implementation Notes_ <%= headers status: 200 %> <%= json(:dstu2_document_reference_docref_bundle) %> -[`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 [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 From 1f707e4c81effcc8c1ad9b031dcffdb7996c2df7 Mon Sep 17 00:00:00 2001 From: Aaron McGinn Date: Thu, 16 Nov 2023 11:32:07 -0600 Subject: [PATCH 6/7] Update 'ID' in document-reference.md fields Co-authored-by: Ashoka P --- content/millennium/dstu2/infrastructure/document-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/millennium/dstu2/infrastructure/document-reference.md b/content/millennium/dstu2/infrastructure/document-reference.md index ae32eb08e..09eccbedd 100644 --- a/content/millennium/dstu2/infrastructure/document-reference.md +++ b/content/millennium/dstu2/infrastructure/document-reference.md @@ -16,7 +16,7 @@ For fields supported on write, see the [create](#create) section. The following fields are returned if valued for clinical documents: -* [DocumentReference id](http://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"} +* [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"} * [Document description/title](http://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.description){:target="_blank"} From 3e9ac006913db85a9cb8034dd4c27afe9a569b40 Mon Sep 17 00:00:00 2001 From: kckeim Date: Thu, 16 Nov 2023 11:32:55 -0600 Subject: [PATCH 7/7] Formatting-related changes to standards --- .../infrastructure/document-reference.md | 74 +++++++++---------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/content/millennium/dstu2/infrastructure/document-reference.md b/content/millennium/dstu2/infrastructure/document-reference.md index ae32eb08e..b6be5fef7 100644 --- a/content/millennium/dstu2/infrastructure/document-reference.md +++ b/content/millennium/dstu2/infrastructure/document-reference.md @@ -16,31 +16,31 @@ For fields supported on write, see the [create](#create) section. The following fields are returned if valued for clinical documents: -* [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"} -* [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](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"} +* [DocumentReference ID](https://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"} +* [Subject](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"} +* [Document type](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.type){:target="_blank"} +* [Document description/title](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.description){:target="_blank"} +* [Authenticator/verifying provider](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.authenticator){:target="_blank"} +* [Create date/time](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.created){:target="_blank"} +* [Indexed date/time](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.indexed){:target="_blank"} +* [Status](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"} +* [Document status](https://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](https://hl7.org/fhir/dstu2/datatypes-definitions.html#Attachment.url){:target="_blank"} * [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"} +* [Patient encounter](https://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"} +* [DocumentReference ID](https://hl7.org/fhir/dstu2/resource-definitions.html#Resource.id){:target="_blank"} +* [Subject](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.subject){:target="_blank"} +* [Document type](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.type){:target="_blank"} +* [Index date/time](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.indexed){:target="_blank"} +* [Status](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.status){:target="_blank"} +* [Format](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.format){:target="_blank"} +* [ContentType and URL](https://hl7.org/fhir/DSTU2/documentreference-definitions.html#DocumentReference.content.attachment){:target="_blank"} <%= disclaimer %> @@ -65,14 +65,14 @@ Search for DocumentReferences that meet supplied query parameters: ### Parameters - Name | Required? | Type | Description --------------|----------------------------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - `_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. + Name | Required? | Type | Description +-------------|---------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + `_id` | Conditionally | [`token`] | The logical resource ID associated with the resource. This parameter is required if neither the `patient` nor `subject` parameters are used. Example: `_id=1234` + `patient` | Conditionally | [`reference`] | The patient to which the document reference belongs. This parameter is required if neither the `_id` nor `subject` parameters are used. Example: `patient=5678` + `subject` | Conditionally | [`reference`] | The subject of the document reference. May use the ":Patient" modifier. This parameter is required if neither the `_id` nor `patient` parameters are used. Example: `subject=Patient/91011` + `encounter` | No | [`reference`] | The encounter to which the document reference belongs. Example: `encounter=1213` + `created` | No | [`date`] | A date/time the referenced document was created. Example: `created=ge2017-01-07&created=le2017-02-05` + [`_count`] | No | [`number`] | The maximum number of results to return. _Implementation Notes_ @@ -107,9 +107,9 @@ _Implementation Notes_ <%= headers status: 200 %> <%= json(:dstu2_document_reference_docref_search) %> -## Retrieve by id +## Retrieve by ID -List an individual DocumentReference by its id: +List an individual DocumentReference by its ID: GET /DocumentReference/:id @@ -213,10 +213,10 @@ Argonaut operation for querying DocumentReferences for the supplied parameters: 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. 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` +`patient` | Yes | [`reference`] | A reference to the patient whose document references are required. Example: `patient=12345` +`type` | Yes | [`token`] | The document reference type. Example: `type=http://loinc.org\|34133-9` +`start` | No | [`date`] | The start of the date range from which document reference records should be included. Example: `start=2014-09-24T12:00:00.000Z` +`end` | No | [`date`] | The end of the date range till which document reference records should be included. Example: `end=2016-09-24T12:00:00.000Z` _Implementation Notes_ @@ -246,12 +246,12 @@ _Implementation Notes_ [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 +[`reference`]: https://hl7.org/fhir/DSTU2/search.html#reference +[`token`]: https://hl7.org/fhir/DSTU2/search.html#token +[`_count`]: https://hl7.org/fhir/dstu2/search.html#count +[`number`]: https://hl7.org/fhir/dstu2/search.html#number +[`date`]: https://hl7.org/fhir/DSTU2/search.html#date +[dateTime]: https://hl7.org/fhir/DSTU2/datatypes.html#dateTime [errors]: ../../#client-errors [`Binary`]: ../binary/#authorization-types [OperationOutcomes]: ../../#operation-outcomes