Organization Structure Import and Export

Page layout
File format
Import Org. Units
Import Users
Import Roles
- How to upload the structure from a file

The Structure Import/Export page uploads org units, users and roles in bulk from an Excel or CSV file, and it can also export the same data. It is useful when you roll out TAS or during a large reorganization, when entering everything by hand would take a long time.

Super administrator only
Only users with the $SuperAdministrator role can see the Structure Import/Export tile in Administration (in the integrations category). A regular administrator does not have the tile and cannot open the page.

Page layout

The page has three tabs, which you work through in order:

Tab	What it imports
Import Org. Units	Org units and their hierarchy.
Import Users	Users and the units they belong to.
Import Roles	Roles and their assignment to users.

Element	Purpose
Import	In the page header. Runs the import on the current tab. It becomes active only after a file is uploaded.
Close	In the page header. Takes you back to Administration. If an import is in progress, TAS asks "Do you really want to cancel the import?".
Export (Excel), Export (csv)	On every tab. Downloads the current units, users or roles. You can change the file name before downloading.
File area	"Drag and drop a file here, or click to select a file." Accepts only .xlsx and .csv files.
Column separator (csv)	The character that separates columns in the CSV file. The default is a comma.
Upload new file	Shown after a file is uploaded. Replaces the file with a different one.

File format

CSV in UTF-8 encoding, with a header in the first row.
Excel .xlsx. TAS reads only the first sheet, and the header is in the first row.
Column names can be anything, because you map the columns to TAS fields in the form. If they have the same names as in the export, they are mapped automatically.

The easiest way to start is with an export: download the current data, edit it in Excel and upload it again.

Export	Columns
Org. units	orgstr_id, orgstr_name, organization_type, external_id, parent, parent_orgstr_id, parent_external_id
Users	user_id, user_name, user_first_name, user_last_name, user_display_name, user_email, user_status, external_id, orgstr_name, orgstr_id, orgstr_external_id
Roles	role_id, role_name, role_category, role_note, user_id, user_name, user_external_id

The unit export includes all active units.

Import Org. Units

Field	Purpose
Match units by	The file column and the TAS field used to identify an existing unit: name, ID or external ID. The default is name.
Unit hierarchy column	The column with the parent unit (default `parent`). The value is looked up by the same field used for matching. Instead of a column, you can choose Always 'Root' or Always 'Unassigned'.
Fill in attributes	The columns used to fill in the unit's Name, Type and External ID.
Validate and show preview	Checks the file and shows the results grouped by row type.

The preview sorts the rows into groups that you can expand:

Group	What the import does with it
Rows with new entities to import	Creates new units.
Rows with existing entities (can be overwritten)	Updates them if you choose to overwrite.
Rows with entities that exist more than once	Skips them, because it cannot tell which unit the row refers to.
Rows with duplicate matching values	Skips them.
Invalid rows	Rows that are missing a required value or have an invalid hierarchy, for example a circular one. Skips them.

The Import button opens a dialog with a summary and a choice between Import only new entities and Import new entities and overwrite existing ones. If you changed the settings after the last validation, TAS validates the data again first and asks you to check the preview.

The import creates units from parents down to their children. For existing units, it overwrites the mapped fields and the parent unit, but it does not move the root unit. If it cannot find the parent unit, it places the unit under Unassigned. This tab does not set unit managers or members. The import does not delete or deactivate units that are missing from the file.

After the import, the page takes you to the Import Users tab.

Import Users

Field	Purpose
Match users by	Username, ID or external ID.
Assign to organization by	The column with the unit and the field used to look up the unit, or Always 'Root' or Always 'Unassigned'. You set New users (From file, Root, Unassigned) and Existing users (From file, Keep current, Root, Unassigned) separately.
Fill in attributes	Columns for username, first name, last name, display name, email, User status and external ID.

The preview and the import dialog work the same way as for units. New users get the default settings, the $AllUsers role and the unit set in the import settings. The import does not set passwords. Users who sign in to TAS with a password need to have one set in the user detail.

Import Roles

Field	Purpose
Match roles by	By role name.
Match users by	Do not assign (only creates the roles), or the field used to find the user the role is assigned to.
Role assignment method	Add to the roles the user already has, or Replace the currently assigned roles with them.
Fill in attributes	Columns for the role name, category and description.

The preview is split into Role creation and Role assignment to users. The import dialog lets you import only new roles or also overwrite existing ones.

How to upload the structure from a file

In Administration, open Structure Import/Export.
On the Import Org. Units tab, click Export (Excel) and use the downloaded file as a template.
Add the units and upload the file.
Set the matching, the hierarchy column and the attributes, then click Validate and show preview.
Check the groups in the preview, especially the invalid and duplicate rows.
Click Import, choose whether to overwrite existing units, and confirm the import.
Repeat the same steps on the Import Users and Import Roles tabs.

Do a test run first
An import cannot be undone. Before you overwrite existing records, try the file on a test installation, or import only new entities first.

Related: Organization Structure, Users, Roles, competences and competence rules.

Organizational Structure

(opens in a new tab)