Implementation Guide

From HL7 Argonaut Project Wiki
Jump to navigation Jump to search

Introduction

The Argonaut Implementation Guide documents:

  1. Security and Authorization
  2. Data element query of the ONC Common Clinical Data Set (CCDS)
  3. Document query of static documents (such as C-CDA)
  4. Provider Directory

The IG is based upon the core FHIR API and contains the overall Argonaut FHIR Technical Specification. This page links to resource specific pages which document the detailed conformance requirements, CRUD operations, and search critera as well as specific criteria for successful implementation for each resource.

Note that the Data element Query and Document Query IGs are based upon FHIR DSTU2.0. The Provider Directory IG is based upon the candidate STU 3.0 version.

Use Cases

This specification describes four use cases and sets search expectations for each. For complete details and background, see Use Cases for the Argonaut Project.

  1. Patient  uses  provider-approved  web  application  to  access  health  data
  2. Patient  uses  provider-­approved  mobile  app  to  access  health  data
  3. Clinician  uses  provider­-approved  web  application  to  access  health  data
  4. Clinician  uses  provider­-approved  mobile  app  to  access  health  data
  5. (future) Clinician  in  organization  A  uses  EHR  A  to  access  patient  data  in  EHR  B,  operated  by organization  B

Note, the Common MU Data Set referenced in the Use Cases is now the ONC 2015 Common Clinical Data Set (CCDS).

Security (Authorization and Authentication)

Argonaut uses SMART on FHIR authorization for apps that connect to EHR data. For details, see SMART on FHIR Authorization Guide and the Argonaut Sprint Definitions. For background material see SMART OAuth Background.

Data Element Query

Approved Argonaut design has been formalized and moved

Official Argonaut IG


The Argonaut data element query IGs are intended to meet the 2015 Edition certification criterion for Patient Selection 170.315(g)(7) and Application Access – Data Category Request 170.315(g)(8). They were created for each 2015 Edition Common Clinical Data Set. Where applicable they are based on the HL7 U.S. Data Access Framework (DAF) FHIR Implementation Guide. However, the Argonaut use case and requirements per resource are a subset of those of the DAF implementation guide.

Requirements per Resource Type

  • Allergies
  • Assessment and Plan of Treatment
  • CareTeam
  • Goals
  • Immunizations
  • Implantable Devices/UDI
  • Laboratory Results
  • Medications
  • Patient
  • Problems and Health Concerns
  • Procedures
  • Smoking Status
  • Vital Signs

Date Range Search


Document Query

Approved Argonaut design has been formalized and moved

Official Argonaut IG


For the Argonaut Document Query Implementation guide, we are focused on the provider and patient access and retrieval of a patient's existing C-CDA formats - specifically, transition of care and patient summary CCDAs required for Meaningful Use as well as other document types like PDF documents. These are exposed in FHIR using a DocumentReference Resource to index/search for them. This guide provides the minimal requirements to fetch a URL link to either a) patient's existing documents like C-CDA and other documents or b) a "virtual" documents such as a CCD that could be created "on-demand".

The Document itself can be subsequently retrieved using the link provided from the DocumentQuery search results. The link could be ,for example, a FHIR endpoint to a Binary Resource or some other document repository. The details of how to retrieve the document are not covered in this guide.

Use Case

Patient or Provider search for Documents

  • Patient ID

Example Search

  • Locate a patients CCD document from a recent or current encounter

Assumptions and Preconditions

  • Initial search for a reference to a document instead of documents itself ( retrieval of actual document is a two-step process)
  • Documents may or may not already exist and be indexed prior to the search
  • Document references may be created "on-demand" when requested
  • Documents may be created "on-demand" when requested
  • Details of document retrieval is out of scope

Requirements

  • DocumentReference

Provider Directory

Approved Argonaut design has been formalized and moved

Official Argonaut PD IG CI Build


The Argonaut project Provider Directory guide provides the foundation for a robust provider directory. It outlines the key data elements for any provider directory and basic query guidance for 4 use cases.

The requirements for the Argonaut Provider Directory data model were drawn from IHE Healthcare Provider Directory and the ONC Provider Directory Workshop.

Use Cases

  1. Practitioner search by demographics
    • Name
    • Specialty
  2. Practitioner search within a region (city, state)
    • Practitioner or specialty within a specified distance - 10 miles from patient home
    • Show me every one of this specialty in the city
  3. Organization and facility search by attributes
    • Name
    • Address
  4. Practitioner search by organizational relationships
    • Practitioner in a specific health organization (e.g. Baptist Health Organization)
    • Practitioner in a specific clinic (e.g. West Clinic)

Example Searches

  1. Locate a Provider's Direct address
    1. Search Practitioner by Name or Specialty
    2. Select appropriate Practitioner
    3. Retrieve Direct address from Practitioner.role.endpoint
  2. Locate a Provider's phone or fax number at a location
    1. Search Practitioner by Name or Speciality
    2. Select appropriate Practitioner.
    3. Retrieve Practitioner.role.telecom with Patient.telecom.system=phone|fax

Assumptions and Preconditions

Electronic service information will be available when the Practitioner or Organization is returned

Additional implementation guidance on the use cases and core data elements will be required. For example:

  • Pushing updates to central directory
  • Bulk registry download

Requirements

