# Bring your material in (bring-material-in-what)= ## What you'll do You load operational templates (OPTs), FHIR Connect mappings, ConceptMaps and FHIR packages into the engine, check what the upload will change before it changes anything, and read what happened to each file. You also replace a template's OPT and delete a template you no longer need. ```{figure} ../images/map/upload-preview-merge.png :class: screenshot :alt: The upload preview, one model will be updated, the OPT and the context are unchanged The preview of an upload: one model will be updated, two files change nothing. ``` ## Before you start - You need the files to upload: a ZIP archive, or single `.opt`, `.yaml`, `.yml`, `.json` or `.tgz` files. A ZIP exported from Atlas ({doc}`/ship/export`) works as it is. - Uploading changes the engine for everyone who works on it. If your engine keeps a history of the mappings, you can go back to an earlier version afterwards ({doc}`/ship/history`). ## Steps ### Upload files 1. Open **Engine state** in the sidebar and click **Upload** [1]{.callout} at the top right. The **Upload mappings** panel opens. ```{figure} ../images/map/upload-panel.png :class: screenshot :alt: The Engine state page with the Upload mappings panel open The Upload button [1]{.callout}, what goes where [2]{.callout}, and the drop zone [3]{.callout}. ``` 2. Drag your files onto the drop zone [3]{.callout}, or click **browse** and pick them. You can pick several files at once. Atlas reads each one by its content, not by its name: | File | Where it goes | |---|---| | `.opt` | The engine's store of operational templates. | | `.yaml` / `.yml` | A FHIR Connect file: Atlas detects whether it is a context mapper (a top-level `context:` or `type: context`) or a model mapper (a top-level `mappings:` or `type: model` / `extension`). A file that is neither is skipped with a reason. | | `.json` | A FHIR ConceptMap (`"resourceType": "ConceptMap"`) goes to the terminology store. StructureDefinitions, ValueSets and CodeSystems (also in a Bundle) are stored together as one package in the FHIR packages, named after the ZIP they came in (`local.`), else after the first profile ({doc}`/codes-and-profiles/fhir-packages`); a Bundle's ConceptMaps go to the terminology store. Any other JSON is skipped. | | `.tgz` | A FHIR IG package goes to the FHIR packages ({doc}`/codes-and-profiles/fhir-packages`). | | `.zip` | Every supported file inside is handled as above. | The **Upload** button on the Engine state page and the same panel under the template gallery of the Workspace do the same thing. ### Check the preview 3. Atlas shows **Checking what the upload changes…**, then a **Preview**. Nothing has been written yet. ```{figure} ../images/map/upload-preview-merge.png :class: screenshot :alt: The preview of a merge upload The summary [1]{.callout}, the mode [2]{.callout}, one row per item [3]{.callout}, and Apply [4]{.callout}. ``` - The summary [1]{.callout} counts what happens: `N new`, `N updated`, `N deleted`, `N unchanged` and `N packages`. **Nothing to import** means the upload changes nothing. - Each row [3]{.callout} shows the action (**create**, **update**, **delete**, **unchanged**, or **package** for a FHIR package), the kind (OPT, MODEL, CONTEXT, CONCEPTMAP, FHIR PACKAGE), the name, and what will happen (**Will be created**, **Will be updated**, **Will be deleted**, **Unchanged**; a package says **Stored when the upload is applied**, and a `.json` file Atlas packages says **Packaged as \. Stored when the upload is applied**). - Errors the engine finds in the plan are listed in red, warnings in amber. While there is an error, **Apply** stays disabled. 4. Choose the mode [2]{.callout}: **Merge** : Creates what is new and updates what changed. Everything else in the engine stays as it is. This is the default. **Mirror** : Also deletes every template, model, context and ConceptMap the upload doesn't contain, so the engine ends up holding exactly what you uploaded. Atlas recomputes the preview when you switch, and the button becomes **Apply (mirror)**. ```{figure} ../images/map/upload-preview-mirror.png :class: screenshot :alt: The preview of the same upload as a mirror, 26 items will be deleted The same three Blood Pressure files as a mirror: every other template, model, context and ConceptMap would be deleted. The engine also warns that the context names a model the upload doesn't contain. ``` 5. Click **Apply** [4]{.callout}. The upload is **Applied all at once: if anything can't be imported, nothing is, unless you import despite the errors.** Click **Cancel** to drop the upload without changing anything. If the engine found errors in the plan (a model that extends one that is neither uploaded nor in the engine, say), they are listed in red and **Apply** stays disabled until you tick **Import despite these errors**. The engine then imports what it can store, broken references included, and leaves out the files it can't store, marked *Won't be imported* in the preview. Leave the box unticked to fix the files and upload them again instead. ### Read the result 6. After the upload, the panel lists every file with its result, under a summary such as `1 uploaded · 2 skipped · 0 failed`. A green check is a file that was stored, an amber circle a file that was skipped (unchanged, or not something Atlas uploads), a red cross a file that failed, with the reason under it. **Clear** removes the list. ```{figure} ../images/map/upload-result.png :class: screenshot :alt: The per-file results of the upload One model updated, the OPT and the context unchanged. ``` The Engine state page reloads, so the new or changed templates and models show at once. :::{note} Some engines can't import an upload as a whole. With them Atlas skips the preview: it uploads the files one by one as soon as you drop them, and lists the per-file result straight away. There is no **Merge** / **Mirror** choice then, and a file that fails doesn't stop the others. ::: ### Replace a template's OPT Use this when a new version of the operational template arrives and the mappings should stay. 1. On **Engine state**, click the template in **Operational templates** to select it. 2. Click the **⋯** button (**More actions**) [1]{.callout} at the end of its action row, then **Replace OPT…** [2]{.callout}. ```{figure} ../images/map/template-menu.png :class: screenshot :alt: The More actions menu of a selected template **More actions** [1]{.callout}, **Replace OPT…** [2]{.callout} and **Delete template…** [3]{.callout}. ``` 3. In **Update operational template**, drop the new `.opt` file or click **browse**. Only an `.opt` is taken. The file name appears under the drop zone; the **×** next to it removes it again. 4. Click **Update template**. The context mapper and model mappers tied to the template are left untouched. ```{figure} ../images/map/replace-opt.png :class: screenshot :alt: The Update operational template dialog with a file chosen The new OPT is chosen and ready to upload. ``` ### Delete a template 1. Select the template, open **⋯** (**More actions**) and click **Delete template…** [3]{.callout}. 2. Decide what else goes with it. With the box unticked (the default), the engine deletes only the OPT and its context mapper; the model mappers are left untouched. Tick **Also delete all archetypes (model mappers) in the context mapper tied to this template.** [1]{.callout} to delete those models too. ```{figure} ../images/map/delete-template.png :class: screenshot :alt: The Delete operational template dialog with the box ticked With the box ticked, the models tied to the context mapper go as well. ``` 3. Click **Delete**. As the dialog says: **This action cannot be undone.** ## Check it worked - The upload result says `N uploaded` with no failures, and the template or model shows in **Operational templates** or **Model mappers** on the Engine state page. - Open the template in the Workspace ({doc}`start-mapping`) to see its models and what isn't mapped yet. ## Tips :::{tip} A ZIP exported from Atlas ({doc}`/ship/export`) uploads as it is, including the `.tgz` FHIR packages and ConceptMaps it carries. Use it to move a template with everything it needs from one engine to another. ::: :::{tip} Not sure what a file will do? Drop it and read the preview, then **Cancel**. Nothing is written until you click **Apply**. ::: :::{tip} Upload a model that is still being worked on with **Merge**: the rest of the engine stays as it is. ::: ## Watch out :::{warning} **Mirror deletes everything the upload doesn't contain**: every other template, model, context and ConceptMap in the engine. Use it only with a complete set, for example a full export, and read the **delete** rows of the preview before you apply. ::: :::{warning} If the panel says **The engine changed since the preview. This is the new plan — check it and apply again.**, someone (or something) changed the engine between your preview and your click. Atlas shows the new plan instead of applying the old one. Read it again before you click **Apply**. ::: :::{warning} Deleting a template with its model mappers also deletes models other templates may use. Without the box ticked, those models stay in the engine. ::: ## If something goes wrong | What you see | What it means and what to do | |---|---| | `No supported files selected (.zip, .opt, .yaml, .yml, .json, .tgz).` | None of the dropped files has a supported extension. Rename or pick the right files. | | `Upload failed.` or an engine message in red under the drop zone | The upload request itself failed (for example the engine can't be reached). Nothing was applied. Try again; see {doc}`/reference/messages`. | | A red list in the preview, **Apply** disabled | The engine found errors in the plan, such as a model that extends one that is neither uploaded nor in the engine. Fix the files and upload again, or tick **Import despite these errors**. | | `The engine changed since the preview. This is the new plan — check it and apply again.` | See *Watch out* above. | | A file row `Unsupported file type (expected .opt, .yaml, .yml, .json, .tgz or .zip)` | The file isn't one Atlas uploads. | | `Could not classify YAML as a context or model mapper …` | The YAML has neither a top-level `context:` nor `mappings:` (or a `type`). Check it is a FHIR Connect file. | | `Invalid YAML: …`, `Invalid JSON: …`, `Invalid OPT XML: …` | The file doesn't parse. The message says where. | | `JSON is not a FHIR ConceptMap (resourceType must be "ConceptMap")` | The `.json` is neither a ConceptMap nor a StructureDefinition, ValueSet or CodeSystem, for example an example instance. Leave it out. | | `Engine rejected OPT: …`, `Engine rejected file: …`, `Engine rejected ConceptMap: …`, `Engine rejected FHIR package: …` | The engine refused the file; the rest of the message is the engine's reason. | | `Archive has too many entries (limit 1000)`, `Entry exceeds size limit (52428800 bytes)`, `Archive uncompressed size exceeds limit` | The ZIP is too big. Split it into smaller uploads. | | `Only .opt files are supported.` (Replace OPT) | Pick an `.opt` file. | After an upload, the Workspace checks the new mappings. Problems such as [a context that names a missing model](problem-context-model-missing), [a start that names no model](problem-start-model-missing) or [a model for an archetype the template doesn't contain](problem-archetype-not-in-template) show in the Problems dock ({doc}`/check/fix-problems`). ## Related - {doc}`start-mapping`: open the uploaded template and start mapping it. - {doc}`/ship/export`: export a template with everything it needs. - {doc}`/codes-and-profiles/fhir-packages` and {doc}`/codes-and-profiles/conceptmaps`. - {doc}`/reference/screens/index`: the Engine state screen, control by control. - Engine: {external+openfhir:doc}`stateconfiguration`.