Start mapping a template

What you’ll do

You open a template in the Workspace, choose the archetype where every conversion starts, and add a model for each archetype the template contains, either by reusing a model that already exists or by creating a new one with the New model mapping wizard.

The Workspace showing the overview of the International Patient Summary template

The overview of the International Patient Summary template in the Workspace.

Before you start

Steps

Open the template

  1. Click Open Workspace in the sidebar, then the template’s card under Select a template to start mapping. From Engine state you can also select the template and click Open in workspace.

  2. The middle pane shows the template’s overview:

    The template overview with numbered callouts

    The start model 1, a model of an archetype 2, an extension model 3, a model’s problem count 4, and the context mapper button 5.

    START 1

    The start model, marked START: the model the engine begins every conversion with. Its card names the archetype and the FHIR type it maps.

    ARCHETYPE MAPPINGS 2

    Every other model of the template, with its archetype. The bar at the bottom of each card shows how many of the archetype’s elements it maps (8 / 10).

    Extension models 3

    An extension model sits under the model it extends, marked ↳, EXTENSION and extends <model>.

    Problem count 4

    The model’s errors and warnings. See Fix problems.

    <> 5

    Opens the template’s context mapper as YAML (Connect models: slots, links, references).

    NOT YET MAPPED

    The template’s archetypes no model maps yet, one Add mapping card each. This section only shows while there are some.

    Click a model’s card to open it in the editor (Edit mappings in the Workspace). The model crumb in the top bar (Select a model with its ▾) switches between the template’s models too.

Create the context mapper

A template you uploaded without a context mapper (the OPT alone) can’t be mapped yet. Instead of the overview, the middle pane shows New context mapper:

The New context mapper wizard on its profile step, with Bundle selected

The loaded profiles 1, adding one 2, a base resource 3 and Create context mapper 4.

  • 1 · Select the FHIR version the template maps to (R4 unless you change it), then click Next.

  • 2 · Which FHIR profile does the template map to? Pick a profile from the loaded FHIR packages 1, add one by uploading a StructureDefinition or package or fetching one from the registry 2, or pick a base resource such as Bundle 3. Only profiles on resources are offered. The engine picks this context for an incoming FHIR resource whose meta.profile names the profile; a base resource fits when every conversion names the template.

  • Click Create context mapper 4. Atlas names the context mapper after the template and fills in the template id. It lists no models and has no start yet: the overview appears, and the next steps add both.

Choose the start archetype

A freshly uploaded template has no start. The START section then shows Choose a start archetype for this template 1.

The overview with no start and one archetype not yet mapped

No start yet 1; one archetype is not yet mapped 2.

  1. Click Choose a start archetype for this template. The Choose a start archetype dialog lists:

    • Mapped: the template’s models. Click one to make it the start.

    • Not yet mapped: the archetypes no model maps. Click one to add a model for it, which becomes the start (the steps below, without a slot: nothing slots in the start).

    The Choose a start archetype dialog

    One mapped model and one archetype not yet mapped.

    Usually the start is the template’s COMPOSITION archetype. Atlas writes your choice into context.start of the context mapper and keeps the rest of the file as written.

Add a model for an archetype

  1. Under NOT YET MAPPED, click the Add mapping card of the archetype.

    An Add mapping card under Not yet mapped

    The observation archetype has no model in this template yet.

  2. If a model for this archetype already exists in the engine (in another template), Atlas asks Use an existing mapping? + Slot in the template coverage opens the same dialog, with its occurrence chosen; it also lists this template’s own models of the archetype, under In this template, before those In other templates.

    The Use an existing mapping dialog

    Where it is slotted in 1, or not yet 2; a model to reuse 3; or New model… 4.

    • Slot into 1 lists every place in the template where this archetype occurs, with the model that will hold the slot mapping and its openEHR path. The first usable place is chosen for you; see Connect models: slots, links, references for how slotting works.

    • Don’t slot it now 2 adds the model to the context only.

    • With a place chosen, FHIR resource asks whether the model maps the same resource as the enclosing model or enters a new one (Slot a model that maps another resource). The default follows each model’s type.

    • Click a model 3 to reference it into this template. With a place chosen, Atlas also adds the slot mapping to the enclosing model and opens that model on the new mapping. Without one, it opens the reused model.

    • New model… 4 goes on to the next step.

    While you slot the model in, extension models aren’t offered: an extension merges into its core model, so nothing can slot it.

  3. Name the new model. The dialog (titled Add mapping when it offers a place to slot the model in, Name the mapping otherwise) asks for the Model name (metadata.name).

    The Add mapping dialog with Slot into and the model name

    Where it is slotted in 1 and the model’s name 2.

    The name is filled in from the chosen place (made unique if a model of that name exists), or from the archetype id. It follows your choice of place until you type your own. Click Continue (or press Enter).

Create the model with the wizard

