DocumentReference Profile

This DocumentReference profile is part of the set of resource profiles supported by the API Server used with the athenaPractice 12.3 and athenaFlow 9.12 products. It further describes read, search, create and update capabilities of these products.

Overview

This resource references a document.

Scope and Usage

This profile is used to define the content that will be returned by the API Server in response to requests to access DocumentReference resources. All elements listed in the differential profile view are Supported, which means that the API Server is capable of supplying these fields from the product database when they have been populated via the product or its APIs.

The profile also defines the content that must be supplied to the API Server in response to requests to populate DocumentReference resources. Fields which are marked as Mandatory in this profile are those that must be supplied to the API Server in content used to populate a resource.

Source

The DocumentReference resource is used to access or create documents related to the patient. Content of the resource derives from the DOCUMENT table in athenaPractice and athenaFlow, and the PatientProfileAttachment and PatietVisitAttachment tables in athenaPractice. Specific detail can be found in the Mappings section in the profile detail page.

Supported Operations

The operations supported by this resource are listed below.

Read Operation

Read operations are executed as specified in the HL7 FHIR RESTful API implementation definition. To read a DocumentReference, an application shall perform an HTTP GET, specifying the identifier of the resources being retrieved.

GET [base]/fhir/DocumentReference/[id]{?_format=[json|xml]&_summary=[true|data]}

Read Operation Parameters

ParameterDescription
[base]Specifies the base URL of the FHIR Server, e.g., https://cpsapisandbox.virenceaz.com:9443/demoAPIServer
[id]Specifies the identifier of the DocumentReference resource to retrieve
[_format]Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.
[_summary]Filters the output to include only summary elements (_summary=true) or to omit the generated narrative (_summary=data). Note: If the generated html narrative for the resource is not going to be used by the call, using _summary=data provides slightly improved API response times.

Read Operation HTTP Response Codes

Response CodeDescription
200 OKThe requested resource was found and is contained within the body of the HTTP response.
401 UnauthorizedAuthorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required.
404 Not FoundThe requested resource does not exist. The body of the HTTP response will contain an OperationOutcome resource that indicates that the resource could not be found.
500 Server ErrorThe server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.

Search Operation

Search operations are executed as specified in the HL7 FHIR RESTful API implementation definition. To search for DocumentReference resources, an application shall perform an HTTP GET, specifying the query parameters associated with the resource.

GET [base]/fhir/DocumentReference?{search-parameters}{&_count=[max-results]&_format=[json|xml]&_summary=[true|text|data]}

Search Operation Parameters

ParameterDescription
[base]Specifies the base URL of the FHIR Server, e.g., https://cpsapisandbox.virenceaz.com:9443/demoAPIServer
[_count]Specifies the maximum number of search results to return in a single query. Note: The count of results does not limit the number of additional resources returned via the _include parameter. No more than max-results DocumentReference resources which match the search criteria will be returned. The API Server has default and maximum limits for the value that can be specified for this parameter. These limits may vary depending upon the client application vendors participation level in the AthenaHealth Partner program. Note: The API Server support the HL7 FHIR Paging capability.
[_format]Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.
[_summary]Filters the output to include only narrative elements (_summary=text), summary elements (_summary=true) or to omit the generated narrative (_summary=data). Note: If the generated html narrative for the resource is not going to be used by the call, using _summary=data provides improved API response times, especially when returning larger result sets.
_id (token )The ID of the resource
_lastUpdated (date )
_lastUpdated-fromnow (quantity )Like _lastUpdated except expressed as a positive or negative offset from the current time in units of time , e.g. _lastUpdated-fromnow=ge7||d for more than seven days in the future or =le-2||mo for less than two months in the past. The unit must be specified.
_security (token )
authenticator (reference )Who/what authenticated the document
author (reference )Who and/or what authored the document
class (token )Categorization of document
created (date )Document creation time
created-fromnow (quantity )Like created except expressed as a positive or negative offset from the current time in units of time , e.g. created-fromnow=ge7||d for more than seven days in the future or =le-2||mo for less than two months in the past. The unit must be specified.
custodian (reference )Organization which maintains the document
description (string )Human-readable description (title)
encounter (reference )Context of the document content
facility (token )Kind of facility where patient was seen
identifier (token )Master Version Specific Identifier
indexed (date )When this document reference created
indexed-fromnow (quantity )Like indexed except expressed as a positive or negative offset from the current time in units of time , e.g. indexed-fromnow=ge7||d for more than seven days in the future or =le-2||mo for less than two months in the past. The unit must be specified.
patient (reference )Who/what is the subject of the document
period (date )Time of service that is being documented
period-fromnow (quantity )Like period except expressed as a positive or negative offset from the current time in units of time , e.g. period-fromnow=ge7||d for more than seven days in the future or =le-2||mo for less than two months in the past. The unit must be specified.
relatesto (reference )Target of the relationship
relation (token )replaces | transforms | signs | appends
status (token )current | superseded | entered-in-error
subject (reference )Who/what is the subject of the document
type (token )Kind of document (LOINC if possible)

