Sequoia Project Healthcare Directory Implementation Guide
0.0.1 - CI Build

Sequoia Project Healthcare Directory Implementation Guide - Local Development build (v0.0.1). See the Directory of published versions

Introduction

The Sequoia Project Healthcare Directory is designed to accommodate the needs of Sequoia Project initiatives.

The primary use case for the directory is the acquisition of organization-level information, including electronic end points. The Sequoia Project is a heavily engaged member of the three main organizations creating the technical standards used by the directory, including the Argonaut Project, HL7, and IHE International. Many of the characteristics of the current FHIR Provider Directory Standard for Trial Use v3 reflect Sequoia Project contributions to, and requirements of, the standard.

Please see the change logs in this documentation for information about changes to this document, and to the software and operations described by this document.

Conventions Used

XML examples in this documentation use the following formatting convention:

Text to be entered at a terminal uses the following formatting convention:

curl -X GET “https://server.com/abc”

Source code in this documentation use the following formatting convention:

if (x) puts “here” else puts “in else” end

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and”OPTIONAL” in this document are to be interpreted as described in IETF RFC 2119 which currently can be found at the URL: https://www.ietf.org/rfc/rfc2119.txt

Conformance statements use the following formatting convention:

CONF: Testable assertion text.

Carequality Background

For Carequality, the directory is the authoritative representation of the Carequality community of Implementers and their Connections.

eHealth Exchange Background

For the eHealth Exchange, the Sequoia Healthcare Directory is the successor to the original UDDI-based directory

Summary/Roadmap

This document is intended to cover information necessary to successfully understand the approach and connect to the Sequoia Project Healthcare Directory environments. The Sequoia Project will endeavor to maintain the directory with a high degree of stability with respect to the structure of the entries and the processing model until FHIR matures. FHIR has many additional capabilities that have not been implemented this time due to lack of apparent needy by Sequoia Project initiatives. Some unimplemented features include additional query parameter support, historical version retrieval, non-directory resources, and more. The Sequoia Project welcomes feedback on additional capabilities that may help participants use the directory more effectively. Any subsequent changes to the directory will be implemented in a backward compatible manner, if possible.

Claims

This document is copyright 2017-2021 by The Sequoia Project. All rights reserved world wide.

The Sequoia Project is a registered trademark of The Sequoia Project.

HL7 is a registered trademark of Health Level Seven.

FHIR is the registered trademark of HL7 and is used with the permission of HL7.

Audience

This document is intended for software engineers, architects, configuration managers, and project managers involved with the creation, deployment, and run-time operational support of client software using The Sequoia Project Healthcare Directory. It is assumed that the reader has at least minimal exposure to the HL7 FHIR Standard for Trial Use version 3, and to directory concepts in general. Deployment teams are expected to be proficient in the curation of directory data, and have access to expertise, within their organizations, in secure deployment architectures (X.509, TLS, security best practices, etc.).

Anticipated Roadmap

The version 1.0 Healthcare Directory is anticipated to remain stable from its initial deployment until the current FHIR trial standard becomes stable and fully balloted by the HL7 community. At that point, we plan to update the Sequoia Project Healthcare Directory to version 2.0 to reflect the balloted version of the FHIR standard.

Operationally, we anticipate providing sufficient overlap between version 1.0 and 2.0 of the Sequoia Healthcare Directory to allow for a graceful migration by all those using the directory in production. Specifically Sequoia plans to operate the 1.0 provider directory for approximately 1 year after version 2.0 is put into production use. During that 1 year period of time, all users of the directory are expected to complete their migration to version 2.0. After 1 year of dual operation, the 1.0 directory will be decommissioned.

Please see the change log in this documentation for more information.

API Key

As previously mentioned, access to each directory environment requires the presentation of a valid API Key. The API key is a value that is unique to each client and for each environment. The key serves to perform several functions:

  1. It allows the Sequoia Project Healthcare Directory server to immediately, and efficiently, discard invalid queries, such as those from an unauthorized client software package.
  2. It allows for audit logging of requests.
  3. It allows the server to provide more detailed diagnostics to client applications.
  4. It allows The Sequoia Project to identify the organization associated with errant queries, excessive utilization, or other issues.

To obtain an API key please send an email to techsupport@sequoiaproject.org. Once your email has been received by the technical support system, you will automatically be assigned a ticket ID (called a conversation ID), and an automatic response will be sent to your organization to acknowledge receipt of your email. If you do not receive an automatic response, then the support system likely did not receive your support request.

One key will be needed for each environment. A key intended for VAL cannot successful be used in PROD, for example.

To present the key upon an API call to the Sequoia directory, the following syntax must be used:

GET http:///Organization/?apikey=1234

Or

GET https:///Organization/?apikey=1234

Where the value <base-url> is replaced by the value provided to you when directory access is granted, and the value 1234 is replaced by your API key value.

Design Concepts

The Sequoia Project Healthcare Directory is an implementation of the Argonaut FHIR Provider Directory work (http://argonautwiki.hl7.org/index.php?title=Implementation_Guide#Provider_Directory) and the current HL7 FHIR Standard for Trial Use v3 (STU3) version 1.8.0 http://hl7.org/fhir/directory.html which, as of the time of this writing, has incorporated the Argonaut work (with some changes). The Sequoia Projects overall approach is to leverage the base Argonaut and HL7 FHIR work, with respect to provider directory use cases and resources, with only minimal added constraints and extensions.

Theory of Operations

The directory supports an operational model by which the client software retrieves the contents of the directory quickly and efficiently using one of several recommended practices and then obtains incremental updates on a periodic basis.

Clients may include an optional query parameter indicating their preferred data format for the response (JSON vs XML), and additional parameters such as search criteria. Additional directory capabilities may be added in the future if needed by organizations using the directory, such as to support additional query parameters. A successful call results in a document returned containing a FHIR Resource or a FHIR Bundle, which contains Entries for each Organization resource with scope of the query results. A single Resource (not a Bundle) is returned for REST calls retrieving a specific resource such as Organization\1. A FHIR Bundle is returned for RESTful calls performing searches, such as?id=1. Returned Organization resources will contain general information about the entity being described, such as its general office address(es), telephone numbers, etc. The returned Organization resource will include any associated EndPoint resources as Contained resources. The EndPoint resources specify the technical web services end points for an entity listed in the directory. The Organization and EndPoint resource structures have been extended by Sequoia to meet the needs of its communities, including more detailed information than is present in the base FHIR EndPoint resource type. The extension semantics and syntactic structure are discussed in detail elsewhere in this document.

For efficiency, the client software may use HTTP cache control mechanisms to specify a retrieval of the entries, i.e. Organization resources and their children, that have been modified since a specific date/time. HTTP etags are also implemented by The Sequoia Project Provider Directory allowing for simple change detection logic. The returned document also contains embedded date/time stamps indicating the most recent update to that element.

Once the client software receives the HTTP response from the Sequoia directory, it is expected to robustly process success or failure conditions. Sample responses are presented in the Examples Section

Next Page - Environments