Amy-Term
← Back to documentation

Amy-Term Quick Start Guide

Checklist

  1. Log in as Viewer or Admin
  2. Upload your first terminology (Excel / CSV / JSON)
  3. Create a ValueSet and test $expand
  4. Create a ConceptMap and test $translate
  5. Verify ATC search and $lookup
  6. (Optional) Configure federation and export a bundle

This guide is deliberately copy-paste oriented. Use the terminal blocks exactly as shown, replacing URLs with your own canonical URLs.

Step 1 — Log in and confirm basic UI access

Open the following pages in a browser. If you are not logged in, the system should redirect you to the login page. 

GET /codesystems
GET /valuesets
GET /tools
GET /atc/browser

Step 1.5 — Quick smoke tests

Ping a few public endpoints to confirm the terminology cache is serving artefacts: 

GET /codesystems
GET /valuesets
GET /atc/browser?q=A02AA05
GET /fhir/CodeSystem/$lookup?system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05
GET /fhir/ValueSet/$expand?url=http://amterm.local/fhir/ValueSet/example

Pair the hub lookups with CodeSystem/$validate-code to confirm the code is present (example below).

Step 2 — Import content

As an admin, import at least one CodeSystem. For ATC (Germany), use the dedicated ATC import page.

UI import pages

GET /atc/import
GET /codesystems/import   (if your build has a generic import page)
GET /valuesets/import     (if your build has a ValueSet import page)

After import, confirm that the CodeSystem appears in /codesystems, then use $lookup to validate data quality.

Step 3 — Validate CodeSystem lookup

Run a FHIR-style $lookup call against a known code (ATC example below). 

GET /fhir/CodeSystem/$lookup?system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05
Accept: application/fhir+json

FHIR $validate-code

Confirm a code exists in a particular CodeSystem using CodeSystem/$validate-code. 

GET /fhir/CodeSystem/$validate-code?system=http://example.org/CodeSystem/test&code=EX1234&version=1.0.0
Accept: application/fhir+json

If ATC enrichment is loaded, you should also see the additional ATC properties in the response.

Step 4 — Search in the ATC browser (independent of level)

The ATC browser search should work regardless of ATC hierarchy level. Search by code or by display text. 

GET /atc/browser?q=A02AA05
GET /atc/browser?q=omeprazole
GET /atc/browser?system=http://fhir.de/CodeSystem/atc-gkv&q=A02AA05&limit=50&offset=0

If you receive HTTP 422, check that your request does not repeat query parameters (for example, two limit values).

Step 5 — Create and test a ValueSet

Create a ValueSet using the UI (recommended via Tools & Designer) or via your ValueSet editor, then expand it via the FHIR endpoint.

UI

GET /tools
GET /valuesets

FHIR $expand

GET /fhir/ValueSet/$expand?url=http://amterm.local/fhir/ValueSet/example
Accept: application/fhir+json

FHIR $validate-code

GET /fhir/ValueSet/$validate-code?url=http://amterm.local/fhir/ValueSet/example&system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05
Accept: application/fhir+json

Step 6 — Create and test a ConceptMap

Create a small ConceptMap in Tools & Designer (for example mapping a local code to a national code), then test translation via $translate.

UI

GET /tools

FHIR $translate

GET /fhir/ConceptMap/$translate?source=http://fhir.de/CodeSystem/icd-10-gm&target=http://snomed.info/sct&code=F20.0
Accept: application/fhir+json

If you use a specific ConceptMap canonical URL, you can translate using url=... instead of source/target. 

GET /fhir/ConceptMap/$translate?url=http://amterm.local/fhir/ConceptMap/icd10gm-to-snomed&code=F20.0
Accept: application/fhir+json

Step 7 — Federation: capture and export only what you intend to distribute

Federation bundles should include only selected artefacts (not everything). The process is: Capture → Export → (Regional) Apply.

Capture selection (UI)

GET /federation/capture

Export bundle (API)

GET /federation/bundles/export?namespace=default&mode=artifacts&limit=200&include_payload=true&sign=true
Accept: application/json

Apply bundle (regional API)

POST /federation/bundles/apply?direction=import&store_artifacts=true&apply_to_store=true
Content-Type: application/json

{
  "bundle": { ... }
}

For offline distribution, export JSON on central, transfer the file, then apply it on regional nodes via the UI or API.

Step 8 — Quick smoke test set (recommended after every change)

GET /fhir/metadata
GET /codesystems
GET /valuesets
GET /atc/browser?q=A02AA05
GET /fhir/CodeSystem/$lookup?system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05
GET /fhir/CodeSystem/$validate-code?system=http://example.org/CodeSystem/test&code=EX1234
GET /fhir/ValueSet/$expand?url=http://amterm.local/fhir/ValueSet/example