Search Operation HTTP Response Codes

Response CodeDescription
200 OKThe query was performed and any results found are contained within the body of the HTTP response. Note: The search API will return 200 OK when the query itself is successful, regardless of whether or not any matching results were found.
401 UnauthorizedAuthorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required.
500 Server ErrorThe server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.

Create Operation

Create operations are executed as specified in the HL7 FHIR RESTful API implementation definition. To create a new DocumentReference resource, an application must perform an HTTP POST, specifying the content of the resource in the body of the request.

POST [base]/fhir/DocumentReference?{_format=[json|xml]}

Create Operation Parameters

ParameterDescription
[_format]Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.

Create Operation HTTP Response Codes

Response CodeDescription
201 CreatedThe resource was created at the location specified in the HTTP Location header. Note: Unsupported fields will be accepted in a request but will not be persisted to the database. Some fields may be mapped to database specific codes which closely but not perfectly match the input. See the HL7 FHIR specification for more detail on server permitted changes.
400 Bad RequestThe resource could not be parsed, or failed basic validation rules. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
401 UnauthorizedAuthorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required.
422 Unprocessable EntityThe proposed resource violated server business rules. For example, a required field may be missing or a field may contain a value that is not supported by the API Server. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
500 Server ErrorThe server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.

Update Operation

Update operations are executed as specified in the HL7 FHIR RESTful API implementation definition. To create a new DocumentReference resource, an application must perform an HTTP PUT, specifying the content of the resource in the body of the request.

PUT [base]/fhir/DocumentReference/[id]?{_format=[json|xml]}

Update Operation Parameters

ParameterDescription
[_format]Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.

Update Operation HTTP Response Codes

Response CodeDescription
200 OKThe resource was updated at the location specified in the HTTP Location header. Note: Unsupported fields will be accepted in a request but will not be persisted to the database. Some fields may be mapped to database specific codes which closely but not perfectly match the input. See the HL7 FHIR specification for more detail on server permitted changes.
400 Bad RequestThe resource could not be parsed, or failed basic validation rules. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
401 UnauthorizedAuthorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required.
422 Unprocessable EntityThe proposed resource violated server business rules. For example, a required field may be missing or a field may contain a value that is not supported by the API Server. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
500 Server ErrorThe server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.

Other Operations

This Implementation guide defines 3 operations:

$generate Generate Document
$convert-cda Generate Wrapped CDA Document
$docref Argonaut Get DocumentReferences

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

Generate Document

Generate a CDA or other standards based document from resource data associated with the patient referenced by patient parameter below.

GET [base]/$generate?{operation-parameters}
In Parameters:
NameCardinalityTypeBindingProfileDocumentation
patient0..1reference

A reference to the patient for whom the document will be generated. The document will include data from this patient's record. Patient can be omitted when the patient for whom the document is being generated can be inferred from other parameters.

type0..1tokenDocument Type Value Set (Preferred )

The type of document to be generated.

class0..1tokenDocument Class Value Set (Preferred )

The document class to be generated.

format0..*tokenDocument Format Value Set (Preferred )

The format to be used when generating the document.

contentType0..1tokenMimeType (Required )

The contentType of the document to be generated.

author0..*reference

The author of the document. Must be a legal reference to a Patient or Practitioner known to the current system.

authenticator0..1reference

The legal authenticator of the document. Must be a legal reference to a Patient or Practitioner known to the current system.

encounter0..1reference

The encounter associated with the document. Must be a legal reference to an Encounter known to the current system.

order0..1reference

The referral or test order to be used when generating documents where class indicates a Transition of Care.

fromDate0..1date

Start date of the time period associated with the data elements.

toDate0..1date

End date of the time period associated with the data elements.

