# Use FHIR profiles and IG packages ## What you'll do You load the Implementation Guide (IG) packages whose profiles your models produce, for example the International Patient Summary, or your own profiles, value sets and code systems as loose files. With the package loaded, the Workspace follows your profiles: path suggestions show profile cardinality, must-support, slices and extensions; checks report elements the profile forbids; the Profile tab counts the profile's required and must-support elements; and validation checks the FHIR against the profile. What else a package is used for is under {ref}`packages-what-is-used`. ```{figure} ../images/codes-and-profiles/packages.png :class: screenshot :alt: The FHIR packages page with the IPS package expanded, a missing dependency and a package that didn't load The FHIR packages page after adding the IPS package. ``` ## Before you start - Open **FHIR packages** in the sidebar (under **Mappings**). - Have the package ready: its `.tgz` (as published on a package registry or by the IG's build), or its `id#version` on `packages.fhir.org`. Or have the loose resources ready: StructureDefinition, ValueSet and CodeSystem `.json` files, Bundles of them, or a `.zip` of such files (for example an IG's `definitions.json.zip`). Core FHIR (`hl7.fhir.r4.core` …) is built in; don't add it. - A model's profile is its `structureDefinition`, or the profile it writes into `meta.profile` ({doc}`/map/start-mapping`). ## Steps ### 1. Add a package Under **Add a package**, the numbers match the screenshot above: [1]{.callout} **Drop files**: drop npm packages `.tgz`, conformance resources `.json` or a `.zip` of them on the area, or click **browse**. You can pick several files, and drop or browse again to add more. The files are listed first; nothing is uploaded yet: ```{figure} ../images/codes-and-profiles/upload-files.png :class: screenshot :alt: Three files listed for upload, the package name and the Upload button A package, a StructureDefinition and a ZIP, ready to upload: leave a file out [1]{.callout}, the name for the loose resources [2]{.callout}, and **Upload** [3]{.callout}. ``` - Each `.tgz` is stored as the package it is, up to 15 MB. - StructureDefinitions, ValueSets and CodeSystems (loose `.json`, Bundles, and the `.json` files in a `.zip`) are stored together as one package. - ConceptMaps go to **Terminology** ({doc}`conceptmaps`), where mappings use them. - Other files in a `.zip` (examples, a README) are skipped. The cross next to a file leaves it out; **Cancel** drops them all. **Package name for the loose resources**: shown when there are `.json` files or a `.zip`. Leave it empty and Atlas names the package after the `.zip` (`local.`), else after the first profile (`local.`). The package takes the first profile's version (`0.0.1` when it has none), so uploading the same resources again under the same name replaces the package. A name uses letters, digits, `.`, `-` and `_`. **Upload N files** uploads them. When one file can't be stored, Atlas stores none of them and says which file and why; the files stay listed so you can fix the list and upload again. Afterwards the card says what was stored: ```{figure} ../images/codes-and-profiles/upload-result.png :class: screenshot :alt: Stored two packages, one ConceptMap added to Terminology, one file skipped What an upload stored, and the file it skipped with the reason. ``` [2]{.callout} **From packages.fhir.org**: type `package-id#version`, for example `hl7.fhir.uv.ips#1.1.0`, and click **Fetch**. **Fetch** is enabled once the text has that form. This form is missing when fetching from a registry is turned off for your Atlas. While Atlas works, the card says "Uploading …" (or "Uploading files…") or "Fetching #…". ### 2. Add what it depends on A package needs the packages it depends on. When one isn't loaded, **Missing dependencies** lists it: "Profiles from these packages (extensions, base profiles, value sets) can't be resolved until they're added." [3]{.callout} **Fetch**: fetches that dependency from the registry. Without a registry, upload its `.tgz` instead. ### 3. Check the packages [4]{.callout} **A package**: its id, `#version`, the FHIR version, then the number of profiles, the size, the date it was last updated, and **used by N models** when models of any template produce one of its profiles. Click the chevron to see what it **Depends on** and its profiles: **Profile** (title and url), **Type** (`(extension)` for extension definitions), and **Used by**. [5]{.callout} **Used by**: the models whose profile this is, across all templates. [6]{.callout} **not loaded**: the package is stored but couldn't be read for its FHIR version. Hover it for the reason. Its profiles aren't used. [7]{.callout} **Remove package** (step 4). **Refresh** at the top reloads the list. ### 4. Remove a package Click the trash icon of the package. Atlas asks first: ```{figure} ../images/codes-and-profiles/remove-package.png :class: screenshot :alt: The confirmation to remove hl7.fhir.uv.ips#1.1.0 "Remove hl7.fhir.uv.ips#1.1.0? Models using its profiles fall back to base FHIR." ``` (packages-what-is-used)= ## What Atlas uses from a package Atlas reads every StructureDefinition, ValueSet and CodeSystem of the loaded packages, whether uploaded, fetched from the registry or packaged from loose files: | In the package | What Atlas uses it for | |---|---| | Profiles and extension definitions | Path suggestions, checks, the Profile tab, **+ Ext**, and validation ({doc}`/map/paths`, {doc}`/check/coverage`, {doc}`add-extension`). | | ValueSets and CodeSystems | Validation with **Terminology checks (codes & bindings)** on: codes are checked against the ValueSets they are bound to, expanded from the packages' CodeSystems ({doc}`/check/validate`). Path suggestions show a required or extensible binding. The code systems and their codes are suggested where you write terminology: ConceptMap groups and inline rows ({ref}`conceptmap-suggestions`). | | ConceptMaps | Nothing. Mappings translate codes with the ConceptMaps on **Terminology** ({doc}`conceptmaps`): upload them as `.json` (here or there), not inside a `.tgz`. | The codes Atlas suggests for a system are its CodeSystem's, plus the codes the packages' ValueSets list for it. For a code system no package defines, such as SNOMED CT or LOINC, that is only the codes the ValueSets list: a ValueSet defined by a filter (`is-a` …) can't be expanded in Atlas, and validation reports such a code system as unknown. Many shared ValueSets and CodeSystems are in `hl7.terminology.r4`; when a package depends on it, **Missing dependencies** offers to fetch it. ## Check it worked In the Workspace, open a model that produces one of the package's profiles: - the **Profile** tab shows the profile instead of a **base** entry, counting its required and must-support elements ({doc}`/check/coverage`); - the {ref}`profile-not-loaded ` info is gone from the Problems dock; - the validation chip no longer says **N profile(s) not loaded** ({doc}`/check/validate`). Without any package, the page says: ```{figure} ../images/codes-and-profiles/packages-empty.png :class: screenshot :alt: The FHIR packages page without packages "No packages yet. Paths are checked and FHIR is validated against base FHIR only." ``` ## Tips :::{tip} Fetch by `id#version` when you can: Atlas then lists the package's dependencies, and **Fetch** adds each missing one in a click. ::: :::{tip} For profiles of your own, drop their StructureDefinition `.json` files, with the ValueSets and CodeSystems they bind, in one upload. Atlas packages them together; uploading them again under the same package name and version replaces the package. ::: :::{tip} A template exported from Atlas can carry its linked packages, and uploading that ZIP on the Engine state page brings them back ({doc}`/ship/export`). ::: ## Watch out :::{warning} Removing a package takes its profiles away from every model that uses them: they fall back to base FHIR for suggestions, checks, coverage and validation. ::: :::{warning} Right after a package is added or removed, Atlas reloads the profiles. Until it is done, the page says "The packages are still being loaded; their profiles appear shortly." ```{figure} ../images/codes-and-profiles/packages-warming.png :class: screenshot :alt: The notice that the packages are still being loaded The loading notice. ``` ::: ## If something goes wrong An upload's messages start with the file they are about. | Message | What to do | |---|---| | \: packages are limited to 15 MB | The `.tgz` is bigger than 15 MB. Fetch it by `id#version` instead. | | \: files are limited to 60 MB | The file is bigger than 60 MB. Split the ZIP. | | \: not a .tgz, .json or .zip | Leave the file out. | | '\' is no package name: use letters, digits, '.', '-' and '_', for example local.my-profiles | Change the package name. | | \: Not a FHIR conformance resource, ConceptMap or Bundle of them | The `.json` holds no StructureDefinition, ValueSet, CodeSystem or ConceptMap (an example instance, say). In a ZIP or among other files it is only skipped. | | Expected FHIR npm packages (.tgz), conformance resources (StructureDefinition, ValueSet, CodeSystem … as .json or a Bundle), ConceptMaps, or a .zip of them | Nothing in the upload can be stored. | | \: Archive has too many entries (limit 1000), \: Archive uncompressed size exceeds limit, \: Entry exceeds size limit (52428800 bytes) | The ZIP is too big. Split it. | | The registry's package is larger than 15 MB | The package on the registry is bigger than 15 MB. | | \: The package expands to more than 200 MB / '' in the package expands to more than 50 MB / The package holds more than 50000 files | The package unpacks to too much. | | \: Not a FHIR npm package (.tgz with package/package.json): … | The file isn't an npm package. Use the IG's `package.tgz`. | | Engine: … | The engine refused a file. The files before it may be stored: check the list, then upload the rest. | | Core FHIR definitions are built in; don't upload … | Leave out `hl7.fhir.r4.core` and the other core packages. | | package.json has no name or version | The package is incomplete; get it again from its source. | | # not found in () | Check the id and version on the registry. | | Could not fetch from : … | The registry couldn't be reached; try again, or upload the `.tgz`. | | Fetching packages from a registry is disabled | Upload the `.tgz` instead. | See also {ref}`msg-missing-deps` and {ref}`msg-packages-warming`. ## Related - {doc}`/check/coverage`, {doc}`/check/validate` - {doc}`add-extension` - {doc}`/map/paths`