Import

en lt

KTS provides a list of adapters to import different terminologies. The solution architecture offers the ability to add your own custom adapter.

FHIR

Source

You can perform import of the FHIR artifacts using artifacts directly from the HL7 FHIR standard page.
When you use HL7 Terminology (THO) or terminology related to the HL7 FHIR resources you should open the tab with JSON presentation and select the link to the raw JSON content (as in the picture below).

code-system-json-raw.png

CodeSystem

  • Select from menu “Management” -> “Integration” -> “Code system” -> “$sync” (“1”).
    fhir-import-code-system.png
  • Provide link to JSON file (“2”) and press plus button (“3”).

For example for code system arrivalMode use https://terminology.hl7.org/3.1.0/CodeSystem-v2-0430.json.

  • Press “Send request” (“4”) to initialize import.

ValueSet, ConceptMap

The import is identical to the code system import.

ICD10

WHO Edition

Source

Import

  • Select from menu “Management” -> “Integration” -> “ICD10 WHO import”.
  • Press the “Set default data” button.
    icd10-who-default.png

We recomment to use default settings for ICD10 import.

  • Press “Send request”.

Estonian Edition

Source

Please use mirror instead of the official download site. There are was removed > tags in V01-Y99.xml file from RHK10v8.zip archive in order to prevent parser from crash.

Import

  • Select from menu “Management” -> “Integration” -> “ICD10 Est import”.
  • Press the “Set default data” button.

We recommend to use default settings for ICD10 import.

  • Press “Send request”.

We recommend to import WHO Edition of ICD10 first.

We recommend to use “icd10…” in the code of code system. In this case concepts of WHO Edition and Estonian Edition will be shared. In other case there will be two independent classification.

ATC

WHO Edition

Source

Import

  • Select from menu “Management” -> “Integration” -> “ATC WHO import”.
  • Press the “Set default data” button.

We recommend to use default settings for ATC import.

  • Press “Send request”.

Estonian Edition

Source

Import

  • Select from menu “Management” -> “Integration” -> “ATC Est import”.
  • Press the “Set default data” button.

We recomment to use default settings for ATC import.

  • Press “Send request”.

We recommend to import WHO Edition of ATC first.

We recommend to use “atc…” in the code of code system. In this case concepts of WHO Edition and Estonian Edition will be shared. In other case there will be two independent classifications.

File importer

The plain text file importers may be used for the import of terminology from comma-separated files (CSV) or tab-separated files (TSV).

  • Your data should be in UTF-8 format.
  • The first line of the file (header) should contain column names.
  • The supported date formats are YYYY-MM-DD, YY-MM-DD, DD.MM.YYYY, DD.MM.YY, DD/MM/YYYY, MM/DD/YYYY, or MM/DD/YY.

CodeSystem

Destination

You can import new (select link “new”) or update existing (search for existing) code systems.
file-import-cs-main.png
When you create a new code system you should specify also the title and URI.
file-import-cs-new.png
With a selection “Generate ValueSet too” you can manage when an application will create a new value set with a rule that includes all concepts from created code system.

Source

Before the import of the code system please read the information about the code system structure.
You can specify the source as a link to the file or upload the file to the server.
file-import-upload-link.png

When you use a link to the file you should ensure that terminology server (not your computer) have access to the link. It means link should be accessible witout VPN or IP limitation.

file-import-upload-file.png

File content

Pressing the “Analyze” button KTS will validate the file, compose the list of columns, detect their types and formats and scan for empty columns. The results will be presented in a table format:
file-import-structure-initial.png
For every column from the CSV file, you can (re)define the name of the property in the code system, the data type, format (in the case of date datatype), and language (in the case of text datatype). Checkbox “import” to indicate when to import a column or to skip it.
By default we propose 4 predefined properties: concept-code - should be used as a unique key; display - official name; definition - the long name of the concept; description - additional description (typically represents rules on how to use concept). You can define new properties by choosing “ADD NEW”. If you don’t specify the KTS property then the CSV column name will be used as property.
If you have many files with similar structures you can also use the predefined templates with mappings to KTS properties, datatypes, format, and languages. In this case, you should describe only columns that are missing in the template (on the picture below template “pub.e-tervis.ee” used).

file-import-structure-with-template.png

Processing

As a result of processing the definition of the code system (button “Process”)

  • the new code system will be created (or updated)
  • the new code system properties will be created
  • the new code system version will be created
  • the new value set will be created within the rule referring to the created code system version

For every line in the text file

  • the new concept will be created (if it wasn’t created before)
  • the new version of the concept will be added (if data in files differ from the previous version)
  • every imported column will be linked as property or designation to the concept version
  • the concept version will be mapped to the code system version.

File import through API

You can use API call for code system import. The examples of call is:

curl -X 'POST' \
  'https://termx.kodality.dev/api/file-importer/code-system/process' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=' \
  -F 'request={parameters}'

The parameters of import are