description0..1string

A description to include within the DocumentReference returned by this operation.

exclusions0..*uri

URIs identifing resources to exclude from the document.

persist0..1boolean

If true, the generated document will be persisted. The default if not specified is false.

securityLabel0..*token

Security tags to be associated with this docment.

raw0..1boolean

true | false

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
return1..1DocumentReference | Binary

A populated DocumentReference or Binary resource containing metadata about the document and the body of the document in the content attachment (when raw=false or is omitted), or just the body of the document (when raw=true).

The $generate operation constructs a document from resource data available for the specified subject.

 

Generate Wrapped CDA Document

Wrap the contents of this document in a CDA Header

GET [base]/$convert-cda?{operation-parameters}
In Parameters:
NameCardinalityTypeBindingProfileDocumentation
conformance0..1code Document Class Value Set (Required )

Level1 | CCDA2.1 | XDS-SD

contentType0..1code Content Type Code Value Set for $convert-cda Operation (Required )

text/plain | application/pdf | text/html

raw0..1string

true | false | body

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
return1..1DocumentReference | Binary

The returned document.

The $convert-cda operation constructs a CDA Document from the referenced content, optionally converting it to a different format (e.g., PDF, HTML or plain text). The content conforms to CDA Level 1 (a header and nonXMLBody), and may also conform to the HL7 CCDA 2.1 Unstructured Body or the IHE Scanned Document formats.

 

Argonaut Get DocumentReferences

This operation implements the $docref operation specified in the Argonaut profile of the DocumentReference Resource.

GET [base]/$docref?{operation-parameters}
In Parameters:
NameCardinalityTypeBindingProfileDocumentation
patient1..1reference

The identifier of the patient for whom to generate the CDA document.

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
return1..1DocumentReference | Binary

The resulting DocumentReference resource.

The $docref operation implements the Argonaut specified operation on DocumentReference Resource produce a CCD document for the most recent patient encounter. The resulting DocumentReference contains a link to the URL which will produce the requested content.

 

Profile Content

The official URL for this profile is:

http://hl7.org/fhir/StructureDefinition/documentreference-profile

A reference to a document

Name Flags Card. Type Description & Constraints
.. DocumentReference0..*DocumentReference A reference to a document
... meta0..1Meta Metadata about the resource
... implicitRules?! 0..1uri A set of rules under which this content was created
... language0..1code Language of the resource content

