Book a demo
Documentation menu

Import members from a file

Create, update or deactivate many OpenAleph members at once with the Excel import template, its columns, accepted values and error messages.

Who can do thisAdminSuper admin

The import lets admins create, update and deactivate many members at once from an Excel (.xlsx) file, including their manager and all their people attributes (job title, hire date, department, work location...). It is the fastest way to set up OpenAleph or to apply a batch of HR changes.

Before you start

Permissions: importing is reserved for Admins and Super admins. Scoped admins see the Import members button, but uploading a file leads to the Restricted Access page.

  • Only the .xlsx format is accepted (no .csv, no .xls).
  • If your company's members are synchronised from an HRIS, the import is not available: your HRIS is the source of truth (see Integrations).
  • Configure your people attributes first (sections, fields, options, organisation units): the template is generated from them. See People attributes.

Step 1: download the template

  1. Go to Company › People › Members.
  2. Click Import members. The Import users window opens.
  3. Under "You don't have a file ?", click Download template.

The template is built for your company and always reflects your current configuration. It contains three sheets:

Sheet Content
Users The sheet to fill in: one row per member. The first row (hidden) holds the technical column names used by the import; the second row shows readable labels. Fill in from the third row.
Help One row per column, with its technical name, label, type, whether it is required, the expected format, the accepted values and an example.
Lists Every accepted value for select, organisation unit, country and language fields, with its label and its technical name.

Important: don't rename, reorder or delete the hidden first row: the import reads the technical column names from it.

Step 2: fill in the file

Member columns

Column Required Format and accepted values Example
company_uid Yes Your unique identifier for the member. Put #N/A to deactivate the member (see below). EMP-0001
firstname Yes Text Jane
lastname Yes Text Doe
email Yes A valid, unique email address jane.doe@example.com
status Yes active or inactive active
manager_company_uid Column required, value optional The company_uid of the member's manager. The manager can be an existing member or another row of the same file. EMP-0002
access_level Yes employee, manager, manager_creator or admin employee
birth_date No Date, YYYY-MM-DD, not in the future 1992-04-12
gender No male, female or prefer_not_to_say (Male, Female, M, F and their French equivalents are also understood) female

People attribute columns

After these columns, the template has one column per active people attribute of your company (Hire date, Job title, Work location, Contract type, Level, Department, Personal email...). The Help sheet gives the exact format of each one:

Field type Expected value
Text, email, URL, number The value as is
Date YYYY-MM-DD
Toggle true or false
Select The option label as shown in OpenAleph, or its technical name (OPTION_...) listed in Lists
Multi-select Several values in quotes, separated by commas, for example "French","English"
Organisation unit (department, site...) The unit name, or its technical name (NODE_...)
Job title The job title label, or its technical name (JOB_...)
Person (for example HR reference) The company_uid of that person
Country / language The country or language code listed in Lists (for example fr, en)
Phone number {"code":"+33","value":"0612345678"}
File Not supported by the import: leave empty or delete the column

Important: an empty cell in an attribute column clears the existing value for that member. If you don't want to change an attribute, delete its whole column from the file. Columns you delete are simply ignored.

How rows are processed

Your row What the import does
company_uid not found in OpenAleph Creates a new member.
company_uid matches an existing member Updates that member with the values of the row. The company_uid itself is not changed.
company_uid is #N/A Finds the member by email and deactivates them (same effect as a manual deactivation).
Empty row Ignored.
  • The manager is assigned after all rows are processed, so a manager can appear anywhere in the file.
  • If the person given as a manager has the Employee access level, the import automatically raises them to Manager.
  • If manager_company_uid is empty, the member's current manager is kept.

Step 3: upload and check the file

  1. In the Import users window, drag and drop your file or click Upload a file.
  2. OpenAleph inspects the file ("Inspecting file..."). Nothing is changed at this stage.
  3. Two outcomes:
    • Your file contains errors ("Please correct the errors below and reload the file."): each error is listed with its title, its line number ("On line 3") and a hint, for example User access level is incorrect, "please choose among this list: employee, manager, manager_creator and admin". Fix them in Excel, then click Upload another file. Line numbers are the Excel row numbers (your first member is on line 3).
    • File ready for import / "No errors detected.": the Modifications block summarises what will happen, for Users (created, modified, removed), for Metadata values (the attribute values assigned or cleared, and errors) and for the Template (errors).

Frequent errors

Error How to fix it
Missing headers One of the member columns is missing. Download a fresh template.
Unknown metadata field A column doesn't match any active attribute (renamed, deleted or typed by hand). Use a fresh template.
Duplicate header / duplicate metadata field The same column appears twice.
Missing company_uid Every row needs a company_uid (or #N/A to deactivate).
User UID (duplicate found) / User Email (duplicate found) Two rows share the same company_uid or email. Keep one.
Email conflict The email already belongs to a member with a different company_uid. Use the existing company_uid.
User email is not valid / User is missing email, firstname or lastname Fill in or correct the cell.
User access level is incorrect Use employee, manager, manager_creator or admin.
User status is invalid Use active or inactive.
The company_uid passed as manager_company_uid does not refer to any user The manager's company_uid exists neither in OpenAleph nor in the file.
User cannot be his own manager manager_company_uid equals the member's own company_uid.
Birth date is invalid or in the future / Gender must be Male, Female, or Prefer not to say Correct the value.
Option ... not found / Ambiguous option label The value doesn't match an option (or matches several): use the technical name from the Lists sheet.
Only .xlsx format is accepted Save the file as an Excel workbook (.xlsx).

Step 4: import

  1. Tick the Send invitation emails to all new users checkbox if you want the newly created members to receive their invitation right away. Leave it unticked to invite them later from the Members list. (Cancel closes the window without importing.)
  2. Click Import file and apply changes.
  3. A progress indicator shows the users, metadata values and template being imported. When it reaches 100% ("Import completed"), click See details to see the lists Created, Updated, Deleted, Metadata errors, Template errors and Import errors, or Finish to close and refresh the list.

If a single row fails during the import (for example an unexpected value), only that row is skipped and reported with its line number; the other rows are imported.

Note: if you close the window during the check or before importing, OpenAleph asks for confirmation ("If you quit, you will have to restart the import again."). Quit import cancels without changing anything.

After the import

  • Every change is recorded in each member's profile history with the source Import and your name.
  • New managers receive the "New team member assigned to you" email for each member assigned to them.
  • Members created without invitation have the status Not invited. Invite them from the Members list (see Add and invite members).

Common questions

Can I use the file from Export all members to import?

The export uses the same identifiers (company_uid, manager_company_uid), but its columns differ from the template (for example manager_email, hire_date). The safest way is to download the template and copy your data into it.

I only want to update one attribute for everyone.

Keep the member columns and only the attribute column you want to change, delete the others. Or use the bulk action Manage attributes on the Members page.

Can I give the Scoped admin or Super admin level with the import?

Super admin is refused by the import. A scoped admin needs a scope, which can only be defined in the app. Import these members with another level (for example employee), then change their access level from their profile or with Manage access levels.

Why was a member deactivated by my import?

Their row had #N/A in company_uid. Restore them from View deactivated members (see Edit, deactivate and restore members).

An attribute was emptied for everyone after my import.

The column was in the file with empty cells. Re-import with the correct values, and delete columns you don't want to change next time.

Still stuck?

Our team answers every question. Tell us what you are trying to do and we'll walk you through it. Contact support