Argonaut Provider Directory Connectathon

Definitions

Extensible binding for CodeableConcept Datatype

Extensible binding to a value set definition for this IG means that if the data type is CodeableConcept, then one of the coding values SHALL be from the specified value set if a code applies, but if no suitable code exists in the value set, alternate code(s) may be provided in its place. If only text available, then just text may be used.

Required binding for Code and CodeableConcept Datatype

Required binding to a value set definition for this IG means that one of the codes from the specified value set SHALL be used. For CodeableConcept you may have additional codings elements as translations as is discussed below. If only text is available or the local (proprietary, system) cannot be mapped to one of the required codes the The core specification provides guidance which we have summarized:

  1. Send the resource with coded element element empty
  2. Use the DataAbsentReason Extension in the data type
  3. Use the code ‘unsupported’ - The source system wasn't capable of supporting this element.

Note that is will still be ambiguous when using a status based queries

Example: AllergyIntolerance resource with a status that is text only or cannot be mapped to the status value set. 

{
  "resourceType":"AllergyIntolerance",
  ...
  "status":{ 
   "url" : "http://hl7.org/fhir/StructureDefinition/data-absent-reason", 
   "valueCode" : "unsupported" 
   ...
 },
  
}

Using multiple codes with CodeableConcept Datatype

Atlernate codes may be provided in addition to the standards codes defined in required or extensible value sets. The alternate codes are called “translations”. These translations may be equivalent to or narrower in meaning to the standard concept code.

Example of multiple translation for Body Weight concept code. 

"code": {
    "coding": [
     {
        "system": "http://loinc.org",  //NOTE:this is the standard concept defined in the value set//
        "code": "29463-7",  
        "display": "Body Weight"
      },
//NOTE:this is a translation to a more specific concept
     {
        "system": "http://loinc.org",
        "code": "3141-9", 
        "display": "Body Weight Measured"
      },
//NOTE:this is a translation to a different code system (Snomed CT)  
     {
        "system": "http://snomed.info/sct",
        "code":  “364589006”,
        "display": "Body Weight"
      }
//NOTE:this is a translation to a locally defined code
     {
        "system": "http://AcmeHealthCare.org",
        "code":  “BWT”,
        "display": "Body Weight"
      }
    ],
    "text": "weight"
  },

Example of translation of NDC vaccine code to CVX code. 


"vaccineCode" : {
    "coding" : [
      {
        "system" : "http://hl7.org/fhir/sid/cvx",
        "code" : "158",
        "display" : "influenza, injectable, quadrivalent"
      },
      {
        "system" : "http://hl7.org/fhir/sid/ndc",
        "code" : "49281-0623-78",
        "display" : "FLUZONE QUADRIVALENT"
      }
    ]
  },

Read(Fetch) resource notation:

The interactions on IG page are defined like this: 

 GET [base]/[Resource-type]/[id] {parameters}
  • GET is the HTTP verb used for fetching a resource
  • Content surrounded by [] is mandatory, and will be replaced by the string literal identified.
  • Content surrounded by {} is optional
    • parameters: URL parameters as defined for the particular interaction (e.g."?_format=xml"}

For more information see the FHIR RESTful API

Search Syntax

In the simplest case, a search is executed by performing a GET operation in the RESTful framework: 

GET [base]/[Resource-type]?name=value&...

For this RESTful search (see definition in RESTful API), the parameters are a series of name=[value] pairs encoded in the URL. The search parameter names are defined for each resource. For example the Observation resource the name "code" for search on the LOINC code. See Searching for more information about searching in REST, messaging, and services.

Syntax for searches limited by patient

There are three ways to search for resources associated with a specific patient depending on the context and implementation. These three searches result in the same outcome.:

1. An explicitly defined patient that controls which set of resources are being searched by resource type: 

GET [base]/[Resource-type]?patient=24342{&other parameters}

Note that all the search interactions in this IG are published using the above syntax.

However there are several variations to this syntax: (see Issue #39)

  • GET [base]/[Resource-type]?Subject=[id]{&other parameters}
  • GET [base]/[Resource-type]?Subject=Patient/[id]{&other parameters}
  • GET [base]/[Resource-type]?Subject._id=[id]{&other parameters}
  • GET [base]/[Resource-type]?subject:Patient=[id]{&other parameters}
  • GET [base]/[Resource-type]?subject:Patient=Patient/[id]{&other parameters}
  • GET [base]/[Resource-type]?subject:Patient=https://[url]/Patient/id{&other parameters}
  • GET [base]/[Resource-type]?subject:Patient._id=[id]{&other parameters}
  • GET [base]/[Resource-type]?patient:Patient=https://[url]/Patient/id{&other parameters}

2. if the patient is implicit in the context (e.g. UC-1 above or using SMART), then this search applies: 

GET [base]/[Resource-type]?other-parameters

NOTE:

  • Patient compartment based search with a specified resource type in that compartment is not suported for this IG.
  • In addition, Argonaut servers will not resolve full URLs that are external to their environment.

Guidance on limiting the number of search results

In order to manage the number of search results returned, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. For a simple RESTful search, the page links are contained in the returned bundle as links. See the core specification for more information

Reference Material

Retrieved from "https://argonautwiki.hl7.org/w/index.php?title=Implementation_Guide&oldid=2108"