From ePA 2.6 to 3.0: A Technical Journey in Healthcare Data Integration for Electronic Patient Records
…so far
Germany has a bad reputation for digitalisation, so the government’s push to implement an electronic patient record (“elektronische Patientenakte” or ePA) for its citizens and residents is a step in the right direction.
As an official digital health application (“digitale Gesundheitsapplikation” or “DiGA”), we are obligated to shift to the ePA 3.0 implementation. The government rollout has been plagued with technical difficulties and delays, but we’re now at a point where we have completed our implementation successfully, pending BfArm approval.
In this post, I want to cover the exact steps we and had to take to achieve this. I want to thank Senior Product Manager Tanja Lembcke and Senior Backend Engineer Chaythanya Sivakumar for their contributions to this piece.
The Challenge: Connecting Patient Data Across Systems
The electronic patient record (ePA) and HealthID integration project had a clear mission: we wanted to give our patients the ability to log into the HelloBetter platform using their HealthID (which they access through their insurance company) and export their HelloBetter data into their ePA.
A successful implementation would mean that both doctors and patients can electronically access therapeutic data whenever they need it. To make this happen for the patient data at HelloBetter, we partnered with two key players: RISE for ePA system access and Azuma for HealthID system access.
Our journey began in 2024 when our backend team laid the groundwork for ePA 2.6, setting up the pipeline and data export in our staging environment. We successfully implemented both PDF and XML document writing capabilities, along with the frontend and backend integrations for HealthID login.
How It All Works: The Architectural Side
HealthID Authentication
The first piece of the puzzle is connecting to and authorising the user’s HealthID. This part of the system has remained stable and continues to work smoothly.
When a user wants to log in, they select “Log in with HealthID” in our platform, which takes them to their health insurance app. After logging in and authorising the necessary data sharing, they bounce back to HelloBetter, and we receive their user attributes from the IDP Federation.
The ePA Connection: Then and Now
In the ePA version 2.6 implementation, our setup required a physical card terminal located in our Berlin office that used a specialised (dummy) health insurance card to access the RISE connector. The system involved complex authentication processes and careful data formatting to ensure successful transmission. The connection flow was more direct compared to 3.0: once authenticated through the card terminal and connector (both provided by RISE), we could begin the data upload process.
Version 3.0 introduced additional security layers through the trusted execution environment (“Vertrauenswürdige Ausführungsumgebung” or “VAU”) in connection with the identity provider (“Identitätsprovider” or “IDP”) service.
The new process follows these steps:
- We use the card terminal for initial VAU channel authorisation.
- The VAU channel has a chat with the IDP service to authenticate itself.
- The IDP service sends us a code.
- We ping that code back to the VAU to confirm our authentication.
- The VAU responds with another code giving us the all-clear.
- Only then can we start sending data through the VAU to the ePA system.
Technical Implementation Details
Contributed by Chaythanya Sivakumar, Senior Backend Engineer
VAU Channel Setup and Authentication
In our application, we leverage the Gematik VAU library (GitHub — gematik/lib-vau) to implement the initial key negotiation process and obtain the VAU-CID.
The VAU authentication process involves two key steps:
- Initial Channel Setup: The VAU handshake process establishes the secure communication channel.
- User Authentication via IDP Service: Once the channel is established, we authenticate it using the IDP service to receive a VAU-NP (VAU-Nutzerpseudonym), which is required for all subsequent communications.
Document Upload Specifications
The system has strict requirements for document formats and verification:
Supported Document Formats:
- application/pdf (PDF/A only) — .pdf
- text/plain — .txt
- application/fhir+xml — .xml
- application/json — .json
PDF/A Compliance: Due to security concerns around executable code, only specific PDF/A formats are accepted:
- PDF/A-1a
- PDF/A-1b
- PDF/A-2a
- PDF/A-2u
- PDF/A-2b
Implementation Architecture
Our data upload process follows these key steps:
- PHR Service Port Configuration
- Configure CXF client with custom transport and security settings
- Apply MTOM (Message Transmission Optimisation Mechanism) for efficient binary data transmission
- Set HTTP client policies
3. Header Creation: Generate headers with required clientSystemId, mandantId, and workplaceId
4. SOAP Message Handling
- Utilize the diga-epa-lib to create
ProvideAndRegisterDocumentSetRequestTypeSOAP responses - Implement SOAP interceptors for outgoing message encryption
- Use
CxfVauReadSoapInterceptorfor response decryption
Technical Evolution and Solutions
During the transition, we encountered and resolved several technical challenges. The most significant were connecting to the VAU itself; and once that was established the difficulty became adapting to new data formatting requirements.
While version 2.6 utilised a specific library for formatting PDF and XML data, version 3.0 required us to construct SOAP requests manually according to the DiGA MIO standard.
Unfortunately, the DiGA MIO website is not so easy to get answers out of, and requires meticulous combing to ensure that you not only send all the required fields, but that the fields of your own data are formed to the exact namings and conventions that it stipulates.
Notably, the official site is also not available in English. Normally this would be expected of German bureaucracy, but it’s a known reality that a huge proportion of software engineers in Germany are English-speaking. This means that many teams, not just ours, will be battling the confusing documentation and the German language at the same time.
Our engineering team successfully implemented these changes, ensuring our data formatting aligned with the new specifications and field requirements despite the above challenges.
Throughout the process, we also received invaluable support from Stefan Pratsch and Jonas Brüstel at Significo, who had already completed a successful ePA 3.0 migration themselves. They shared their firsthand experience with us, providing an overview of the various steps involved in the process and introducing us to several libraries and tools that had proven useful for their own migration. Their guidance was especially helpful during a technical huddle focused on formulating the IDP payload, where they walked us through their custom solution and clarified some of the more challenging aspects of this step.
Looking Ahead in the Regulatory Landscape
The Federal Institute for Drugs and Medical Devices (BfArm) plays a crucial role in overseeing digital health applications in Germany. As a regulatory body, they must approve any significant changes to medical devices or digital health applications to ensure patient safety and system integrity.
This means that although we consider our implementation to be “Done” in the Jira sense, the feature itself exists behind a feature flag which is only selectively enabled in our staging environment.
Submitting to BfArm means sending an explanation of our implementation, complete with screen recordings and logs demonstrating succesful writing of data to the ePA systems. It remains to be seen whether they will approve our implementation, but we and other DiGAs remain patient to see if our interpretation of their system has been accurate.
Banding Together as DiGA Providers
My team and I have had to talk to several other DiGA providers to get this system working. Everywhere we go, the responses and stories are almost identical to our own.
- A lot of information and companies purporting to have solutions
- Very few actual examples of it happening
Without naming names, I’d like to thank all of the individuals and companies who have helped us to navigate this system.
I am also yet again reminded of the pure skill of good technical writing, and I hope only that the German government will invest in multi-language, clear API documentation in future, that prioritises clarity and simplicity.
