21st Century Cures Act, 170.315 (b)(10) Electronic Health Information Export - ๐Ÿ‡บ๐Ÿ‡ธ๏ƒ

Note

Firely Server v5 has been officially certified against ยง170.315 b(10) 2015 Cures Edition Health IT. For more details, see our CHPL listing. Mandatory disclosures can be found here.

170.315 (b)(10) requires the implementation of Electronic Health Information (EHI) export functionality. This encompasses the ability to generate export files for individual patients and entire patient populations in a computable format. Firely Server provides comprehensive support for this requirement through its Bulk Data Export feature. For a deeper understanding and comprehensive utilization of this feature beyond the (b)(10) requirements, please consult the provided documentation, which includes setup instructions, application settings, parameters, filtering options, and additional details.

File Format๏ƒ

Bulk Data Export files are formatted in NDJSON (New line delimited JSON), a modified version of the JSON format designed for efficient bulk data transfer. NDJSON follows a simplified JSON structure where resources are serialized without whitespace and separated by a newline pair (ASCII characters 13 and 10). This format aids in streamlining processing by ensuring that each NDJSON document contains only resources of a single type. Each line within the document represents a resource of that specific type. A single file can accommodate multiple resources for multiple patients with multiple records, although the resource type is the same across all entries per file.

Note

NDJSON is the default and only supported export format.

Each NDJSON file will have a file naming convention of content{resource}.ndjson, where {resource} represents a FHIR resource type, i.e. Patient, Observation. Within each NDJSON file, only the resources of the named FHIR resource type will be included.

Resources Included (EHI Exported)๏ƒ

When exporting resources, all data from within the Patient compartment, as defined by HL7 FHIR R4, will be included. This means that all relevant information related to the patient, such as demographics, observations, medications, and other healthcare data, will be part of the exported resources.

Handling unstructured data๏ƒ

By definition, EHI covers also unstructured documents that are associated with a patient as well, such as images, documents, or medical notes. Binary Resources are used to represent these kinds of unstructured data. Firely Server has extended the Patient compartment definition to encompass Binary Resources that are linked to a patient. By including these Binary Resources within the Patient compartment during export, Firely Server ensures that all relevant data linked to a patient is included in the export files. See Binary Wrapper documentation for more information on storing Binary Resources in Firely Server. Metadata associated with a Binary resource can be stored in a DocumentReference resource.

Authentication and Authorization๏ƒ

Firely Server and Firely Auth offer a robust set of access control methodologies that leverage the SMART on FHIR framework. These mechanisms provide extensive options for controlling access to the 170.315(b)(10) EHI bulk data export functionality. Detailed information on setting up access control can be found in the access control documentation provided.

To meet the requirements for 170.315(b)(10), the following basic recommendation is detailed below:

1. Implement User Authentication: Require users to authenticate themselves before accessing the EHI bulk data export functionality. This ensures that only authorized individuals can initiate data exports.

2. Create a Firely Auth client registration specifically for EHI export. Creating a client registration in Firely Auth allows you to define the necessary settings and permissions for EHI export. Ensure that the client registration has system-level scopes, granting access to all patient compartment data during the export process. This allows the limited group of users associated with this client to access the required data for EHI export.

Single Patient EHI Export - 170.315(b)(10)(i)๏ƒ

To meet the requirements of 170.315(b)(10)(i), Firely Server offers an export feature that allows for the extraction of data related to a single patient. This is achieved by utilizing a Parameters Resource filter against the Patient endpoint.

However, an alternative method is also provided using the Group endpoint. This alternative approach caters to real-world scenarios and alternative workflows that may be more suitable for portals and UI that connect to Firely Server.

Notice in the following Parameters Resource example; there is just a single patient reference.

Parameters Resource Example๏ƒ
  {
    "resourceType": "Parameters",
    "parameter": [
      {
        "name": "patient",
        "valueReference": {
          "reference": "Patient/test"
        }
      }
    ]
  }

Primary Method: Exporting a Single Patient using the Patient Endpoint๏ƒ

Perform a POST request to the Patient endpoint, including a Parameters Resource filter in the request body. The filter specifies the patient to be exported.

  1. Create a POST request to the Patient endpoint:

    POST {{BASE_URL}}/Patient/$export

  2. Include the example Parameters Resource from above in the request body.

This method directly exports the specified patient using the Patient endpoint and applies the Parameters filter to limit the exported data.

Alternative Method: Exporting a Single Patient using the Group Endpoint๏ƒ

Perform a POST request to the Group endpoint, including a Parameters filter in the request body. The filter is used to filter the patients within the specified group, and only the desired patientโ€™s data will be exported.

  1. Create a POST request to the Group endpoint:

    POST {{BASE_URL}}/Group/[groupId]/$export

  2. Include the example Parameters Resource from above in the request body.

By utilizing the Group endpoint and applying the Parameters filter, the export operation focuses on the patient within the specified group.

Patient Population EHI Export - 170.315(b)(10)(ii)๏ƒ

