Prerequisites

openEHR Explorer is a native desktop application. There are no runtime dependencies — you do not need Java, Docker, Node.js, or any other runtime installed to use it.

System Requirements

• macOS: macOS 12 (Monterey) or later
• Windows: Windows 10 (version 1803) or later
• Linux: Ubuntu 22.04+, Fedora 37+, or equivalent (WebKit2GTK required)
• Disk space: ~10 MB

You will also need access to an openEHR CDR instance (such as EHRBase or Better Platform) to connect to. The app does not include a built-in CDR.

Installation

macOS

Download the .dmg file from GitHub Releases. Open the DMG and drag openEHR Explorer to your Applications folder. Or install via Homebrew:

Not yet notarized by Apple — see Troubleshooting if macOS reports the app as damaged on first launch.

Windows

Download the .exe installer from GitHub Releases and run it. The app will be added to your Start menu. Or install via Scoop:

Not yet Authenticode-signed — Windows SmartScreen may warn on first launch; click “More info” → “Run anyway”. winget support is planned.

Linux

apt (Debian/Ubuntu, recommended): a self-hosted apt repository is published at platzhersh/apt-openehr-explorer and updated automatically on every release, so once added, updates arrive via the normal apt upgrade flow.

Two package formats are also published directly on GitHub Releases for each version, for a one-off install or a distro without apt: a .deb package (Debian/Ubuntu) and a portable .AppImage (any distro).

Debian/Ubuntu (.deb, manual download):

AppImage (any distro):

An AUR package (open-ehr-explorer-bin) is prepared and will be published once AUR account registration — currently paused archive-wide — reopens.

First Connection

After installing and launching the app, follow these steps to connect to your first openEHR CDR:

