How to import new concepts in the spreadsheet importer using a hierarchical format

Save PDF

Last Updated: May 13, 2026
4 minute read

Semaphore
Documentation

Explanation

The spreadsheet importer tool allows you to import and update models without RDF using Excel spreadsheets or CSV files.

This article instructs you on how to import new data into a model when you use the hierarchical file data format.

Assumptions

You have an existing model.
You have the MANAGER, EDITOR, or CONTRIBUTOR role for the model.
You have an existing model structure (i.e., classes and relationships).
You have your data formatted as explained in the article below

The importer cannot import every modelling object into a model. The objects it can import are:

Concepts, Concept Schemes

Concept metadata values and property values (e.g. class)

Relationships between concepts

It cannot import structural objects such as new class definitions, metadata properties, and relationship types. If you want to populate custom concept metadata and property values on import, these objects must exist in your model prior to import.

Method

Each different relationship type that you want to create must be in its own column.

During import, if you do not specify a concept scheme or parent concept, the import process will create a new concept scheme to contain the data.

Duplicate preferred labels are assumed to be the same concept. If you want to import homographs (different concepts with the same preferred label), they must be differentiated via URI. (See helpful hinst article)

Some relationship types or properties can have multiple data values in a cell: alternative labels, metadata values, and classes. Other types must have one value only per cell.

The instructions below make use of the example file called Geography Import, which you can download from this link.

Data Format

The first few rows and column headings look like this:

Below are explanations for each column:

URI – (optional) This column contains the URIs for all the concepts. This example will use it to create custom URIs for the concepts.
Level 1 - Concept preferred labels in the first hierarchical position.
Level 2 - Concept preferred labels in the second hierarchical position.
Level 3 - Concept preferred labels in the third hierarchical position.
Pref Label – This column contains the combine list of preferred labels of the concepts you want to create. This is important for setting up other relationships.
Ally of – This column contains the names of the concepts that have an associative relationship with the concepts you are creating.
Exports to - This column contains the names of the concepts that have an associative relationship with the concepts you are creating.
Imports from - This column contains the names of the concepts that have an associative relationship with the concepts you are creating.

If you do not already have the above custom relationships defined in your model, you will need to create them:

Importing into the model

It is always best to perform imports in a task instead of in the main model. If something goes wrong with the import, you can delete the task and create a new one without causing any changes to the main model.

Open your task, and create a concept scheme named “Geography”.
Click to open your task menu, and click Import.
Click Import Spreadsheet, and then in the Hierarchy section, click Import.
In the Import Spreadsheet dialog box, drag and drop your spreadsheet file. (Alternatively, you can click and navigate to the file.)
Choose the sheet you want to import. (In this example, choose Hierarchy Import.) Then click Next.
For this exercise, select Import as children of an existing concept or concept scheme, then search for and select Geography.
Click Next.
Choose the default class for your concepts. In this exercise, choose Concept. Then click Next.
Select the first and last columns that correspond to the hierarchy structure, then click Next.
Map the columns to the appropriate properties, and then click Next. - URI – URI - Pref Label – <nothing>; this will be used for mapping relationships. - Ally of – associative relationship: select Ally of for the relationship. Place a checkmark beside Map relationship to a column on your spreadsheet, and choose Pref Label. - Exports to – associative relationship: select Exports to for the relationship. Place a checkmark beside Map relationship to a column on your spreadsheet, and choose Pref Label. - Imports from – associative relationship: select Imports from for the relationship Place a checkmark beside Map relationship to a column on your spreadsheet, and choose Pref Label.
On the final screen, click Submit.