id: TEDY.17.1 template: tool-feature module: tedy state: Built traces-from: [] source-refs:
- reference-editor/app/src/app/integration/import/file-import/code-system/csv/code-system-file-import.component.ts
- reference-editor/app/src/app/integration/import/file-import/code-system/code-system-file-import-form.component.ts
- reference-editor/app/src/app/resources/_lib/code-system/services/code-system-file-import.service.ts
- reference-editor/app/src/app/integration/import/file-import/file-analysis.service.ts
- terminology-server/fileimporter/codesystem/CodeSystemFileImportController.java
- terminology-server/fileimporter/codesystem/utils/CodeSystemFileImportRequest.java author: TEDY bootstrap created: 2026-08-09 updated: 2026-08-09
TEDY.17.1 – Code System File Import
Feature grouping
Child of TEDY.17 – File & Source Import (Common Spec), which owns the analyze→map→process→poll lifecycle, transport, job model, IA, and reuse machinery. Siblings: TEDY.17.2 VS, TEDY.17.3 MS, TEDY.17.4 External.
Description
Import concepts into a Code System from a csv / tsv / xlsx / json file (or a
source URL). This is the richest importer: after analyze, the user builds a
column → property mapping and sets version + run options, then processes the
import as a background job. The result (a validation diff on dry-run, or the applied
changes) is shown as a JobLog.
Screen flow
Single scrollable form (progressive disclosure); a card with a breadcrumb header
(Import → Code System) and a footer action row.
- Destination Code System — existing (autocomplete search) or new. New reveals: resource id, title (multi-language, required), URI (required), description (multi-language), and a supplement toggle → base Code System + base version.
- Version — existing draft version select, or new: semantic version number, status (publication-status select), release date; for a supplement, the base/supplement version.
- Source — type radio link | file; format select
csv|tsv|xlsx|json; the URL input or the file input accordingly. Analyze button. - Column mapping (after analyze) — one row per detected column (see model). Toolbar: predefined template select, saved mappings save/load, Load config (portable file). A validation summary blocks Process on errors.
- Options —
generateValueSet(Yes/No),dryRun(validate vs import),cleanVersion(delete concepts / hold),replaceConcept(replace / merge). - Process — runs the job; JobLog panel shows errors/warnings/successes; a log download is offered on issues, success toast (with a link to the CS) on a committed run.
Column-mapping model
Each analyzed column becomes an editable row (FileImportPropertyRow):
| Field | Meaning |
|---|---|
columnName | source column (from analyze; read-only) |
propertyName | target: concept-code, hierarchical-concept, is-a, or a defined/CS property; new-property allowed (_newProp) |
propertyType | from the concept-property-type value set, or designation |
propertyTypeFormat | required for date/dateTime (format string) |
propertyCodeSystem | for code/Coding values — the target system |
propertyDelimiter | multi-value split delimiter |
language | for designations (display:en etc.) |
preferred | single preferred designation (mutually exclusive across rows) |
import | include this column (defaults from hasValues) |
Property-name choices are concept-code, hierarchical-concept, is-a merged
with the defined properties and the CS’s own properties, weight-ordered
(concept-code → hierarchical-concept → display → definition → is-a first).
Selecting a name defaults its type from the property definition.
Client validation (before process): at most one identifier property;
date/dateTime rows require a format; warn on duplicate concept-code /
hierarchical-concept.
Request DTO (/file-importer/code-system/process)
multipart request JSON (modeled on the server DTO; TEDY sends the fields it sets):
- source:
type,link codeSystem { id, uri?, title?, description?, supplement? }(uri/title/… only for a new CS)version { number, status, releaseDate, supplementVersion? }properties: [{ columnName, propertyName, propertyType, propertyTypeFormat, propertyCodeSystem, propertyDelimiter, preferred, language }](only rows withimport)- options:
generateValueSet,dryRun,cleanVersion,replaceConcept
Server DTO additionally supports space, spacePackage, autoConceptOrder,
valueSetProperties, importClass, and extra CS metadata (publisher, oid,
contact, admin, endorser, externalWebSource) + version language,
algorithm, oid — TEDY types include these for forward-compat even if the v1 form
does not surface all of them.
Defaults
source.type = link (reference default; TEDY may default to file), format = csv,
dryRun = true, cleanVersion = false, replaceConcept = false,
generateValueSet = false.
Reuse machinery
Saved mappings (localStorage per CS id), predefined templates
(assets/file-import-templates), and the portable ===TEDY-IMPORT-CONFIG===
config block — all as defined in TEDY.17. Decision (this build): all three are
in v1.
Testing
Per the strategy in TEDY.17 → Testing. CS owns the
richest pure-logic surface, so it carries most of the unit tests: mapping
validation (single identifier, date/dateTime format required, duplicate
concept-code/hierarchical-concept), portable config parse/serialize +
applyMappingRows merge-by-columnName, the process request builder (only
import rows in properties[], multipart request+file shape, releaseDate
serialized), and property-name/default derivation ordering. Component smoke:
analyze mocked → mapping rows render, Process gated on validation. No test re-covers
server-side CSV/XLSX parsing.
Acceptance
- Analyze a csv/tsv/xlsx against an lmb CS → columns detected; map columns; dry-run → JobLog diff; real run → concepts imported, success toast links to the CS.
- New CS-import unit tests green (
nx test); component smoke passes. - Save a mapping, reload the page, load it back; export a config, load it into a fresh session and see CS/version/format/mapping prefilled after analyze.
tscclean; en/et/ru i18n in sync; verified againsthtx.helex.dev/lmb.