Argonaut Document Access

From HL7 Argonaut Project Wiki
Jump to: navigation, search

Back to Argonaut Implementation Guide


The latest Version of the Document Query IG has been moved to the Argonaut DSTU2 IG which is avaialable at a temporary site here: http://healthedatainc.com/go-ftp/Argo-DSTU2/structuredefinition-argo-documentreference.html It will soon be moved to a permanent site for final publishing at the end of the year.



Introduction

The Argonaut Document access Implementation Guide provides the API documentation for searching and fetching patient documents using the DocumentReference Resource. It is loosely based on the use case ITI-68 in IHE MHD specification. The search criteria provided in the Quick Start are intended to meet the 2015 Edition ONC Certification criterion § 170.315(g)(9) (Application Access—All Data Request) requirement

Minimum Requirements

Clients

Question for discussion what is SHALL vs SHOULD level of support?

  • parameters:
    • patient id
    • type of document (most commonly CCD but can be other types as well)
      • behavior if no type - Server SHALL return at least CCD if available but May provide references to other document types as well.
    • date - clinically relevent period - DocumentReference.context.period
      • Behavoir if date range - any document that falls within the date range
      • Behavior if no date = last encounter



Precondition 1:

There is pre-existing index or set of references to a patient documents.

narrowest search:

  • A client has connected to a server and fetched references to documents for a patient searched by type and date using either:

GET [base]/DocumentReference?patient=[id]&type=[type]&period=[date]

broadest search:

Precondition 2:

The references may be created "on-the-fly". In other words there MAY NOT be pre-existing indices or set of references to a patient documents for example the documents themselves may not exist but can be generated when needed.

  • use an operation `$get-docref` similar to the Get Everything operation but limiting to DocRef
  • in parameters = patient id, start date, end date, type
  • out parameter = returns search set bundle containing 0 to many Argonaut DocumentReference profiles.
  • what is does:
    • standard GET like above if document reference already exists
    • creates a document reference ( URL ) for either a) an existing non-indexed document or b) an "on-demand" document
    • return empty bundle if no documents or "on-demand" documents


narrowest search:

  • A client has connected to a server and fetched references to documents for a patient searched by type and date using either:

GET [base]/DocumentReference/$get-docref?patient=[id]&start=[date]&end=[end]&type=[type]

broadest search:

Servers

pending based on client search requirements

  • A server has ensured that every API request includes a valid Authorization token, supplied via:Authorization: Bearer {server-specific-token-here}
  • A server has rejected any unauthorized requests by returning an HTTP 401 Unauthorized response code.

By default, servers will only return current documents.

Mandatory Data Elements

The following data-elements are mandatory (i.e data MUST be present). These are presented below in simple human-readable explanation and a more thorough formal summary of the requirements. Sample data is provided to demonstrate the requirements.

Each DocumentReference must have:

  1. an identifier for the document
  2. a patient
  3. a code describing the type of document
  4. when the reference was created
  5. a status
  6. an https address where the document can be retrieved
  7. a code identifying the specific details about the format of the document — over and above the content's MIME type


In addition it should have:

  1. a document creation date

For discussion: what about the context.period ( see example )?


Formal Summary of the Mandatory Requirements

  1. One identifier in DocumentReference.masterIdentifier
  2. One reference to a patient in DocumentReference.subject
  3. One document type code in DocumentReference.type which is bound to Document Type Value Set
  4. One dateTime value in DocumentReference.indexed
  5. One status in DocumentReference.status
  6. One url of the document in DocumentReference.content.attachment
    • a mime type in DocumentReference.content.attachment.contentType which is bound to MimeType value set (code set)
    • a url* of the document in DocumentReference.content.attachment.url
  7. One format code in DocumentReference.content.format with an extensible binding to DocumentReference Format Code Set



*Note:

  • this address may refer to a FHIR Binary Resource (i.e. [base]/Binary/[id]) address on the server
  • this address may have a parameter that identifies the patient e.g. GET [url]?patient=. Argonaut servers SHOULD not require this parameter, but SHALL allow it to be provided, and SHALL check that it is correct if it is provided (IHE compatibility reasons)
DocumentReference Resource Example


Quick Start


Below is a quick overview of the required search and read operations.

GET [base]/DocumentReference/id

'Support: Mandatory to read a single DocumentReference

Implementation Notes: Fetches a DocumentReference resource by id (how to access a single resource).

Response Class:

  • (Status 200): successful operation
  • (Status 400): invalid parameter
  • (Status 401/4xx): unauthorized request
  • (Status 403): insufficient scope
  • (Status 404): Not Found

Example:

[GET https://fhir-open-api-dstu2.smarthealthit.org/DocumentReference/1-note]

GET [base]/DocumentReference?patient=[id]

Support: Mandatory to support search by patient.

Implementation Notes: Search for all documents for a patient. Fetches a bundle of all DocumentReference resources for the specified patient (how to search by reference).

Response Class:

  • (Status 200): successful operation
  • (Status 400): invalid parameter
  • (Status 401/4xx): unauthorized request
  • (Status 403): insufficient scope

Example:

[GET https://fhir-open-api-dstu2.smarthealthit.org/DocumentReference?patient=2169591]

Open Issues

Issues for this IG have been identified and tracked HERE

todo - fix examples and links

Resources

Formalized testing with test scripts and objective results reporting is available through the participation of AEGIS and MITRE (Crucible). The testscript provided can be used to test servers: [todo]

References

Back to Argonaut Implementation Guide

Copyright © Health Level Seven International ® ALL RIGHTS RESERVED. The reproduction of this material in any form is strictly forbidden without the written permission of the publisher.