Parameter Content Is required? Description
codeSystem object Yes The reference to the code system.
codeSystem.id string Yes Resource unique identifier. Any combination of upper- or lower-case ASCII letters (‘A’…‘Z’, and ‘a’…‘z’, numerals (‘0’…‘9’), ‘-’ and ‘.’, with a length limit of 64 characters.
codeSystem.uri string Yes (for first import) Canonical identifier for this code system, represented as a URI (globally unique).
codeSystem.title.$lang string Yes (for first import) Localized human friendly name.
codeSystem.description.$lang string No Localized natural language description of the code system.
codeSystem.name string No Machine name. If not specified it calculated from uri (where every word is capitalized and hyphens removed).
codeSystem.oid string No Legacy OID identifier.
version object Yes The version of code system.
version.number string Yes The version number.
version.status code No Value from the list: draft, active, retired. Default draft.
version.releaseDate date No Release date or date expected use since. Default today().
version.oid string No Legacy OID identifier.
type code No* Value from list: csv; tsv; json; fsh. (*) Required if file provided.
link url No* (*) File or link should be provided
importClass string No The name of import class. Default CS-FILE-IMPORT.
generateValueSet boolean No Should it create value set automatically? Default false.
valueSetProperties string array No List of value set (generated from code system) properties.
dryRun boolean Yes Perform validations only without data changes? Default true.
cleanVersion boolean No Delete all concepts before import from version? true - Delete, false - Hold. Default false.
replaceConcept boolean No Behavior on the overlap of concepts? true - Replace, false - Merge. Default false.
properties object Yes The description of the file to be imported.
properties.columnName string Yes The name of column in the import file.
properties.propertyName string Yes The name of property in the code system. The name ‘concept-code’ should be specified for unique identifier, ‘hierarchical-concept’ same as ‘concept-code’ with automatical hierarchy detection. The defined properties is recommended. At least one and only one from ‘concept-code’ and ‘hierarchical-concept’ should be specified.
properties.propertyType code Yes The value designation and FHIR concept property types are supported. If designation specified it will be imported as concept designation, in other case as property.
properties.preferred string No If both ‘concept-code’ and ‘hierarchical-concept’ are specified which should be used as concept code.
properties.propertyTypeFormat string No Applicable for datetime datatype only to specify the date format.
properties.propertyDelimiter string No The separator inside one field. If specified several values of the same property may be created. Applicable for string and Coding only.
properties.language string No The language of designation from AllLanguages. Applicable for datatype designation only.
 Example of CodeSystem 12345
{
   "codeSystem":{
      "id":"test12345",
      "uri":"http://example.org/CodeSystem/test12345",
      "title":{
         "en":"Test12345"
      },
      "description":{
         "en":"Test 12345",
         "et":"Test 1 2 3 4 5"
      },
      "name":"test-12345",
      "oid":"1.2.3.4.5.6.7"
   },
   "version":{
      "number":"1.0.0",
      "status":"draft",
      "releaseDate":"2023-09-18T13:02:32.888Z"
   },   
   "link":"C:\\fakepath\\2-8.csv",
   "type":"csv",
   "importClass": "import-class",
   "generateValueSet":false,
   "dryRun":true,
   "cleanVersion":false,
   "replaceConcept":false,   
   "properties":[
      {
         "columnName":"Kood",
         "propertyType":"string",
         "propertyName":"concept-code"
      },
      {
         "columnName":"Nimetus",
         "propertyType":"designation",
         "propertyName":"display",
         "language":"et"
      },
      {
         "columnName":"Pikk_nimetus (SNOMED CT FSN)",
         "propertyType":"designation",
         "propertyName":"display",
         "language":"en"
      },
      {
         "columnName":"Kehtivuse_alguse_kpv",
         "propertyType":"dateTime",
         "propertyTypeFormat":"dd.MM.yyyy",
         "propertyName":"effectiveDate"
      },
      {
         "columnName":"Selgitus",
         "propertyType":"string",
         "propertyName":"comment"
      }
   ]
}

ValueSet

Destination

You can import new (select link “Create new”) or update existing (search for existing) value set.
file-import-vs-main.png
When you create a new value set you should specify also the name and URI.
file-import-vs-new.png

Source

You can specify the source as a link to the file or upload the file to the server.
file-import-upload-link.png

When you use a link to the file you should ensure that terminology server (not your computer) have access to the link. It means link should be accessible witout VPN or IP limitation.

file-import-upload-file.png

File content

Pressing the “Analyze” button KTS will validate the file, compose the list of columns.
From proccesed columns you can select only 2 columns to import - one is concept code and another display. Display is optional.
file-import-vs-mapping.png

Processing

As a result of processing the definition of the code system (button “Process”)

  • the new value set will be created (or updated)
  • the new value set version will be created
  • the new value set will be created within the existing rule or a rule referring to the selected code system

For every line in the text file

  • the new concept will be added to rule defintion
  • the concept code will be taken from referred column and also same for display (if referred column was selected)

File import through API

You can use API call for value set import. The examples of call is:

curl -X 'POST' \
  'https://termx.kodality.dev/api/file-importer/value-set/process' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=' \
  -F 'request={parameters}'

The parameters of import are

Parameter Content Is required? Description
valueSet object Yes The reference to the value set.
valueSet.id string Yes Resource unique identifier. Any combination of upper- or lower-case ASCII letters (‘A’…‘Z’, and ‘a’…‘z’, numerals (‘0’…‘9’), ‘-’ and ‘.’, with a length limit of 64 characters.
valueSet.uri string Yes (for first import) Canonical identifier for this value set, represented as a URI (globally unique).
valueSet.title.$lang string Yes (for first import) Localized human friendly name.
valueSet.description.$lang string No Localized natural language description of the value set.
valueSet.name string No Machine name. If not specified it calculated from uri (where every word is capitalized and hyphens removed).
valueSet.oid string No Legacy OID identifier.
version object Yes The version of value set.
version.number string Yes The version number.
version.status code No Value from the list: draft, active, retired. Default draft.
version.releaseDate date No Release date or date expected use since. Default today().
version.oid string No Legacy OID identifier.
type code No* Value from list: csv; tsv; json; fsh. (*) Required if file provided.
link url No* (*) File or link should be provided
importClass string No The name of import class. Default VS-FILE-IMPORT.
dryRun boolean Yes Perform validations only without data changes? Default true.
mapping object Yes The description of the file to be imported.
mapping.code string Yes The name of column referred to the concept code in the import file.
mapping.display string No The name of column referred to the concept display in the import file.
mapping.retirementDate string No The name of column referred to the concept retirementDate in the import file. Used for validation.
mapping.status string No The name of column referred to the concept status in the import file. Used for validation.
 Example of ValueSet 12345
{
   "valueSet":{
      "id":"test12345",
      "uri":"http://example.org/ValueSet/test12345",
      "title":{
         "en":"Test12345"
      },
      "description":{
         "en":"Test 12345",
         "et":"Test 1 2 3 4 5"
      },
      "name":"test-12345",
      "oid":"1.2.3.4.5.6.7"
   },
   "version":{
      "number":"1.0.0",
      "status":"draft",
      "releaseDate":"2023-09-18T13:02:32.888Z"
   },   
   "link":"C:\\fakepath\\2-8.csv",
   "type":"csv",
   "importClass": "import-class",
   "dryRun":true,
   "mapping":{
         "code":"Kood",
         "display":"Nimetus"
    }
}

ConceptMap

Destination

You can import a new (select link “new”) or update an existing (search for existing) concept map.
concept-map-import.png
The source and destination value sets should be created beforehand.

Source

The CSV file with the predefined structure should be used for the import.
The file should contain next columns:

Column Description Is required?
sourceCodeSystem The code system belongs to the source value set. Optional
sourceVersion A version of the source code system. Optional
sourceCode Code of the concept in the source code system (if specified) or any code system that belongs to the source value set. Mandatory
targetCodeSystem Code system belongs to the destination value set. Optional
targetVersion A version of the destination code system. Optional
targetCode Code of the concept in the destination code system (if specified) or any code system that belongs to the destination value set. Mandatory
equivalence Value from the FHIR concept-map-equivalence value set. ‘equal’ is used if empty. Optional
comment Optional
dependsOnProperty Reference to the additional property required for this mapping. Optional
dependsOnSystem Code system of the property. Optional
dependsOnValue Value of the property. Optional

Example of empty file.

LOINC

Source

Import

  • Select from menu “Management” -> “Integration” -> “LOINC” -> “LOINC import”
  • Specify version you are importing
  • From downloaded zip choose proper files for import (“Parts” and “Loinc terminology” required for minimal import)

File locations in downloaded zip file:

  • Parts - AccessoryFiles/PartFile/Part.csv
  • Loinc terminology - AccessoryFiles/PartFile/LoincPartLink_Primary.csv
  • Supplementary properties - AccessoryFiles/PartFile/LoincPartLink_Supplementary.csv
  • Panels - AccessoryFiles/PanelsAndForms/PanelsAndForms.csv
  • Answer list - AccessoryFiles/AnswerFile/AnswerList.csv
  • Answer list link - AccessoryFiles/AnswerFile/LoincAnswerListLink.csv
  • Translations - AccessoryFiles/LinguisticVariant/…
  • Order observation - AccessoryFiles/LoincUniversalLabOrdersValueSet/LoincUniversalLabOrdersValueSet.csv

loinc_import.png

SNOMED

Source

Import

WHO ICF

Source

Import

  • Use File Importer for ICF file upload
    • Specify file type as tab-separated (TSV)
    • Linearization URI is the only mandatory field in the file and should be used as an internal id
    • Please define the data type of the import file according to the picture below

icf-mappings.png

Orphanet

Rare diseases

Source

Import

  • Select from menu “Management” -> “Integration” -> “Orphanet” -> “Rare diseases”.
  • Press the “Set default data” button.
    orphanet-rare-deaseses-default.png

Please verify data! Check file name, uri, code system code and name twice.

  • Press “Send request”.

Page last modified: Jan 8 2024 at 01:45 PM.