0.0.1 - CI Build

SequoiaProjectHealthcareDirectoryImplementationGuideSTU3 - Local Development build (v0.0.1). See the Directory of published versions

Operational Best Practices

Previous Page - Detailed Workflow Example

Background

This section documents recommended practices for use of the directory by client software. The FHIR standard provides a significant discretion to the directory implementer and thus this section serves to provide guidance in this regard.

Carequality Directory Data Quality

Carequality Implementers are specifically responsible for submitting complete and accurate information about any Carequality Implementer or Connections entities that they wish to include in the Healthcare Directory.

eHealth Exchange Directory Data Quality

eHealth Exchange Participants are specifically responsible for submitting complete and accurate information about any entities that they wish to include in the Healthcare Directory.

Bulk Directory Acquisition

To obtain a copy of the entire directory client software can retrieve the contents of the entire directory quickly and efficiently using a paging concept. To obtain the entire directory using paging, the RESTful URL should should the _start and _count query parameters to iterate through the entire directory, paging between 100 and 1000 organizations at a time. The client should continue paging until it receives no more directory entries or until the returned count is less than the specific count (both of which signal that the end of the directory have been reached). Since FHIR organization.id values are constant for a given directory instance, and since Organizational resources can be deleted at any time, client software is advised to first request a count of the number of current active Organizational resources, and then continue paging through the directory until this count has been achieved. Since FHIR directories do not lock out write or update access, be advised that client software should be prepared to receive results that are different depending on other concurrent destructive operations. Alternatively, until further notice, a directory client application can obtain the entire directory by making a single GET request to the …/Organization URL. Sequoia reserves the right to suspend this type of access in the future should it become necessary for performance reasons.4.5. Directory Incremental Updates To keep the client copy of the directory updated, the best practice is for client software to first obtain the entire directory (preferably using paging) and then use the _lastUpdated URL query parameter to request a list of all entries that were created, updated or deleted between the time of the last full directory acquisition and the time of the query in question. Note that the active flag will have will be set to false in order retrieve deleted organizations. As covered elsewhere in this documentation, directory entries that are deleted are still persisted in the directory, but with a status of active=false.

Maximum Query Frequency

In order to efficiently operate the directory, and to help ensure short response times, the PROD Sequoia Project Healthcare Directory must be queried no more often than once every hour for general operational use. More frequent queries are acceptable for short periods of time if needed for PROD testing, configuration, or similar activities. CONF: The directory MUST be queried no more than once per hour for standard production operational use. Prolonged intervals of queries at a more frequent interval than once per hour may result in temporary suspension of access until the problem is remediated. The directory itself is hosted in a clustered environment that can be relatively easily scaled horizontally to ensure sufficient response times. The cluster is operationally monitored using predictive analytics and is sized with conservatively excess capacity.

Robustness, Exceptions and Reliability

Introduction

The provider directory is implemented in such a way that all client access operations CAN be robust, if the client software follows rules as discussed in this section. Robustness requires that both the directory client software and the directory server software adhere to known practices. These practices are covered in this section.

Reliability

All client applications should assume an operation potentially failed if they do not receive an HTTP 200 response code from the directory server. If the client software does not receive any HTTP response code, then common causes, without limit, include:

  1. The request could have succeeded and a success response code could have been generated by the directory and then lost over the Internet virtual connection before it was received by the client.
  2. The request could have failed and the error response code could have been generated by the directory and then lost over the Internet virtual connection before it was received by the client.
  3. The server could have been busy servicing a time-consuming request and not returned a result before the server exceeded a time out limit.
  4. The server could have been busy servicing a time-consuming request and not returned a result before the client exceeded a time out limit.
  5. The Internet connection could have been slow or unreliable not able to return a result before the server exceeded a time out limit.
  6. The Internet connection could have been slow or unreliable not able to return a result before the client exceeded a time out limit.
  7. The server may be temporarily unavailable, such as for scheduled or unscheduled maintenance.
  8. The maximum number of simultaneous concurrent inbound connections allowed by the server configuration could have temporarily exceeded resulting in the server rejecting the inbound connection. The client software needs to, thus, confirm proper responses are received, or retry or confirm each transactions success status, if an HTTP 200 response code is not received.

Robustness

The directory only returns HTTP response codes upon dispositioning of the inbound request. This allows for reliability as this means that messages are completely processed before the directory server returns the appropriate HTTP response code. In the case of create, update or delete operations, this means that the directory server will only return a HTTP 200 response once the operation has been successfully persisted to durable storage or its equivalent. If directory clients do not receive HTTP success response codes, then clients MUST query the server to determine if the create, update or delete operation succeeded. If the operation is a query or retrieve, then clients MUST retry the operation. CONF: Clients sending a create, update, or delete request that do not receive an HTTP response code MUST query the server to determine if the operation succeeded.

Locking

Create, update and delete operations normally change the contents of the directory. In order to assure consistency, prior to this operations being executed, a lock is attempted on the directory. If the lock fails, then the directory retries the lock operation until timeout and a retry limits are exceeded or until the lock succeeds. If the lock succeeds, then the operation is allowed to complete, and then the directory is unlocked. Clients should be aware of this behavior, and as mentioned elsewhere in this document, should perform a retry operation if the client request cannot be serviced before either the client or the server exceed the configured time-out value.

Next Page - Security