Binding: IETF BCP-47 (required )
... textI0..1Narrative Text summary of the resource, for human interpretation
... contained0..*Resource Contained, inline Resources
...documentreference-refprovid0..1Reference (Reference)Extension
.... url1..1uri "http://hl7.org/fhir/StructureDefinition/documentreference-refprovid"
.... valueReference1..1Reference (Reference)Value of extension
... extension0..1?? [UriType[http://hl7.org/fhir/StructureDefinition/documentreference-pubtime]]Extensionhttp://hl7.org/fhir/StructureDefinition/documentreference-pubtime
.... extension0..*Extension Additional Content defined by implementations
.... url1..1uri "http://hl7.org/fhir/StructureDefinition/documentreference-pubtime"
.... valueDateTime1..1dateTime Value of extension
... modifierExtension?!0..*Extension Extensions that cannot be ignored
... masterIdentifier0..1Identifier Master Version Specific Identifier
... identifierIdentifier Other identifiers for the document

Slice: Unordered, Closed, by system
... identifier0..*Identifier Other identifiers for the document
... identifier0..*Identifier Other identifiers for the document
... identifier0..*Identifier Other identifiers for the document
... subject0..1Reference (Patient )Who/what is the subject of the document
... type1..1CodeableConcept Kind of document (LOINC if possible)

Binding: Document Type Value Set (preferred )
... class0..1CodeableConcept Categorization of document

Binding: Document Class Value Set (example )
... author0..*Reference (Practitioner )Who and/or what authored the document
... custodian0..1Reference (Organization )Organization which maintains the document
... authenticator0..1Reference (Practitioner )Who/what authenticated the document
... created0..1dateTime Document creation time
... indexed1..1instant When this document reference created
... status?! 1..1code current | superseded | entered-in-error

Binding: DocumentReferenceStatus (required )
... docStatus0..1CodeableConcept preliminary | final | appended | amended | entered-in-error

Binding: CompositionStatus (required )
... relatesTo?! 0..*BackboneElement Relationships to other documents
.... extension0..*Extension Additional Content defined by implementations
.... modifierExtension?!0..*Extension Extensions that cannot be ignored
.... code1..1code replaces | transforms | signs | appends

Binding: DocumentRelationshipType (required )
.... target1..1Reference (DocumentReference )Target of the relationship
... description0..1string Human-readable description (title)
... securityLabel0..*CodeableConcept Document security-tags

Binding: All Security Labels (extensible )
... contentBackboneElement Document referenced

Slice: Unordered, Closed, by type use
... content1..3BackboneElement Document referenced
.... extension0..*Extension Additional Content defined by implementations
.... modifierExtension?!0..*Extension Extensions that cannot be ignored
.... attachment1..1Attachment Where to access the document
.... format0..*Coding Format/content rules for the document

Binding: DocumentReference Format Code Set (preferred )
... content1..*BackboneElement Document referenced
.... extension0..*Extension Additional Content defined by implementations
.... modifierExtension?!0..*Extension Extensions that cannot be ignored
.... attachment1..1Attachment Where to access the document
.... format0..*Coding Format/content rules for the document

Binding: DocumentReference Format Code Set (preferred )
... content1..*BackboneElement Document referenced
.... extension0..*Extension Additional Content defined by implementations
.... modifierExtension?!0..*Extension Extensions that cannot be ignored
.... attachment1..1Attachment Where to access the document
.... format0..*Coding Format/content rules for the document

Binding: DocumentReference Format Code Set (preferred )
... content1..*BackboneElement Document referenced
.... extension0..*Extension Additional Content defined by implementations
.... modifierExtension?!0..*Extension Extensions that cannot be ignored
.... attachment1..1Attachment Where to access the document
.... format0..*Coding Format/content rules for the document

Binding: DocumentReference Format Code Set (preferred )
... context0..1BackboneElement Clinical context of document
.... extension0..*Extension Additional Content defined by implementations
.... modifierExtension?!0..*Extension Extensions that cannot be ignored
.... encounter0..1Reference (Encounter )Context of the document content
.... event0..*CodeableConcept Main Clinical Acts Documented

Binding: v3 Code System ActCode (example )
.... period0..1Period Time of service that is being documented
.... facilityType0..1CodeableConcept Kind of facility where patient was seen

Binding: Facility Type Code Value Set (example )
.... practiceSetting0..1CodeableConcept Additional details about where the content was created (e.g. clinical specialty)

Binding: Practice Setting Code Value Set (example )
.... sourcePatientInfo0..1Reference (Patient )Patient demographics from source
.... related0..*BackboneElement Related identifiers or resources
..... extension0..*Extension Additional Content defined by implementations
..... modifierExtension?!0..*Extension Extensions that cannot be ignored
..... identifier0..1Identifier Identifier of related objects or events
..... ref0..1Reference (Resource )Related Resource


 

athenaPractice Mapping

The mappings in this section represent the how data stored within athenaPractice is served through the product's APIs. athenaPractice and athenaFlow share a common schema for patient clinical data and only one is shown when these are the same. Use of this information is subject to the the API Server Terms and Conditions.

DocumentReference Profile
DocumentReferenceDocumentReference-ProfileFHIR_DOCUMENTREFERENCEVIEW
 ├ idSDIDMakeIdWithPrefix(%ATTACHMENTID%,%ID_PREFIX%)
 ├ extensionrefprovid
 ├ extensionPUBTIME
  │ └ valueDateTimegetDateFromId(%PUBTIME%)
 ├ masterIdentifierSDIDMakeIdentifier("U",getSiteSystem("DocumentReferenceId"),%ATTACHMENTID%,%ID_PREFIX%)
 ├ identifierDocument Identifiers
 ├ identifierEXTID
 ├ identifierVISDOC
 ├ subjectPIDMakeReference("PERSON",%PID%,"Patient")
 ├ typeDESCRIPTIONMapConcept(%TYPE%,"DOCUMENTTYPE")
 ├ classMapConcept(%TYPE%,"DOCUMENTCLASS")
 ├ authorPUBUSERMakeReferenceList("USR",%AUTHOR%,"Practitioner")
 ├ custodianLOCIDMakeReference("LOCREG",%FACILITYID%,"Organization")
 ├ authenticatorPUBUSERMakeReference("USR",%USRID%,"Practitioner")
 ├ createdDB_CREATE_DATE%CREATED%
 ├ indexedDB_CREATE_DATE%CREATED%
 ├ statusXIDMapCode(%DOCREFSTATUS%,"DOCUMENTREFERENCESTATUS")
 ├ docStatusSTATUSMapConcept(%STATUS%,"DOCSTATUS")
 ├ relatesToREPLACEDBY
  │ ├ codeMapCode(%RELATESTOCODE%,"DOCUMENTRELATESTO")
  │ └ targetMakeReference("DOCUMENTREFERENCE",%RELATESTOTARGET%,"DocumentReference")
 ├ descriptionDESCRIPTION%NAME%
 ├ contentAttachments
 ├ contentInternalAttachmentMakeDocRefContentComponentForBinary(%INTREFERENCE%, %INTREFERENCEFORMAT%)
 ├ contentInternalAttachment2MakeDocRefContentComponentForBinary(%INTREFERENCE2%, %INTREFERENCEFORMAT2%)
 └ contentExternalAttachmentMakeDocRefContentComponentForExtReferencedBinaryList(%EXTREFERENCE%, %EXTREFERENCEURL%)
   ├ encounterSDIDMakeReference("DOCUMENT",%DOCUMENTID%,"Encounter")
   ├ periodCLINICALDATEMakeEMRPeriod(%CLINICALDATE%)
   ├ facilityTypeLOCNAMEMakeTextConcept(%SITE%)
   └ sourcePatientInfoPIDMakeReference("PERSON",%PID%,"Patient")

athenaFlow Mapping

The mappings in this section represent the how data stored within athenaFlow is served through the product's APIs. Use of this information is subject to the API Server Terms and Conditions .

DocumentReference Profile
DocumentReferenceDocumentReference-ProfileFHIR_DOCUMENTREFERENCEVIEW
 ├ idSDIDMakeId("DOCUMENT",%ATTACHMENTID%)
 ├ extensionrefprovid
 ├ extensionPUBTIME
  │ └ valueDateTimegetDateFromId(%PUBTIME%)
 ├ masterIdentifierSDIDMakeIdentifier("U",getSiteSystem("DocumentReferenceId"),%ATTACHMENTID%)
 ├ identifierDocument Identifiers
 ├ identifierEXTID
 ├ identifierVISDOC
 ├ subjectPIDMakeReference("PERSON",%PID%,"Patient")
 ├ typeDESCRIPTIONMapConcept(%TYPE%,"DOCUMENTTYPE")
 ├ classMapConcept(%TYPE%,"DOCUMENTCLASS")
 ├ authorPUBUSERMakeReferenceList("USR",%AUTHOR%,"Practitioner")
 ├ custodianLOCIDMakeReference("LOCREG",%FACILITYID%,"Organization")
 ├ authenticatorPUBUSERMakeReference("USR",%USRID%,"Practitioner")
 ├ createdDB_CREATE_DATE%CREATED%
 ├ indexedDB_CREATE_DATE%CREATED%
 ├ statusXIDMapCode(%DOCREFSTATUS%,"DOCUMENTREFERENCESTATUS")
 ├ docStatusSTATUSMapConcept(%STATUS%,"DOCSTATUS")
 ├ relatesToREPLACEDBY
  │ ├ codeMapCode(%RELATESTOCODE%,"DOCUMENTRELATESTO")
  │ └ targetMakeReference("DOCUMENTREFERENCE",%RELATESTOTARGET%,"DocumentReference")
 ├ descriptionDESCRIPTION%NAME%
 ├ contentAttachments
 ├ contentInternalAttachmentMakeDocRefContentComponentForBinary(%INTREFERENCE%, %INTREFERENCEFORMAT%)
 ├ contentInternalAttachment2MakeDocRefContentComponentForBinary(%INTREFERENCE2%, %INTREFERENCEFORMAT2%)
 └ contentExternalAttachmentMakeDocRefContentComponentForExtReferencedBinaryList(%EXTREFERENCE%, %EXTREFERENCEURL%)
   ├ encounterSDIDMakeReference("DOCUMENT",%DOCUMENTID%,"Encounter")
   ├ periodCLINICALDATEMakeEMRPeriod(%CLINICALDATE%)
   ├ facilityTypeLOCNAMEMakeTextConcept(%SITE%)
   └ sourcePatientInfoPIDMakeReference("PERSON",%PID%,"Patient")