1. Click Servers in the sidebar to open the Server Manager.
2. Click "+ Add Server".
3. Enter a display name (e.g., "Local EHRBase").
4. Enter the base URL of your CDR (e.g., http://localhost:8080/ehrbase).
5. Select the server type: EHRBase, Better Platform, or Generic.
6. Choose an authentication method:
   • None — for unauthenticated servers
   • Basic — enter username and password
   • Bearer — enter an access token
7. Click "Test Connection" to verify.
8. Click "Save".

The server now appears in the sidebar switcher at the top. Select it to start browsing EHRs, templates, and running queries.

Server Manager

The Server Manager lets you create, edit, and delete server profiles. Each profile stores a connection configuration for a specific openEHR CDR instance.

• Supports EHRBase, Better Platform, and generic openEHR REST servers.
• Each profile stores: display name, base URL, server type, and authentication method.
• Test Connection validates the configuration before saving.
• Switch between servers instantly using the sidebar dropdown — no restart needed.

Server profiles are stored locally and never sent to any external service. You can configure as many profiles as you need.

Server Version Detection

Each server profile displays the detected CDR version on the profile card. Version detection happens automatically when you test a connection or connect to a server.

• EHRBase: Fetches version from GET /rest/status (displays ehrbase_version)
• Better Platform: Fetches version from OPTIONS /rest/v1 (displays solutionVersion)
• Generic: Version detection not available — liveness check only

Click the "Test" button on any profile card to verify connectivity and refresh the version number.

EHR Browser

The EHR Browser displays a paginated list of all Electronic Health Records from the connected CDR.

• Click any EHR to expand it and see its compositions grouped by template.
• Click a composition to open it in the Composition Viewer.
• Create EHR: Click "+ New EHR" to create a new record with optional subject identity, external references, and custom EHR ID.
• Delete EHR: Open an EHR's detail view and click "Delete EHR". You must type the EHR ID to confirm — this prevents accidental deletion.

The browser uses AQL-based listing for efficient pagination, even on CDRs with thousands of records.

Search

The EHR Browser supports powerful server-side search using typed attribute syntax. All searches execute AQL queries against the CDR and are visible in the Request Inspector.

Search Syntax

Enter search terms in the search bar using these attribute filters:

Combining Search Terms

Combine multiple terms with spaces (implicit AND logic):

Search Help

Click the ? icon next to the search bar to view the full syntax reference and examples.

Composition Viewer

The Composition Viewer provides three synchronized views of any composition:

• Pretty view: A structured tree rendering with human-readable archetype labels. Archetype node IDs like at0006 are replaced with their display names (e.g., "Any Event").
• JSON view: The raw canonical JSON representation as returned by the CDR.
• FLAT view: A key-value representation using FLAT paths — ideal for SDK developers building or debugging FLAT compositions.

The Path Panel on the right shows all FLAT paths from the Web Template. Click any path to copy it to your clipboard.

You can also navigate between composition versions, edit compositions (opens the Composition Form), and delete compositions from this view.

Template Browser

The Template Browser lists all templates uploaded to the connected CDR.

• Click a template to inspect its Web Template tree structure interactively.
• Expand nodes to explore archetypes, data types, constraints, and cardinalities.
• Upload OPT: Upload Operational Template XML files directly from the browser.
• New Composition: Click "New Composition" on any template to create a composition using that template's form.
• Lifecycle indicator: Each template shows a badge for its governance/publication state (e.g. Published, Draft). Click the ? icon next to the badge for an explanation of each lifecycle state.
• OPT XML view: The raw Operational Template XML is pretty-printed with indentation so large templates stay readable.

AQL Runner

The AQL Runner is a query editor for the Archetype Query Language (AQL), the standard query language for openEHR data.

• Write AQL queries with syntax highlighting and intelligent autocomplete.
• Execute queries against the connected CDR and see results in a sortable table.
• Save queries: Save frequently used queries with a name and description for quick access.
• Export CSV: Export query results as CSV files for further analysis.
• Format: Auto-format queries with the Format button or Shift+Alt+F.
• Execute: Run queries with Ctrl/Cmd + Enter.

Intelligent Autocomplete

The AQL editor provides three layers of context-aware autocomplete powered by CodeMirror:

Layer 1: Keywords & RM Types

Autocomplete for AQL keywords and openEHR Reference Model types:

• Keywords: SELECT, FROM, WHERE, CONTAINS, ORDER BY, LIMIT, etc.
• RM Types: EHR, COMPOSITION, OBSERVATION, EVALUATION, INSTRUCTION, ACTION, etc.
• Functions: COUNT(*), MAX(), MIN(), SUM(), AVG()

Layer 2: Static RM Paths

After typing an alias followed by / (e.g., e/, c/), autocomplete suggests standard RM paths:

• EHR paths: ehr_id/value, time_created/value, ehr_status/subject/external_ref/id/value, etc.
• COMPOSITION paths: uid/value, name/value, archetype_details/template_id/value, context/start_time/value, etc.

Layer 3: Template-Aware Paths

Select a Context Template from the dropdown to enable template-specific path completions. When you type an archetype-constrained alias (e.g., obs/ for an OBSERVATION), autocomplete suggests actual data paths from the Web Template:

• Paths are extracted from the selected template's Web Template definition
• Completions show human-readable labels with RM type hints
• Full AQL paths are inserted automatically

Example: With a vital signs template selected, typing obs/ suggests paths like data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude with the label "Systolic".

FLAT Path Panel

The FLAT Path Panel is available in both the Composition Viewer and the Template Browser. It displays the full FLAT path for every node in the Web Template.

• One-click copy: Click any path to copy it to your clipboard.
• Paths follow the Web Template FLAT format — useful for building FLAT compositions programmatically with SDKs like oehrpy.
• Search and filter paths by keyword.

Example FLAT path:

Request Inspector

The Request Inspector is a bottom drawer panel that captures every HTTP request openEHR Explorer makes to the connected CDR. It provides full visibility into the API conversation for debugging and learning.

Opening the Inspector

• Keyboard shortcut: Cmd+Shift+I (macOS) / Ctrl+Shift+I (Windows/Linux)
• Toggle between three height states: Collapsed (tab bar only), Half (default), Expanded (full window)
• Red dot badge on collapsed tab indicates recent 4xx or 5xx errors

Request Log

The left pane shows a reverse-chronological list of all CDR requests:

• Color-coded method badges: GET (blue), POST (green), PUT (amber), DELETE (red)
• HTTP status color coding: 2xx (green), 3xx (blue), 4xx (orange), 5xx (red)
• Request duration in milliseconds
• Filter by method, status class, or URL path
• Most recent entry is auto-selected

Request Detail Panel

The right pane shows full details of the selected request, with two tabs:

Request Tab

• Summary: Method, URL, duration, timestamp
• Request Headers: Key-value table with copy buttons
• Request Body: Shown for POST/PUT requests in Tree/Raw/FLAT views
• Copy as curl: One-click to copy a complete curl command that reproduces the exact request

Response Tab

• Summary: Status code, content type, response size
• Response Headers: Key-value table with copy buttons
• Response Body: Three view modes:
  • Tree View (default): Interactive, collapsible JSON tree with openEHR-aware rendering (_type pills, archetype labels, DV type formatting)
  • Raw JSON: Syntax-highlighted, read-only JSON editor with line numbers
  • FLAT View: FLAT path → value table (available when response contains a composition)

Use Cases

• Debugging: See exactly what was sent when a composition was rejected with 422
• Learning: Understand what a CREATE EHR request looks like (method, URL, body, response)
• Reproduction: Copy as curl to reproduce requests in CI or external tools
• Verification: Verify that stored compositions contain correct FLAT path values

Server Profiles

Server profiles are stored locally on your machine:

• Linux/macOS: ~/.config/openehr-explorer/profiles.json
• Windows: %APPDATA%\openehr-explorer\profiles.json

Server Types

The server type determines how API URLs are constructed:

Authentication Methods

• None: No authentication headers sent. Use for local development servers.
• Basic: HTTP Basic Authentication with username and password. Credentials are stored locally (not encrypted).
• Bearer: Authorization header with a Bearer token. Useful for OAuth2-based CDR deployments.

Keyboard Shortcuts

Troubleshooting

"Connection refused"

Verify that your CDR is running and that the base URL in your server profile is correct. If using EHRBase locally, ensure the Docker container is started:

"401 Unauthorized"

Check your authentication credentials in the server profile. For Basic auth, verify the username and password. For Bearer auth, ensure the token has not expired.

"CORS errors"

openEHR Explorer uses Tauri's native HTTP client, which does not go through a browser engine — CORS does not apply. If you see CORS-related errors, you may be running a development build via npm run tauri dev where the Vite dev server proxies requests.

"Template not found" when creating a composition

Ensure the template has been uploaded to the CDR. Go to Template Browser, verify the template appears in the list, and try again.

macOS: "openEHR Explorer is damaged and can't be opened" (Gatekeeper)

Release builds aren't code-signed and notarized by Apple yet, so Gatekeeper quarantines the app on first launch and reports it as damaged — it isn't actually corrupted. Clear the quarantine attribute and open it normally:

This is a one-time step per install. brew install --cask prints this same instruction automatically as a caveat; direct downloads don't get a prompt, so you may need to run it yourself.

Changelog

v0.6.0 — FerroEHR Support & Default Server Profile

• FerroEHR Support: Added FerroEHR as a recognized server type, including automatic version detection against its unauthenticated status endpoint
• Default Server Profile: Server profiles can now be marked as the default, so it's preselected automatically on app start instead of requiring a manual switch every time
• AQL Autocomplete Fix: Pressing Enter or Escape to accept or dismiss an AQL autocomplete suggestion now works correctly instead of inserting a newline or falling through to the editor

v0.5.2 — AQL Editor Highlighting Fix

• AQL Syntax Highlighting: Fixed a regression from the previous release where standard SQL keywords (SELECT, FROM, WHERE, and others) stopped being highlighted in the AQL editor while openEHR-specific keywords were added

v0.5.1 — Linux APT Repo & AQL Editor Highlighting

• APT Repository: Debian/Ubuntu users can now install and update via a signed apt repository, published automatically on every release alongside the existing .deb download
• AQL Syntax Highlighting: The AQL editor now highlights openEHR-specific keywords (CONTAINS, EHR, COMPOSITION, MATCHES, EXISTS, and more) the same way it already highlighted standard SQL keywords
• Landing Page Refresh: Real product screenshots and a demo clip replace the old hero mockup, with a fullscreen lightbox for browsing the screenshot gallery and OS-aware download button text

v0.5.0 — Manual Update Checks

• Check for Updates: Added a “Check for Updates…” item to the native app menu (macOS app menu, Windows/Linux Help menu) that triggers the same check as the Settings page button
• Update Download Fix: Fixed a crash that could occur while downloading and installing an update

v0.4.3 — Windows Install & Server Form Refresh

• Windows Install via Scoop: scoop install openehr-explorer now works against the published Scoop bucket, auto-published on every release (winget support still planned)
• Server Form Modal: Add/Edit Server now opens in a modal dialog instead of an inline panel, for a cleaner server management workflow
• Linux Install Docs: Install instructions now cover the .deb package alongside the AppImage
• Troubleshooting: Documented the macOS Gatekeeper “damaged” workaround for unnotarized builds

v0.4.2 — Signed Auto-Updates & Homebrew

• Working Auto-Update: The updater now signs releases with a real Tauri signing key, so in-place updates actually verify and install (previous versions shipped the updater unsigned)
• Homebrew Cask: brew install --cask platzhersh/openehr-explorer/openehr-explorer is now published and auto-updated on every release
• SEO basics: Sitemap, Open Graph/Twitter metadata, and Google Search Console verification for the product website

v0.4.1 — Windows Icon Fix

• App icon: Replaced the single-size Windows .ico with a multi-resolution icon so the app looks correct in the Start menu, taskbar, and title bar at all sizes

v0.4.0 — Template Lifecycle & OPT Readability

• Template Lifecycle Indicator: Templates now show a lifecycle badge (Published, Draft, etc.) with a contextual help popover explaining each state
• Pretty-Printed OPT XML: The raw Operational Template XML view is now indented for readability
• VirusTotal Scanning: Windows installers are automatically submitted to VirusTotal on tagged releases

v0.3.0 — Auto-Update, Analytics & Security Hardening

• Auto-Update: Built-in updater checks GitHub Releases on startup and installs signed updates in-place (toggleable in Settings)
• Secure Credential Storage: Server profile credentials are stored in the OS keychain, with an encrypted-file fallback when no keychain is available
• Opt-in Usage Analytics: First-run consent dialog enables anonymous Aptabase telemetry to guide development — off by default and switchable any time from Settings
• Security Hardening: Strict Content Security Policy, Subresource Integrity for CDN assets, and URL validation for server profiles
• Settings Files Panel: View and open the app's config, profile, and log directories directly from Settings
• Documentation Shortcut: New Documentation link in the sidebar with a keyboard shortcut for quick access

v0.2.0 — EHR Browser Search & Enhanced Features

• EHR Browser Search: Server-side AQL-backed search with attribute filters (subject, namespace, system, modifiable, hasCompositions)
• Server Version Detection: Auto-detect and display CDR version for EHRBase and Better Platform
• Global Keyboard Shortcuts: Navigate with Cmd+1-4, open settings with Cmd+,, toggle inspector with Cmd+Shift+I

v0.1.0 — Initial Release

• EHR Browser: Paginated listing, create, delete EHRs
• Composition Viewer: Pretty / JSON / FLAT views, path panel, version navigation
• Composition CRUD: Create, edit, delete compositions in FLAT format
• Template Browser: List templates, inspect Web Template tree, upload OPT
• AQL Runner: Execute queries with 3-layer autocomplete (keywords, RM paths, template-aware paths), sortable results table, saved queries, CSV export, auto-format
• Server Manager: Multi-server profiles with EHRBase and Better Platform support
• Request Inspector: View raw HTTP requests/responses for debugging with Tree/Raw/FLAT views, copy as curl