Create wiki/website for TORCH

Author: Lucas0T

.github/workflows/build.yml

@@ -4,13 +4,13 @@ on:
   push:
     branches:
       - main
-      - develop
     tags:
       - 'v*.*.*'
   pull_request:
     branches:
       - main
-      - develop
+    paths-ignore:
+      - 'docs/**'
   schedule:
     - cron: '0 1 * * *'
   merge_group:

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*.*.*'
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: '0 1 * * *'
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions: read-all
+
+jobs:
+  build-pages:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: 'docs/package-lock.json'
+
+      - name: Build
+        working-directory: docs
+        env:
+          DOCS_BASE: "/${{ github.event.repository.name }}/"
+        run: make build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy-pages:
+    runs-on: ubuntu-24.04
+    needs: [ build-pages ]
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: ${{ github.ref == 'refs/heads/main' && 'github-pages' || format('preview-{0}', github.ref_name) }}
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.nvmrc

@@ -0,0 +1 @@
+23.11.1

docs/.gitignore

@@ -0,0 +1,3 @@
+/node_modules/
+/.vitepress/cache
+/.vitepress/dist

docs/.vitepress/config.ts

@@ -0,0 +1,79 @@
+import {withMermaid} from "vitepress-plugin-mermaid";
+
+export default withMermaid({
+    title: 'TORCH',
+    description: 'TORCH Documentation',
+    base: process.env.DOCS_BASE || '',
+    lastUpdated: true,
+    themeConfig: {
+        siteTitle: false,
+
+        editLink: {
+            pattern: 'https://github.com/medizininformatik-initiative/torch/edit/main/docs/:path',
+            text: 'Edit this page on GitHub'
+        },
+
+        socialLinks: [
+            {icon: 'github', link: 'https://github.com/medizininformatik-initiative/torch'}
+        ],
+
+        footer: {
+            message: 'Released under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License 2.0</a>',
+        },
+
+        search: {
+            provider: 'local'
+        },
+
+        outline: {
+            level: [2, 3]
+        },
+
+        nav: [
+            {text: 'Home', link: '/'}
+        ],
+
+        sidebar: [
+            {
+                text: 'Home',
+                link: '/index.md',
+                activeMatch: '^/$'
+            },
+            {
+                text: 'Getting Started',
+                link: '/getting-started',
+                activeMatch: '^/getting-started'
+            },
+            {
+                text: 'Documentation',
+                link: '/documentation',
+                items: [
+                    {text: 'Configuration', link: '/configuration'},
+                    {text: 'API', link: '/api/api'},
+                    {
+                        text: 'CRTDL', link: '/crtdl/crtdl',
+                        items: [
+                            {text: 'Filter', link: '/crtdl/filter'},
+                            {text: 'Consent Key', link: '/crtdl/consent_key'}
+                        ]
+
+                    },
+                    {
+                        text: 'Implementation',
+                        link: '/implementation/implementation-overview',
+                        items: [
+                            {text: 'Consent', link: '/implementation/consent'},
+                            {text: 'Direct Loading', link: '/implementation/direct_load'},
+                            {text: 'Must Have Checking', link: '/implementation/must_have'},
+                            {text: 'Cascading Delete', link: '/implementation/cascading_delete'},
+                            {text: 'Reference Resolve', link: '/implementation/reference_resolve'},
+                            {text: 'Redaction', link: '/implementation/redaction'},
+                            {text: 'Data Extraction', link: '/implementation/data-extraction'}
+                        ]
+                    }
+
+                ]
+            }
+        ]
+    }
+})

docs/Makefile

@@ -0,0 +1,7 @@
+install:
+	npm install
+
+build: install
+	npm run docs:build
+
+.PHONY: install build

docs/api/api.md

@@ -0,0 +1,136 @@
+# API
+
+TORCH provides a FHIR REST API for extracting data based on the Clinical Resource Transfer Definition Language (CRTDL).
+It implements the FHIR [Asynchronous Bulk Data Request Pattern](http://hl7.org/fhir/R5/async-bulk.html).
+
+### Key Features of the API
+
+- **Asynchronous Requests**: Supports long-running data extraction tasks.
+- **FHIR Compliant**: Adheres to FHIR standards for resource representation.
+- **CRTDL Integration**: Uses CRTDL definitions to specify data extraction rules.
+
+### API Endpoints
+
+- **`/$extract-data`**: Initiates a data extraction job based on a CRTDL definition.
+- **`/__status`**: Checks the status of an ongoing data extraction job.
+- **`/metadata`**: Provides metadata about the TORCH server and its capabilities.
+
+## TORCH REST API (based on FHIR Bulk Data Request)
+
+Torch implements the FHIR [Asynchronous Bulk Data Request Pattern][1].
+
+### $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 [CRTDL](https://github.com/medizininformatik-initiative/clinical-resource-transfer-definition-language).
+All examples are with a torch configured with **`http://localhost:8080`**.
+
+```sh
+scripts/create-parameters.sh src/test/resources/CRTDL/CRTDL_observation.json | curl -s 'http://localhost:8080/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>"
+    }
+  ]
+}
+```
+
+Optionally patient ids can be submitted for a known cohort, bypassing the cohort selection in the CRTDL:
+
+```
+{
+  "resourceType": "Parameters",
+  "parameter": [
+    {
+      "name": "crtdl",
+      "valueBase64Binary": "<Base64 encoded CRTDL>"
+    },
+    {
+      "name": "patient",
+      "valueString": "<Patient Id 1>"
+    },
+    {
+      "name": "patient",
+      "valueString": "<Patient Id 2>"
+    }
+  ]
+}
+```
+
+#### 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.
+
+```sh
+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
+* Operation Outcome with fatal issue
+
+#### 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
+
+```sh
+curl -s 'http://localhost:8080/fhir/$extract-data' -H "Content-Type: application/fhir+json" -d '<query>'
+```
+
+the result is a looks something like this:
+
+```json
+{
+  "requiresAccessToken": false,
+  "output": [
+    {
+      "type": "Bundle",
+      "url": "http://localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/6c88f0ff-0e9a-4cf7-b3c9-044c2e844cfc.ndjson"
+    },
+    {
+      "type": "Bundle",
+      "url": "http://localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/a4dd907c-4d98-4461-9d4c-02d62fc5a88a.ndjson"
+    },
+    {
+      "type": "Bundle",
+      "url": "http://localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/f33634bd-d51b-463c-a956-93409d96935f.ndjson"
+    }
+  ],
+  "request": "http://localhost:8080//fhir/$extract-data",
+  "deleted": [],
+  "transactionTime": "2024-09-05T12:30:32.711151718Z",
+  "error": []
+}
+
+```
+
+[1]: <http://hl7.org/fhir/R5/async-bulk.html>