To meet the requirements of 170.315(b)(10)(ii), Firely Server exports all patients and their related data without applying any filtering parameters, as demonstrated in the Single Patient Export. However, it is important to acknowledge that filtering is a common occurrence in real-world scenarios, particularly during the migration of patient populations between health IT systems.

In such cases, Firely Server provides the flexibility to apply filtering parameters and/or by using groups, allowing for the export of specific subsets of patients. This accommodates both adherence to the requirement of exporting all patients and data, as well as the practical need for targeted data exports in specific situations.

In the following examples, the first method exports the entire patient population, while the subsequent methods allows for exporting a subset of the patient population.

Method 1: Exporting an Entire Patient Population using the Patient Endpoint๏ƒ

Perform a POST or GET request to the Patient endpoint without any filters.

  1. Create a POST or GET request to the Patient endpoint:

    POST/GET {{BASE_URL}}/Patient/$export

This method exports all patients and their related data without applying any filtering parameters.

Method 2: Exporting a Subset Patient Population using the Patient Endpoint๏ƒ

Perform a POST request to the Patient endpoint without any filters.

  1. Create a POST request to the Patient endpoint:

    POST {{BASE_URL}}/Patient/$export

  2. Include the example Parameters Resource from below in the request body.

    {
        "resourceType": "Parameters",
        "parameter": [
        {
            "name": "patient",
            "valueReference": {
            "reference": "Patient/test"
            }
        },
        {
            "name": "patient",
            "valueReference": {
            "reference": "Patient/other"
            }
        }
        ]
    }
    

This method allows you to specify the patients to be exported by including their references in the Parameters Resource.

Method 3: Exporting a Subset Patient Population using the Group Endpoint๏ƒ

To export a subset of the patient population using the Group endpoint, you have two options:

3.1. Exporting without filtering parameters๏ƒ

Perform a POST or GET request to the Group endpoint without any filters.

  1. Create a POST or GET request to the Group endpoint:

    POST/GET {{BASE_URL}}/Group/[groupId]/$export

This option exports all of the patients within the specified [groupId].

3.2. Exporting with filtering parameters๏ƒ

Perform a POST request to the Group endpoint, including a Parameters filter in the request body.

  1. Create a POST request to the Group endpoint:

    POST {{BASE_URL}}/Group/[groupId]/$export

  2. Include the example Parameters Resource from below in the request body.

    {
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "patient",
          "valueReference": {
            "reference": "Patient/test"
          }
        },
        {
          "name": "patient",
          "valueReference": {
            "reference": "Patient/other"
          }
        }
      ]
    }
    

This option exports only the patients within the specified [groupId] and based on the provided references.

Understanding the Export Results๏ƒ

After successfully requesting a Single Patient EHI Export or Patient Population EHI Export, the response will be in the following format:

$Example export response body๏ƒ
{
    "resourceType": "OperationOutcome",
    "id": "ce82d245-ed15-4cf1-816f-784f8c937e72",
    "meta": {
        "versionId": "addcff4e-4bc1-4b68-a08c-e76409a0b5b0",
        "lastUpdated": "2023-06-16T19:15:55.092273+00:00"
    },
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "The $export task is successfully added to the queue. Status updates can be requested using https://localhost:4081/$exportstatus?_id=13d8ce0d-9f96-48d4-96a7-58d0b3dd4e75. This URL can also be found in the Content-Location header."
        }
    ]
}

Since the Bulk Data Export is asynchronous, it will need to be queried periodically to determine when it has completed compiling resources for the patients(s) is complete. To perform this, execute the $exportstatus operation.

Example:

GET https://localhost:4081/$exportstatus?_id=13d8ce0d-9f96-48d4-96a7-58d0b3dd4e75

Refer to the Bulk Data Export Status documentation for more information on the $exportstatus operation and non-complete statuses.

Once the $exportstatus returns a completed response, as shown below, the next step is to query and download the actual NDJSON files.

$Example exportstatus complete response body๏ƒ
{
    "transactionTime": "2023-06-16T17:01:04.6036373+00:00",
    "request": "/Patient/$export",
    "requiresAccessToken": false,
    "output": [
        {
            "type": "Invoice",
            "url": "https://localhost:4081/$exportfilerequest/?_id=6a8936d5-b1ab-46fb-a54b-0f69f8b4fda6&filename=contentInvoice.ndjson"
        },
        {
            "type": "Patient",
            "url": "https://localhost:4081/$exportfilerequest/?_id=6a8936d5-b1ab-46fb-a54b-0f69f8b4fda6&filename=contentPatient.ndjson"
        }
    ],
    "error": [],
    "extension": {
        "http://server.fire.ly/context/informationModel": "Fhir4.0",
        "ehiDocumentationUrl": "https://docs.fire.ly/projects/Firely-Server/en/latest/features_and_tools/bulkdataexport.html"
    }
}

Each output:url in the JSON above represents a downloadable NDJSON file. To download each respective NDJSON file, a GET request can be used to query and retrieve the file.

Example:

Accept:application/fhir+ndjson
GET https://localhost:4081/$exportfilerequest/?_id=13d8ce0d-9f96-48d4-96a7-58d0b3dd4e75&filename=contentPatient.ndjson