Hi everyone!
I’d already built a working FHIR to DHIS2 sync tool - a Node CLI that polls a FHIR server on a schedule and pulls Immunization data into DHIS2 Tracker. That’s the right shape for that job: a DHIS2 App only runs while a browser tab is open, so anything that needs to run unattended has to live outside DHIS2. But that left a real gap - no way to configure it, trigger a run, or see what happened, without SSH access to a server. FHIR Sync Console is the same engine, given a browser control panel.
Why it goes through a DHIS2 Route, not a direct fetch:
The first draft of this assumed the app would fetch the FHIR server directly from the browser. DHIS2 updated its App Hub guidelines in March 2026 specifically to stop that - apps can’t hold third-party credentials in browser-readable code. So this goes through a DHIS2 Route instead: DHIS2 itself makes the outbound call, same-origin, credentials encrypted at rest, never returned to the browser.
What it does:
Settings, Preview, Confirm and sync, Run History. Preview runs the real fetch, map and classify pipeline with zero writes, so what you see in preview is exactly what a real run would do. Writes are batched up to 50 Tracker events per call. The one I’d actually highlight: every FHIR resource carries a meta.versionId - if it’s unchanged since the last sync, it’s skipped; if it changed, the existing DHIS2 event is updated, not duplicated.
Real bugs, not hypothetical ones:
A few things only showed up against real data, not test fixtures:
- HAPI’s own pagination “next” link for page 2+ has no resource-type path segment at all - the original code treated that as “no more pages” and silently stopped after page 1.
- @dhis2/app-runtime’s query layer only parses JSON when Content-Type is exactly application/json. A FHIR server correctly responds application/fhir+json, which fell through to being treated as a blob - every sync reported “fetched 0” even though the Route itself worked perfectly.
- canCreateRoutes checked for a literal ‘Route’ authority string that isn’t real - always false for anyone but a superuser. The actual authorities are F_ROUTE_PUBLIC_ADD / F_ROUTE_PRIVATE_ADD.
Verified against more than one server:
Live-verified against a real DHIS2 2.42.5 instance - Route creation, pagination, Tracker create and update. Against three independent public FHIR servers (HAPI, SMART Health IT, Firely), zero code changes, even though they don’t all paginate the same way. And against a real EMR, not just a sandbox - OpenMRS’s public demo - where real immunization records synced and were verified field-for-field on read-back.
What it doesn’t do, stated plainly:
No background execution - there’s no DHIS2-native job API to hook into, so it only ever runs on demand. No OAuth2 auto-refresh - a manually-rotated Bearer token works, a server that hard-requires live token negotiation doesn’t. Scoped to Immunization only today. And the sync engine and the original CLI share logic by duplication across two repos, not a shared import - a named risk that the two copies could drift, not something papered over.
Original post: FHIR Sync Console for DHIS2 Interoperability | Khalilur Rahman Ridoy Khan posted on the topic | LinkedIn
Has anyone else here built a FHIR-adjacent App Hub app, or hit similar Route/App Hub guideline issues? I’d be glad to compare notes.