The New model mapping wizard opens in the middle pane. Its header names the archetype and, when the model will be slotted in, where: Will be slotted into <model> at <path> 1. Once you pick what the model maps (step 2), the header also asks under FHIR resource whether it maps the same resource as that model or enters a new one; the default follows the two types (Slot a model that maps another resource).

  1. 1 · Select the FHIR version: STU3, R4 (the default) or R5 2. Click Next.

    Step 1 of the wizard, the FHIR version

    Where the model will be slotted in 1, and the FHIR version 2.

  2. 2 · What does this model map to? Choose a profile, a base resource or a data type.

    Step 2 of the wizard, profiles, base resources and data types

    Search 1, profiles of the loaded packages 2, add a profile 3, base resources 4, and the choice 5.

    • Type in Search profiles, resources and data types… 1 to narrow all three lists.

    • Profiles (loaded FHIR packages) 2 lists the profiles of the packages loaded for this FHIR version. Picking a profile also picks its type (shown next to it). With none loaded, the list says No profiles loaded for FHIR <version> yet — add one below.

    • To add a profile on the spot 3, click Upload profiles / packages, pick one or more files (StructureDefinition .json, .tgz packages up to 15 MB, or a .zip of them) and click Upload N files, the same as on FHIR packages (Use FHIR profiles and IG packages). Or type a package as name#version in or fetch: hl7.fhir.uv.ips#1.1.0 and click Fetch. Atlas loads it into the FHIR packages and, when the added packages hold a single profile (or a single resource profile), selects it for you: Added <package>#<version>: selected <profile> (<type>).

    • Base resources (no profile) 4 and Other data types map the plain FHIR type.

    • The line at the bottom 5 says what you picked: Selected: <profile> (profile on <type>) or Selected: <type> (base, no profile).

    Click Next.

  3. 3 · Extends (optional): to make an extension model, pick the model it extends. The list holds the engine’s models for the same archetype. Leave None to start fresh.

    Step 3 of the wizard, Extends

    Extends 1: None, or a model of the same archetype.

  4. Click Create model. Back returns to the previous step; on the first step it is Cancel.

Atlas creates the model and adds it to the template’s context (and sets it as the start when you came from Choose a start archetype). With a place chosen, it adds the slot mapping to the enclosing model and opens that model on it, with the FHIR path focused: fill in where the slotted resource goes in FHIR. Otherwise the new, empty model opens.

The enclosing model with the new slot mapping selected

The new slot mapping in the enclosing model: its Slot archetype 1 names the new model; the FHIR path is still to fill in.

Check it worked

Tips

Tip

Pick the profile rather than the base type when you have one. The model then keeps the base type as its structureDefinition and gets a meta mapping that writes the profile into meta.profile. That profile drives the path suggestions, the checks, profile coverage and validation (Validate against FHIR profiles).

Tip

Reuse a model when the same archetype is mapped the same way in another template. Reusing keeps one model for both, so a fix applies to both.

Tip

To map a slightly different variant of an existing model, create an extension model (step 9) rather than a copy. See Fixed values, codes and manual pairs for what an extension model’s mappings can do.

Watch out

Warning

A model you add with Don’t slot it now is in the context, but no conversion runs it until a slot links it. Its card shows Not linked; see Connect models: slots, links, references.

Warning

Reusing a model shares it: editing it later changes it for every template that uses it.

If something goes wrong

What you see

What it means and what to do

Failed to create the context mapper (or the engine’s reason) under New context mapper

The engine didn’t store the context mapper. Template '<id>' already has a context mapper means one was added meanwhile (an upload, another user): reload the page.

Failed to set start or The context YAML doesn't parse: … in the start dialog

The context mapper couldn’t be read or saved. Open it with <> and fix the YAML (Connect models: slots, links, references).

Context YAML has no `context` block to set `start` on

The context mapper lacks its context: block. Add it with <>.

Failed to reference model in Use an existing mapping?

The engine refused to add the model to this context. The rest of the message is its reason.

<model> has no model to hold the slot — choose a start / map it first under a place in Slot into

The archetype that encloses this place has no model yet. Choose a start, or map the enclosing archetype first.

<model> already maps elements inside <occurrence> — a model slotted in would map them twice under a place in Slot into

The enclosing model maps this occurrence inline. Keep those mappings and choose Don’t slot it now or another place, or remove the inline mappings first.

Reading the template structure… in Slot into

Atlas is still reading the template; the places appear once it is done.

Failed to load FHIR types in step 2

The FHIR type list couldn’t be loaded. Go back to step 1, pick another FHIR version and then yours again: the list is loaded again.

Packages are limited to 15 MB

The file is too big to add here.

Failed to add the profile (or the engine’s reason)

The StructureDefinition or package couldn’t be stored or fetched. See Use FHIR profiles and IG packages.

Added <package>#<version>; its profiles are still loading or it has none for FHIR <version>.

The package is stored but no profile of it shows yet. Wait a moment and search again, or check the package’s FHIR version.

Failed to create model (or the engine’s reason)

The model couldn’t be created, for example because its name is taken. Go Back to step 1, click Cancel, and add the mapping again with another name.

After the model exists, the Problems dock may show the start names no model, a model nothing reaches or a model without mappings. Other notices are listed in Messages and notices A–Z.