Implementation Guide
Contents
- 1 Introduction
- 2 Security (Authorization and Authentication)
- 3 Data Element Query
- 4 Document Query
- 5 Provider Directory
- 6 Definitions
- 6.1 Extensible binding for CodeableConcept Datatype
- 6.2 Required binding for Code and CodeableConcept Datatype
- 6.3 Using multiple codes with CodeableConcept Datatype
- 6.4 Read(Fetch) resource notation:
- 6.5 Search Syntax
- 6.6 Syntax for searches limited by patient
- 6.7 Guidance on limiting the number of search results
- 7 Reference Material
Introduction
The Argonaut Implementation Guide documents:
- Security and Authorization
- Data element query of the ONC Common Clinical Data Set (CCDS)
- Document query of static documents (such as C-CDA)
- 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.
- Patient uses provider-approved web application to access health data
- Patient uses provider-approved mobile app to access health data
- Clinician uses provider-approved web application to access health data
- Clinician uses provider-approved mobile app to access health data
- (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
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
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
- Practitioner search by demographics
- Name
- Specialty
- 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
- Organization and facility search by attributes
- Name
- Address
- 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
- Locate a Provider's Direct address
- Locate a Provider's phone or fax number at a location
- Search Practitioner by Name or Speciality
- Select appropriate Practitioner.
- 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:
- Send the resource with coded element element empty
- Use the DataAbsentReason Extension in the data type
- 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.
- base: The Service Root URL (e.g. "https://fhir-open-api-dstu2.smarthealthit.org")
- Resource-type: The name of a resource type (e.g. "Patient")
- id: The Logical Id of a resource(e.g. "24342")
- 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
- FHIR Specification
- FHIR HTTP API
- FHIR Tutorial (needs updating for technical details!)
- DAF Implementation Guide
- DAF Conformance expectations
- CCDA/FHIR Mappings
- Test Server - note: to get an account on the test server, you must complete the Argonaut Project Testing Data Use Agreement
- Resource Validation