Get started as a developer

From zero to your first stored and queried health record in an afternoon. This guide gets you going, then hands you over to the full developer resources.

Start step 1Developer site

Seven steps to your first openEHR app

You’ll need Docker, a REST client such as Postman or curl, and a free account on the Clinical Knowledge Manager. No prior openEHR knowledge is needed.

  1. Understand the idea15 min

    openEHR keeps the data model out of your code. A small, stable reference model is shared by every system; clinical content is defined in archetypes; templates combine archetypes for a specific form or message. Your app works with templates, and the data stays meaningful long after your app is replaced.

    How openEHR worksThe science of clinical modeling

  2. Run a clinical data repository30 min

    A clinical data repository (CDR) stores and queries openEHR data. The quickest start is EHRbase, an open-source CDR that runs locally with Docker Compose. Once it’s up, the openEHR REST API is at:

    http://localhost:8080/ehrbase/rest/openehr/v1

    Prefer not to run your own? Several vendors offer sandboxes. See the platforms in the directory.

    EHRbaseEHRbase on GitHubPlatforms in the directory

  3. Get a template30 min

    Browse the Clinical Knowledge Manager for the archetypes you need, such as blood pressure. Then build a template in Archetype Designer and export it as an operational template (.opt). Upload it to your CDR:

    POST /definition/template/adl1.4
Content-Type: application/xml

(your .opt file)

    Clinical Knowledge ManagerArchetype Designer

  4. Store your first record20 min

    Create an EHR for a test patient, then save a composition (one filled-in instance of your template) to it:

    POST /ehr
→ returns an ehr_id

POST /ehr/{ehr_id}/composition
(your composition as JSON)

    Many CDRs can generate an example composition from your template, which is the easiest way to see the expected shape.

    REST API specification

  5. Query it with AQL20 min

    The Archetype Query Language (AQL) queries by clinical meaning rather than database tables, so the same query works on any openEHR system:

    POST /query/aql

SELECT
  o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic
FROM EHR e
  CONTAINS COMPOSITION c
  CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v2]

    AQL specification

  6. Build somethingOngoing

    Use low-code form tools to put a working form in front of users quickly, or use a library or SDK, such as Archie for Java, to build your own application on the API.

    Libraries and SDKsApplicationsModelling tools

  7. Join the communityOngoing

    Ask questions on Discourse, where developers and vendors answer daily. Contribute on GitHub, follow the Software Program and, when your product is ready, look at conformance testing.

    DiscourseGitHubSoftware Program

Stuck? Most first-day problems are a template that hasn’t been uploaded, or a composition that doesn’t match the template. Check the CDR’s error message: it usually names the exact path that’s wrong.

Keep learning

Get help

Where next?

openehr.org