User Guide
Last updated
A practical guide for business users, researchers, and data stewards working with the Health Dataspace platform. Each section links directly to the feature page in the live demo. For a complete end-to-end walkthrough covering every persona and workflow, see the Full User Journey.
Static Demo vs Full Stack
The GitHub Pages demo runs as a static export with mock data. The Azure EHDS Portal at ehds.mabu.red runs the full stack with live services, on weekdays in office hours (see When Is the Live Demo Available?). The following features require the full stack:
- Keycloak SSO login — the static demo uses a persona switcher instead
- Live Neo4j graph queries — graph explorer uses pre-loaded mock data
- Contract negotiation & transfers — require EDC connectors
- Natural language / federated queries — require neo4j-proxy service
- ODRL policy enforcement — requires live dataspace middleware
See the Developer Guide for full stack setup instructions.
Purpose
This platform is a reference implementation of the European Health Data Space (EHDS) regulation. Its purpose is to demonstrate how sovereign health data exchange works in practice — combining the Dataspace Protocol (DSP 2025-1), FHIR R4 clinical resources, OMOP CDM analytics, and biomedical ontologies into a unified Neo4j knowledge graph.
The five knowledge-graph layers model the complete EHDS data lifecycle:
- L1 Dataspace Marketplace — Participants, DataProducts, ODRL policies, contracts, HDAB approvals
- L2 HealthDCAT-AP Metadata — Catalogues, datasets, distributions, data services
- L3 FHIR R4 Clinical — Patients, encounters, conditions, observations, medications
- L4 OMOP CDM Analytics — Persons, condition occurrences, drug exposures, measurements
- L5 Biomedical Ontology — SNOMED CT, ICD-10, RxNorm, LOINC concept mappings
All data is fully synthetic. Organisation names are fictional (AlphaKlinik Berlin, PharmaCo Research AG, MedReg DE, Limburg Medical Centre, Institut de Recherche Santé).
Personas & Roles — Who Uses What?
The EHDS regulation defines distinct participant roles to ensure accountability, data sovereignty, and patient rights across the health data ecosystem. This platform adapts its navigation, graph view, and available actions to the signed-in user's EHDS role. Sign in at /auth/signin with any demo account — password equals username in local dev.
Sign In — Demo Persona Cards
The sign-in page lists every demo account with its role badge, organisation, and the graph persona view it will open after login. Clicking a card calls Keycloak SSO and redirects directly to the user's personalised graph.
| Username | Organisation | Role | Graph view | Primary question | EHDS basis |
|---|---|---|---|---|---|
| edcadmin | Dataspace Operator | EDC Admin | edc-admin | Who are my participants? What contracts are active? | EHDS Art. 52 — operates the dataspace infrastructure and ensures interoperability between participants |
| clinicuser | AlphaKlinik Berlin | Data Holder | hospital | Who has approved access to my datasets? | EHDS Art. 33-34 — health data holders must make electronic health data available for secondary use when authorized |
| lmcuser | Limburg Medical Centre | Data Holder | hospital | What contracts are active for my NL datasets? | EHDS Art. 33-34 — cross-border data holder demonstrating multi-country interoperability |
| researcher | PharmaCo Research AG | Researcher | researcher | What datasets match my study protocol? | EHDS Art. 34(1) — data users access health data for permitted secondary use purposes (research, innovation, public health) |
| regulator | MedReg DE | HDAB Authority | hdab | What approvals are pending? Is the chain complete? | EHDS Art. 36-37 — Health Data Access Bodies are designated by each Member State to authorize secondary use of health data |
Why These Roles? — EHDS Regulatory Background
The European Health Data Space regulation establishes a governance framework for both primary use (patient access to their own data) and secondary use (research, innovation, policy-making). Each role in this platform maps to a specific actor defined in the regulation:
Healthcare providers, insurers, and registries that hold electronic health data are legally required to make it available for authorized secondary use. They retain sovereignty over their data and control access through ODRL policies and contract negotiation.
Researchers, public health agencies, and innovators who need health data for permitted purposes must apply through an HDAB, receive a data permit, and access data only in a secure processing environment. They never receive raw patient data directly.
Each EU Member State must designate one or more Health Data Access Bodies (HDABs) as the national authority that reviews data access applications, issues data permits, and ensures compliance. MedReg DE represents the German HDAB in this implementation.
The dataspace operator runs the technical infrastructure: participant onboarding, connector management, federated catalog, and transfer monitoring. They ensure interoperability across all participants but do not access health data directly.
The EHDS mandates pseudonymisation and re-identification controls. The Trust Center manages pseudonym resolution, secure processing environment (SPE) sessions, and ensures that data users only access de-identified data. This role enforces the technical privacy safeguards the regulation requires.
Menu Items per Role
Navigation is filtered by role — items not relevant to a user's function are hidden entirely. This separation of concerns reflects the EHDS principle that each actor should only see the tools and data relevant to their regulatory function.
| Page | Patient | Data Holder | Researcher | HDAB | EDC Admin |
|---|---|---|---|---|---|
My Health in One View /overview | ✅ | ✅ | ✅ | ✅ | ✅ |
My Health Records /patient | ✅ | ✅ | ✅ | ✅ | ✅ |
Personal Research /patient/query | ✅ | — | — | — | — |
Health Profile & Risks /patient/profile | ✅ | — | — | — | — |
Research Programs /patient/research | ✅ | — | — | — | — |
Research Insights /patient/insights | ✅ | — | — | — | — |
Dataset Catalog /catalog | — | ✅ | ✅ | ✅ | ✅ |
DCAT-AP Editor /catalog/editor | — | ✅ | — | — | ✅ |
Statistical Requests /requests | — | ✅ | ✅ | ✅ | ✅ |
Supervision /supervision | — | ✅ | ✅ | ✅ | ✅ |
OMOP Analytics /analytics | — | ✅ | ✅ | ✅ | ✅ |
EEHRxF Profiles /eehrxf | — | ✅ | ✅ | ✅ | ✅ |
Permits Register /permits | — | ✅ | — | ✅ | ✅ |
Activity Report /activity-report | — | ✅ | — | ✅ | ✅ |
Secondary Use Info /information | — | ✅ | — | ✅ | ✅ |
Share Data /data/share | — | ✅ | ✅ | — | ✅ |
Negotiate /negotiate | — | ✅ | ✅ | ✅ | ✅ |
Tasks /tasks | — | ✅ | ✅ | ✅ | ✅ |
Transfer /data/transfer | — | ✅ | ✅ | ✅ | ✅ |
Discover Datasets /data/discover | — | — | ✅ | ✅ | ✅ |
Apply for a Permit /applications | — | — | ✅ | — | — |
Query & Export /query | — | — | ✅ | ✅ | ✅ |
EHDS Approval /compliance | — | — | — | ✅ | ✅ |
Protocol TCK /compliance/tck | — | — | — | ✅ | ✅ |
Credentials /credentials | — | — | — | ✅ | ✅ |
Policies /admin/policies | — | — | — | ✅ | ✅ |
Audit & Provenance /admin/audit | — | — | — | ✅ | ✅ |
Onboarding /onboarding | — | — | — | — | ✅ |
Operator Dashboard /admin | — | — | — | — | ✅ |
EDC Components /admin/components | — | — | — | — | ✅ |
Tenants /admin/tenants | — | — | — | — | ✅ |
Participants /admin/participants | — | — | — | — | ✅ |
Generated from the navigation itself, so it shows exactly what each persona's menu holds. Every page except the start page and this documentation needs a sign-in (ADR-044); a page missing from a menu is not necessarily forbidden, the middleware decides that.
Graph Explorer — Persona Views
The “View as” panel in the graph sidebar and the “My graph view” link in the UserMenu dropdown load a role-specific subgraph that answers each persona's primary question. Each view surfaces only the graph layers and node types relevant to that regulatory function.
/graph?persona=hospital“Who has approved access to my datasets?”
Focus nodes: Participant · HealthDataset · Contract · HDABApproval · EEHRxFProfile
/graph?persona=researcher“What datasets match my study? What OMOP analytics can I run?”
Focus nodes: HealthDataset · OMOPPerson · SnomedConcept · SPESession
/graph?persona=hdab“What approvals are pending? Is the governance chain complete?”
Focus nodes: HDABApproval · VerifiableCredential · TrustCenter · AccessApplication
/graph?persona=trust-center“Which pseudonym resolution flows am I managing?”
Focus nodes: TrustCenter · SPESession · ResearchPseudonym · ProviderPseudonym
/graph?persona=edc-admin“Who are my participants? What contracts and transfers are live?”
Focus nodes: Participant · DataProduct · Contract · TransferEvent
Getting Started
After authenticating through Keycloak SSO, you land on the graph view personalised for your role. You can also browse datasets, review patient timelines, run analytics, or check EHDS compliance. The UserMenu (top-right) shows your role badge and a “My graph view” shortcut to your persona graph.
Home Dashboard
The landing page presents a high-level overview of the dataspace: active participants, registered datasets, and recent transfers. Quick-action cards let you jump to common tasks.
Example: PharmaCo Research AG logs in and sees 5 active participants, 3 published datasets, and a pending contract negotiation with AlphaKlinik Berlin.
Participant Onboarding
The onboarding wizard guides new participants through dataspace registration: creating a DID identity, registering with the Credential Federated Manager, and enrolling in the federated catalog. This process implements the EHDS requirement for authorised participation (Art. 52) with verifiable credentials.
Example: Limburg Medical Centre joins the EHDS dataspace by providing its organization details, generating did:web:lmc.nl:clinic, and obtaining a MembershipCredential.
Participant Settings
View and manage your participant profile, verifiable credentials (MembershipCredential, EHDSParticipantCredential), connector endpoints, and Keycloak SSO configuration.
Example: AlphaKlinik Berlin checks that both its MembershipCredential and EHDSParticipantCredential are active and not expired before publishing a new dataset.
When Is the Live Demo Available?
The demo exists twice. The live dataspace runs the real connectors, identity services and databases, and to save running costs it is stopped outside office hours. The static demo is a copy of the same pages with synthetic data, and it is always available.
| Live demo | Static demo | |
|---|---|---|
| Address | ehds.mabu.red | GitHub Pages |
| Available | Monday to Friday, 07:00 to 20:00 Berlin time in summer and 06:00 to 19:00 in winter. Closed on Berlin public holidays. | Always |
| Sign-in | Keycloak accounts per persona | A persona picker, no password |
| Data | The live knowledge graph; negotiations and transfers really run | A fixed snapshot; actions are shown but not carried out |
If you open the live demo outside these hours, every page shows a notice saying when it is back, with a button that opens the same page in the static demo. The Klarbefund app cannot connect to EHDS or use its cloud analysis during these times either. Analysis on the phone keeps working.
Explore
Persona Overview
The force-directed graph visualisation displays all five architecture layers of the knowledge graph. Nodes are colour-coded by layer: Marketplace, HealthDCAT-AP, FHIR R4, OMOP CDM, and Ontology. This unified view shows how the EHDS connects clinical data (FHIR), analytics (OMOP), and governance (DSP) into a coherent ecosystem.
- Click nodes to see properties and related entities
- Use the layer toggle to filter visible layers
- Zoom and pan with mouse controls
- Search bar finds specific nodes across all layers
Example: A researcher explores how a FHIR Patient resource connects to OMOP Person and condition_occurrence records via the SNOMED ontology layer.
Dataset Catalog
Browse and search HealthDCAT-AP metadata records for all published datasets. Each entry shows title, description, publisher, temporal/spatial coverage, and distribution formats. The catalog implements the EHDS metadata requirements (Art. 55) for discoverable, machine-readable dataset descriptions.
- Filter by publisher, theme, or keyword
- View distribution endpoints (FHIR, OMOP, bulk export)
- Check data quality metrics (DQV dimensions)
- Initiate data access requests from catalog entries
Example: PharmaCo Research AG searches for "diabetes" datasets and finds AlphaKlinik Berlin's Type 2 Diabetes Cohort with FHIR R4 and OMOP CDM distributions.
Patient Journey
View the clinical timeline for synthetic patients, showing FHIR R4 resources (Encounters, Conditions, Observations, Medications, Procedures) mapped to their OMOP CDM equivalents. This dual-view demonstrates how primary-use clinical data (EHDS Art. 3-12) can be transformed for secondary-use analytics while preserving semantic integrity.
- Select patients from the patient list
- Timeline displays events chronologically
- Toggle between FHIR and OMOP views
- Explore SNOMED/LOINC/RxNorm concept mappings
Example: A data steward reviews the timeline for a synthetic patient with hypertension, verifying that the FHIR Condition correctly maps to OMOP condition_occurrence with SNOMED code 38341003.
OMOP Analytics
Cohort-level research analytics powered by the OMOP CDM layer. Run aggregate queries across conditions, measurements, drug exposures, and procedures. This implements the EHDS secondary-use analytics capability (Art. 34) where researchers work with de-identified, standardised data.
- View condition prevalence and demographics
- Analyse drug exposure patterns
- Run cohort characterisation queries
- Export results for further analysis
Example: PharmaCo Research AG runs a cohort query to identify patients with Type 2 Diabetes who received Metformin, showing age and gender distribution across the cohort.
Natural Language / Federated Query
Execute cross-participant queries using natural language or structured query syntax. The query engine translates requests into federated SPARQL/Cypher queries across connected dataspace nodes. This demonstrates how the EHDS enables cross-border data access without centralising raw health data.
Example: A researcher types "How many patients with hypertension are older than 65?" and the system queries both AlphaKlinik Berlin and Limburg Medical Centre, returning aggregated results without moving raw data.
EEHRxF Profiles
European EHR Exchange Format profile alignment view. Analyse which FHIR profiles satisfy EHDS priority categories (Patient Summary, ePrescription, Laboratory Results, Medical Imaging, Hospital Discharge) and identify coverage gaps. The EEHRxF is mandated by EHDS Art. 6 to ensure interoperability of primary-use health data across Member States.
Example: MedReg DE reviews AlphaKlinik Berlin's profile coverage and sees that Patient Summary and Laboratory Results are fully aligned, while ePrescription has one missing profile.
My Health
A signed-in patient gets their own menu: one overview, their records, and the pages below. Each shows that patient's own record only; any other patient's record is refused (EHDS Art. 3, GDPR Art. 15).
Personal Research
A natural-language question over the patient's own record (EHDS Art. 3, GDPR Art. 15): trends from fitness, lab and nutrition data, together with the relevant ePA events, computed only from that patient's data.
Example: A patient asks how their cholesterol has changed since their last check-up.
Health Profile & Risks
The patient's health profile and risk assessment, derived from their own record.
Example: A patient reviews the risk factors the profile derives from their last lab results.
Research Programs
Research programmes the patient can join or leave, and the history of every consent given or withdrawn.
Example: A patient withdraws consent from a study and sees the withdrawal recorded in the consent history.
Research Insights
What research using the patient's data found, and the recommendations that follow for them.
Example: A patient reads an insight from a diabetes study they contributed to.
Governance
The governance modules manage EHDS compliance, protocol testing, and verifiable credential issuance as required by the European Health Data Space regulation (Articles 36-52). These modules ensure that every data access follows the legally mandated approval chain: application, HDAB review, data permit issuance, contract negotiation, and audited transfer.
EHDS Approval
Manage data access permits as required by EHDS Articles 45-49. Data users submit applications specifying the purpose, scope, and duration of data access. HDABs review applications against the permitted purposes in Art. 34(1) and issue verifiable credentials as proof of authorization.
Example: PharmaCo Research AG submits a data access application for the diabetes cohort. MedReg DE (HDAB) reviews the request, approves it under Art. 46, and a DataPermitCredential is issued.
Protocol TCK
The Technology Compatibility Kit validates that your EDC connector implements the Dataspace Protocol (DSP 2025-1) correctly. Tests cover catalog queries, contract negotiations, and transfer processes. Passing the TCK is a prerequisite for interoperability within the EHDS ecosystem.
Example: The operator runs the TCK suite and compares the result with the floor recorded in scripts/compliance-baseline.json; a drop below it fails the compliance workflow.
Verifiable Credentials
View and manage verifiable credentials across all dataspace participants. Each participant holds a MembershipCredential and an EHDSParticipantCredential, issued by the trusted issuer service. Credentials follow the DCP v1.0 standard for decentralised claims, enabling trust without a central authority.
Example: The operator verifies that all 5 participants (AlphaKlinik Berlin, PharmaCo Research AG, MedReg DE, Limburg Medical Centre, Institut de Recherche Santé) each hold 2 active credentials.
Apply for a Permit
A data user applies for a data permit with the eleven items of Regulation (EU) 2025/327 Art. 67(2), then follows what becomes of it: the access body's clock (Art. 68(4)), a notice that items are missing, the permit or the refusal, and the results the user communicates afterwards (Art. 61(4)).
Example: PharmaCo Research AG applies for the Type 2 Diabetes Cohort and sees the access body's decision deadline count down.
Statistical Requests
A health data request under Art. 69: the data user asks a question and, if the access body approves, receives an anonymised statistic and nothing else. The access body decides on the same page.
Example: A researcher asks how many patients in the cohort have HbA1c above 7 % and receives a single count.
Supervision
Art. 63: the access body records a finding of non-compliance against a data user or holder, the party states its views within four weeks, the body takes a measure and publishes it; the body can also ask a party for information, answered on record.
Example: MedReg DE records a finding against a data user and the user responds within the four-week window.
Permits Register
The access body's register of applications received and permits granted, refused or revoked (Art. 57). Any signed-in participant can read it.
Example: A data holder checks which permits currently cover its datasets.
Activity Report
The access body's activity report under Art. 59(1)(a) to (k), generated from the graph for a chosen period, with a Markdown export.
Example: MedReg DE generates the report for the last 24 months before publishing it.
Secondary Use Information
What the access body tells the public about secondary use (Art. 58(1)): the legal basis, the safeguards, people's rights and how to exercise them, who has access to which datasets and why, and the results of the projects.
Example: A patient reads which research projects use data from AlphaKlinik Berlin and how to opt out.
Data Exchange
The sovereign data exchange pipeline follows the Dataspace Protocol (DSP 2025-1): share assets, discover via federated catalog, negotiate contracts, manage tasks, and transfer data. This pipeline implements EHDS Art. 33-34 requirements for making health data available while preserving data holder sovereignty through policy-controlled access.
Share Data
Publish datasets with HealthDCAT-AP metadata and ODRL access policies for the federated catalog. Define distribution endpoints, data quality attributes, and usage constraints. Data holders use this page to fulfil their obligation under EHDS Art. 33 to make data available for secondary use.
Example: AlphaKlinik Berlin publishes a "Synthetic Diabetes Cohort" dataset with FHIR R4 bulk export distribution, EHDS Art. 33 usage policy, and spatial coverage set to DE.
Discover
Search the federated catalog across all connected dataspace participants. Results aggregate datasets from multiple EDC connectors, showing availability and access terms. The federated catalog enables cross-border dataset discovery without centralising metadata.
Example: PharmaCo Research AG discovers 3 datasets across 2 participants for "cardiovascular" research — one from AlphaKlinik Berlin and two from Limburg Medical Centre.
Negotiate
Initiate and track DSP contract negotiations with data holders. View negotiation state (REQUESTED, AGREED, VERIFIED, FINALIZED), ODRL policy terms, and counter-offer history. Contract negotiation ensures that data access terms are mutually agreed before any transfer occurs, as required by EHDS Art. 34.
Example: PharmaCo Research AG initiates a contract negotiation with AlphaKlinik Berlin for the diabetes cohort. The negotiation progresses to FINALIZED with an EHDS Art. 33(c) research use policy.
Tasks
Monitor the task queue for pending and active data transfer operations. Tasks track the full lifecycle from initiation through provisioning to completion, providing the audit trail required by EHDS for accountability.
Example: The operator monitors a bulk FHIR export task from AlphaKlinik Berlin to PharmaCo Research AG — currently at the provisioning stage with an estimated 2-minute completion time.
Transfer
View the complete history of data transfers — both initiated and received. Each entry includes timestamps, transfer size, protocol used, and a link to the audit trail. Transfer logging implements the EHDS requirement for full traceability of all health data movements across the dataspace.
Example: PharmaCo Research AG reviews its transfer history showing a completed 12 MB FHIR bulk export from AlphaKlinik Berlin, transferred via HTTP-PUSH with full W3C PROV audit trail.
Administration
Platform administrators manage participants, access policies, and audit logs. The admin dashboard provides an overview of system health, active connections, and recent activity. Access requires the EDC_ADMIN role assigned through Keycloak. The operator role is defined by EHDS Art. 52 as responsible for ensuring the technical infrastructure supports interoperable, sovereign data exchange.
Operator Dashboard
The admin dashboard shows system health at a glance: connector uptime, active participants, recent negotiations, transfer throughput, and credential status.
Example: The operator sees all 5 participants are online, 3 contract negotiations are active, and 12 transfers completed in the last 24 hours with no failures.
EDC Components
Inspect the runtime status of Eclipse Dataspace Connector components — Control Plane, Data Plane, Identity Hub, Issuer Service, and the Connector Fabric Manager. View health checks, versions, and configuration details.
Example: The operator checks that the Control Plane (port 11003), the FHIR Data Plane (port 11002) and the Identity Hub (port 11005) all report healthy on the local stack.
Tenant Management
The participants' tenants in the Connector Fabric Manager: their virtual participant agents and provisioning state.
Example: The operator checks that a newly onboarded clinic's tenant finished provisioning.
Participant Directory
Every participant in the dataspace with its DID and credentials; the operator can add or remove one.
Example: The operator adds Limburg Medical Centre and confirms its DID resolves.
Audit & Provenance
The audit log and provenance trail, with the retention settings. Shared with the access body, which uses it for supervision.
Example: MedReg DE traces which queries touched a dataset in the last month.
Need Help?
For technical questions, see the Developer Guide. For architecture details, visit the Architecture Diagrams. Try the live demo at GitHub Pages.
For the complete end-to-end walkthrough of every persona and workflow, read the Full User Journey.