Import an organization from a file
Bring units, roles, headcount and reporting lines into the Organization page from a people file, a roles file or a wi-org-import document, with a preview before anything changes.
You can fill in the Organization page from a file instead of one edit at a time. There are two spreadsheet formats (CSV), one for people and one for roles, and a JSON document for tools that produce the same structure. You see a preview of what would change before anything is saved, and you confirm to apply it.
Open the import#
On the Organization page, choose Import a spreadsheet at the top of the page. When the company has no units, the empty Units and roles view also offers Import next to Add a unit and Start from Teams. The dialog asks three things:
- What are you importing? Choose People, Roles or A full file (JSON).
- File: choose the CSV (or, for a full file, the JSON document).
- Replace existing managers: off by default, so people who already have a manager keep them. Tick it to let the file's manager replace theirs.
- Also invite people who aren't in the company (for People and A full file (JSON)): off by default. Tick it to invite the people in the file who have no account. Each one gets an email with a link to set up their account.
Then choose Preview. Import stays off until you have previewed the file you have now, with the choices you have now, and the preview shows no errors. Change the file, what you are importing, either box or a column choice, and it turns off again until you preview again; a line beside the buttons says why ("Preview your file to enable Import." or "Fix the errors above, then preview again."). Pressing Enter in the dialog previews; it never imports. Warnings alone do not stop you.
Who can import#
People with the admin, people_manager or executive ability. Units, roles and role groups
can be imported across the whole company. Reporting lines follow the same rule as the page: an
administrator can set anyone's manager, while an executive or people manager can change only the
people below them (and place people who are not in the chart), and only under themselves or
someone below them. See Managing people on the Organization page.
Download a template#
Under the choice of what you are importing, Start from a template offers the template for the choice you made: People template (CSV), Roles template (CSV) or Full file template (JSON). It changes when you choose another option. Each template has the right column names (or fields) and a couple of fictional example rows. Fill it in, save it (a CSV as UTF-8, with or without a byte order mark), and upload it. A file can be up to 2 MB and 5,000 rows.
You do not have to use the template's exact column names. Names ignore capital letters, spaces, hyphens and punctuation, and many common names are recognized, so a spreadsheet exported from a people system usually works as it is. For example:
| We read it as | Names we recognize (examples) |
|---|---|
| Work email | email, work email, e-mail, email address, business email, UPN |
| Person's name | name, full name, employee name, worker, display name |
| Job title | title, job title, business title, position |
| Manager's email | manager email, manager's email, supervisor email, reports to email |
| Role title | role, role title (in a roles file also title, job title, position) |
| Level | level, grade, job level, seniority |
| How many people | headcount, head count, count, hc, staff total, number of people, employees |
| Hours a week | hours, hours per week, weekly hours, scheduled hours |
| Job family | family, job family, function, job function |
| Rate band name | band, band name, rate band |
In a people file, job title is the person's title; the role they hold is read only from role
or role title. In a roles file, job title is the role.
Giving units#
Give units in one of three ways. A file that mixes them is an error, shown with a plain sentence, and nothing is applied.
- A path in one column, called
unit(orunit path,org unit,supervisory organization):Engineering > Pod A. Besides>, a/or|between the names also separates levels (so a unit's own name cannot contain one). - One column for each level, outermost first:
unit_1,unit_2,unit_3... or named columns in this order:division,department(ordept),team,sub team,section,group. A blank at the end of a row is fine (Engineering,,is just Engineering); a blank between two filled levels is an error. A file with only adepartmentcolumn has one level. - A unit and its parent: a
unitcolumn and aparent unitcolumn (alsoparent department,parent organization). Each row names a unit and the unit it sits in; the chain is worked out across the file, and a unit name stands for one unit. A parent that no row defines is treated as a top-level unit, and the preview says so. A loop, or a chain deeper than 12 levels, is an error.
In a people file the unit columns are read only when the file also has a role title column, because a person is placed by unit and role together; otherwise they are left out and the preview says so.
The people file#
Columns: email, name, title, manager_email, and optionally unit, role_title and
level (the names above are recognized too).
- Each row is matched to an existing account by work email. Employee IDs and manager IDs are not used to match anyone. If a file has IDs but no email column, the preview says "Add a work email column to match people to accounts", and a file with manager IDs but no manager email column leaves reporting lines alone and says so. Accounts are created only when you choose to invite people without an account (below).
manager_emailsets who the person reports to. The same rules as the page apply: nobody reports to themselves, loops are refused, and a reporting line can be at most 12 levels deep. A person who already has a manager keeps it unless you tick Replace existing managers. If you are not an administrator, a row that would change someone outside your part of the chart, change your own manager, or place someone under a manager outside your part of the chart is an error in the preview. The same rule covers placing a person in a role group through theunit,role_titleandlevelcolumns: rows outside your reach are reported by row number and nothing is applied.unit(a path such asEngineering > Pod A),role_titleandlevelplace the person in the matching role group. The unit and role must already exist; a people file never creates them. Someone who is already placed in another role group stays where they are.nameandtitleare used only to invite people without an account: an existing account keeps the name and title it already has.- Abilities and Teams are never changed.
People without an account. By default, if an email has no account, nothing is stored for that row. The preview shows how many rows were skipped and which row numbers they are, never the emails or names.
Inviting people without an account. Tick Also invite people who aren't in the company, and each such row becomes an invitation instead:
- the row needs a
name; itstitlebecomes the person's title; - the person is placed under
manager_emailwhen that address has an account. If you are not an administrator, that manager must be you or someone below you, and a row without one is an error. An administrator's invitation without a known manager is placed nowhere; - the person starts with no abilities and no Teams, and is placed in the row's role group when
unitandrole_titlematch one; - an address that already belongs to an account elsewhere in the deployment cannot be invited, and the row is an error.
The preview says how many people will be invited (for example "3 people will be invited") and, when some rows place people you can't place, how many rows that is, never their emails or names. When you apply, everyone is invited in the same step, and each person then receives the invitation email with their setup link. The result lists how many people were invited and how many invitations were emailed. An invitation that could not be emailed shows as Invited in Settings > Team, where an administrator can send it again.
The roles file#
Columns: units (in one of the three ways above), role_title, headcount, and optionally
level, family, hours_per_week, band, automatable_pct, augmentable_pct and impact
(low, medium or high).
- Units that do not exist are created, and a unit is matched by its full path, ignoring capital letters.
- A role is matched by its title and level, ignoring capital letters and extra spaces. "Developer" at level "II" and "Developer" with no level are different roles.
- Each row sets the headcount of that role in that unit, creating or updating the role group.
bandmust be the name of a rate band that already exists. An unknown name gives a warning and the role's band is left as it is. An import never creates a band.- A role with no estimate is counted in the preview as having no estimate; it shows as not profiled.
Match your columns#
The preview shows how your columns were read. When a needed column could not be found, or more than one column could fill a field, a Match your columns section opens under the file. It has one choice for each field, in plain words (Work email, Person's name, Job title, Manager's email, Role title, Level, How many people, Hours a week, Rate band name), already set to the columns we found, with (none) to leave a field out, and Unit levels, outermost first to give units as levels (Add a level, Remove level). Pay columns are never offered. Make your choices, then choose Preview again; Import waits until you have.
When every column matched by its name, the same choices sit in a closed How we read your columns section, so you can check them and change one if it is wrong. Your choices apply to that preview and its import only; nothing is saved, and the file is read the same way when you import.
When the file is the other kind#
If the columns fit a different kind better than the one you chose (a roles file under People, or the other way round), the preview starts with a notice such as This looks like a roles file. Switch to Roles? and a button, Switch to Roles and preview again. Nothing switches by itself, and the column matching waits, closed, under the notice. A JSON file chosen as a CSV kind, or a CSV chosen as A full file (JSON), gets the same kind of notice.
Preview, then confirm#
The preview, headed What this file would change, lists how many units, roles and role groups would be created or updated, how many people would be linked, get a manager or be invited, which columns were ignored, and any warnings. Errors come first, with the row number, for example a reporting loop or a headcount that is not a number; the dialog moves to them when a preview has errors. A file with errors, or one with no rows read ("No rows were read."), is never shown as "Nothing would change"; that line appears only for a clean file whose rows all match what is already there. People in the file who are not in the company are shown as a count with their row numbers only, never their emails or names. Pay-like columns are listed after Ignored:, and other columns the import does not use after Columns not used:. A file's column names, never its values, are all the preview and the Audit log ever show of its contents.
Choose Import to apply the file. Import is unavailable while there are errors, and also when the file would change nothing. The server checks the file again when you import and refuses one with errors. Applying is all or nothing: if anything fails, nothing is saved. When it is done the dialog says what was added and updated, and the page shows the new structure. Changing the kind, the file, Replace existing managers or Also invite people who aren't in the company after a preview asks you to preview again.
Safe to repeat#
Importing the same file twice changes nothing the second time. An import only creates and updates. It never deletes a unit, role, role group, reporting line or account, so a file with fewer rows than you already have leaves the rest as it is. Each applied import adds one line to the Audit log with counts only, and each invited person adds an invitation line that names no email or name.
Pay columns are ignored#
Columns whose names look like pay, such as salary, pay band, salary band, hourly_rate,
compensation or bonus, are skipped, whatever else they might be matched to; you cannot choose
one in Match your columns. A column called band, band name or rate band is the name of a
rate band, and is read as that (it must be an existing band). The preview lists the column names it skipped, and the values in those columns are
never read or stored. Roles refer to pay only through the name of a rate band.
The JSON document#
A full file (JSON) is one file that holds the whole structure. It is usually produced by an
export or an onboarding tool, and it goes through the same preview and rules as the CSVs. Choose
Full file template (JSON) in the dialog to download a small fictional example. It starts with
"format": "wi-org-import" and "version": 1, and has four parts, each a list:
- units: each has a
key, anameand, for a unit inside another, that unit's key asparent_key(the template has Engineering with Pod A inside it). - roles: each has a
key, atitleand, optionally, a level, job family, hours a week,impact_rating,support_needed, a job description and tasks. A task has itstext, its share of the week (time_share_pct) and the share a Coworker takes over (takeover_percent). A task withcreateset is new work. - role_groups: how many people hold a role in a unit (
unit_key,role_key,headcount). - people: links for people who already have accounts, by work email: their manager's email, and the unit and role they hold.
A task in the document can carry
takeover_percent (0 to 100), the share of that task a Coworker takes over; when it is given it
sets the task's group and is used in place of the older yes-or-no answers. time_share_pct is the
task's share of the week. A task with create set is new work: its time_share_pct is the share
of the week a person spends on it with a Coworker, its takeover_percent is recorded (and does not
change the hours), and it is left out of the work that happens today. A role names a rate band only
by its existing name, and the file never carries pay.