User Guide
A practical guide for business users, researchers, and data stewards working with the Health Dataspace platform. Each section includes a screenshot, a description, and a link to the live demo.
Getting Started
After authenticating through Keycloak SSO, you can explore the knowledge graph, browse datasets, review patient timelines, run analytics, or check EHDS compliance status.
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.
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.
Example: Limburg Medical Centre joins the EHDS dataspace by providing its organization details, generating did:web:lmc.nl:clinic, and obtaining a MembershipCredential.
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.
Explore
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.
- 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.
Browse and search HealthDCAT-AP metadata records for all published datasets. Each entry shows title, description, publisher, temporal/spatial coverage, and distribution formats.
- 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.
View the clinical timeline for synthetic patients, showing FHIR R4 resources (Encounters, Conditions, Observations, Medications, Procedures) mapped to their OMOP CDM equivalents.
- 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.
Cohort-level research analytics powered by the OMOP CDM layer. Run aggregate queries across conditions, measurements, drug exposures, and procedures.
- 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.
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.
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.
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.
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.
Governance
The governance modules manage EHDS compliance, protocol testing, and verifiable credential issuance as required by the European Health Data Space regulation (Articles 45–52).
Manage data access permits as required by EHDS Articles 45–49. Data users submit applications, HDABs review and approve, and verifiable credentials are issued 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.
The Technology Compatibility Kit validates that your EDC connector implements the Dataspace Protocol (DSP) correctly. Tests cover catalog queries, contract negotiations, and transfer processes.
Example: The operator runs the TCK suite and confirms 20/20 tests passing — verifying DSP-compliant catalog, negotiation, and transfer process implementations.
View and manage verifiable credentials across all dataspace participants. Each participant holds a MembershipCredential and an EHDSParticipantCredential, issued by the trusted issuer service.
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.
Data Exchange
The sovereign data exchange pipeline follows the Dataspace Protocol: share assets → discover via federated catalog → negotiate contracts → manage tasks → transfer data.
Publish datasets with HealthDCAT-AP metadata and ODRL access policies for the federated catalog. Define distribution endpoints, data quality attributes, and usage constraints.
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.
Search the federated catalog across all connected dataspace participants. Results aggregate datasets from multiple EDC connectors, showing availability and access terms.
Example: PharmaCo Research AG discovers 3 datasets across 2 participants for "cardiovascular" research — one from AlphaKlinik Berlin and two from Limburg Medical Centre.
Initiate and track DSP contract negotiations with data holders. View negotiation state (REQUESTED → AGREED → VERIFIED → FINALIZED), ODRL policy terms, and counter-offer history.
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.
Monitor the task queue for pending and active data transfer operations. Tasks track the full lifecycle from initiation through provisioning to completion.
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.
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.
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 can manage tenants, access policies, and audit logs. The admin dashboard provides an overview of system health, active connections, and recent activity. Access requires the admin role assigned through Keycloak.
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.
Inspect the runtime status of Eclipse Dataspace Connector components — Control Plane, Data Plane, Identity Hub, Issuer Service, and Credential Federated Manager. View health checks, versions, and configuration details.
Example: The operator checks that the Control Plane (port 19193), Data Plane (port 19195), and Identity Hub (port 17171) are all reporting healthy status for AlphaKlinik Berlin's connector.
Need Help?
For technical questions, see the Developer Guide. For architecture details, visit the Architecture Diagrams. Try the live demo at GitHub Pages.