TORCH - Transfer Of Resources in Clinical Healthcare
Transfer Of Resources in Clinical Healthcare
Goal
The goal of this project is to provide a service that allows the execution of data extraction queries on a FHIR-server.
The tool will take an DEQ, Whitelists and CDS Profiles to extract defined Patient ressources from a FHIR Server and then apply the data extraction with the Filters defined in the DEQ. Additionally Whitelists can be applied.
The tool internally uses the HAPI implementation for handling FHIR Resources.
CRTDL
The Clinical Resource Transfer Definition Language or CRTDL is a JSON format that describes attributes to be extracted with attributes filter.
Prerequisites
Local FHIR Server with test data and a Flare server with a cohort Endpoint Torch interacts with these components for the data extraction.
Build
mvn clean install
Run
java -jar target/torch-0.0.1-SNAPSHOT.jar
mvn spring-boot:run
Environment Variables
| Name | Default | Description |
|---|---|---|
| SERVER_PORT | 8080 | The Port of the server to use |
| TORCH_FHIR_URL | http://localhost:8082/fhir | The base URL of the FHIR server to use. |
| TORCH_FLARE_URL | http://localhost:8084 | The base URL of the FLARE server to use. |
| TORCH_PROFILE_DIR | src/test/resources/StructureDefinitions | The directory for profile definitions. |
| TORCH_RESULTS_DIR | output/ | The directory for storing results. |
| TORCH_RESULTS_PERSISTENCE | PT12H30M5S | Time Block for result persistence in ISO 8601 format. |
| TORCH_BATCHSIZE | 100 | The batch size used for processing data. |
| NGINX_SERVERNAME | localhost:8080 | The server name configuration for NGINX. |
| LOG_LEVEL_org_springframework_web_reactive_function_client | info | Log level for Spring Web Reactive client functions. |
| LOG_LEVEL_reactor_netty | info | Log level for Netty reactor-based networking. |
| LOG_LEVEL_reactor | info | Log level for Reactor framework. |
| LOG_LEVEL_de_medizininformatikinitiative_torch_util | ${LOG_LEVEL:info} | Log level for torch utility. |
| LOG_LEVEL_de_medizininformatikinitiative_torch | ${LOG_LEVEL:info} | Log level for torch core functionality. |
| LOG_LEVEL_de_medizininformatikinitiative_torch_rest | ${LOG_LEVEL:info} | Log level for torch REST services. |
| LOG_LEVEL_org_springframework | ${LOG_LEVEL:info} | Log level for Spring Framework. |
Examples of Using Torch
Below, you will find examples for typical use cases. To demonstrate the simplicity of the RESTful API, the command line tool curl is used in the following examples for direct HTTP communication.
Flare REST API
Torch implements the FHIR Asynchronous Bulk Data Request Pattern.
$extract-data
The $extract-data endpoint implements the kick-off request in the Async Bulk Pattern. It receives a FHIR parameters resource with a CRTDL parameter containing a valueBase64Binary.
scripts/create-parameters.sh src/test/resources/CRTDL/CRTDL_observation.json | curl -s 'http://localhost:8086/fhir/$extract-data' -H "Content-Type: application/fhir+json" -d @- -v
The Parameters resource created by scripts/create-parameters.sh look like this:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "crtdl",
"valueBase64Binary": "<Base64 encoded CRTDL>"
}
]
}
Response - Error (e.g. unsupported search parameter)
- HTTP Status Code of 4XX or 5XX
Response - Success
- HTTP Status Code of 202 Accepted
- Content-Location header with the absolute URL of an endpoint for subsequent status requests (polling location)
That location header can be used in the following status query: E.g. location:"/fhir/__status/1234"
Status Request
Torch provides a Status Request Endpoint which can be called using the location from the extract Data Endpoint.
curl -s http://localhost:8080/fhir/__status/{location}
Response - In-Progress
- HTTP Status Code of 202 Accepted
Response - Error
- HTTP status code of 4XX or 5XX
- Content-Type header of application/fhir+json
Response - Complete
- HTTP status of 200 OK
- Content-Type header of application/fhir+json
- A body containing a JSON file describing the file links to the batched transformation results
curl -s 'http://localhost:8080/fhir/$extract-data' -H "Content-Type: application/fhir+json" -d '<query>'
the result is a looks something like this:
{
"requiresAccessToken": false,
"output": [
{
"type": "Bundle",
"url": "localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/6c88f0ff-0e9a-4cf7-b3c9-044c2e844cfc.ndjson"
},
{
"type": "Bundle",
"url": "localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/a4dd907c-4d98-4461-9d4c-02d62fc5a88a.ndjson"
},
{
"type": "Bundle",
"url": "localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/f33634bd-d51b-463c-a956-93409d96935f.ndjson"
}
],
"request": "localhost:8080//fhir/$extract-data",
"deleted": [],
"transactionTime": "2024-09-05T12:30:32.711151718Z",
"error": []
}
Metadata
Response -Success
- HTTP status of 200 OK
- Content-Type header of application/fhir+json
- A body containing a Bundle Resource with a type of batch-response.
Supported Features
- Multiple Profiles per Resource (greedy talkes first CDS conforming one)
- Loading of CDS StructureDefinitions
- Redacting and Copying of Ressources
- Parsing CRTDL
- Interaction with a Flare and FHIR Server
Outstanding Features
- CQL functionalities
- Loading of Whitelists
- Verifiyng against the CDS Profiles
License
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.