Import users and departments from Entra or Active Directory

Use Microsoft Entra ID as the source of truth. VisionAtlas does not crawl your directory. Company admins export CSVs on an IT workstation, review the mapping, then load them with the existing Admin → Departments and Admin → Users import cards.

On-prem Active Directory is not supported directly. Confirm Entra Connect or Microsoft Entra Cloud Sync is healthy, then export from Entra so the same fields and SSO emails are used.

Export scripts that emit the import format live in the product repository under scripts/directory-export/.

Prerequisites

• A VisionAtlas company administrator
• In Entra: Global Reader or User Administrator (enough to list users and groups)
• On the IT workstation: Microsoft Graph PowerShell
• Graph consent in your tenant only (not granted to VisionAtlas): User.Read.All and Group.Read.All

VisionAtlas Microsoft sign-in and Outlook/Teams connect do not request these directory scopes. The export runs as your IT admin against your tenant.

What to skip

Do not import:

• Guest accounts (userType = Guest)
• Disabled accounts
• Service principals, shared mailboxes used as bots, or conference rooms
• Directory passwords — leave the VisionAtlas password column blank so people sign in with Entra SSO
• Entra directory roles copied 1:1 into VisionAtlas RBAC — map roles with the worksheet below

Field mapping

Department CSV columns: required code,name; optional description,parent_code,owner_email,delegate_emails.

User CSV columns: required name,email; optional title,role,department_code,department_codes,primary_department_code,manager_email,cell_phone,text_allowed,email_reminders_allowed,password.

Import order is fixed: departments first, then users. Department codes on user rows must already exist.

Department codes

Entra department is a display name, not a code. Invent a stable slug:

1. Uppercase the department name.
2. Replace spaces and punctuation with a hyphen.
3. Keep only A–Z, 0–9, -, and _.
4. If two names collide (for example “Sales” and “SALES”), add a suffix (SALES-2) and record the choice.

Examples: Sales → SALES, Customer Success → CUSTOMER-SUCCESS, R&D → R-D.

Users with a blank Entra department should have a blank department_code until you assign them.

Parent departments

Entra department is usually flat. To set parent_code:

• Manager chain: for each department, look at the most common manager department among its people. If that other department is different, use it as parent_code.
• Groups / OUs: if you already model hierarchy in security groups or AD organizational units, map those names to codes and fill parent_code by hand.
• Leave parent_code blank when the department sits at the company root.

The Graph export script applies the manager-chain heuristic and prints it in the review summary so you can correct it before import.

Role mapping worksheet

Default every imported user to `CONTRIBUTOR`. Do not copy Entra Global Administrator, Exchange Admin, or similar into VisionAtlas.

Map your security groups or job-title patterns to VisionAtlas roles, then edit the role column before import:

See Roles and permissions for what each role can do. You can change roles later under Admin → Users.

Optional: pass a role-map.csv to the export script (match_type,match_value,role where match_type is group or title).

Two-pass load

Department owner_email and delegate_emails are stored only when those users already exist. Import owners on a second pass.

1. Export with scripts/directory-export/Export-VisionAtlasDirectory.ps1 (or the AD appendix script if Entra sync is not ready).
2. Review the printed summary: row counts, missing mail, unknown departments, suggested parents and owners.
3. Edit departments.csv — confirm codes, parents, and role map. Clear owner_email and delegate_emails for the first department import (or leave them; they are skipped until users exist).
4. Admin → Departments — upload departments.csv.
5. Edit employees.csv — confirm emails match Entra UPN/mail, set roles, leave password blank.
6. Admin → Users — upload employees.csv. Users with a blank password receive the form’s default password for emergency password sign-in; they should still use Sign in with Microsoft.
7. Second pass — re-import departments.csv (or edit departments in the UI) with owner_email and semicolon-separated delegate_emails. Confirm manager lines on Admin → Users.

SSO email match

Microsoft sign-in attaches to an existing VisionAtlas user when the email matches Entra mail or userPrincipalName. If they differ, the user is created in Entra but cannot open this workspace with SSO.

Create each user first (CSV or Admin → Users), then they click Sign in with Microsoft on Sign in. See Login, MFA, and account access.

Run the Entra export

On an IT workstation (not on the VisionAtlas host):

Install-Module Microsoft.Graph -Scope CurrentUser
cd path\to\visionatlas\scripts\directory-export
.\Export-VisionAtlasDirectory.ps1

The script writes departments.csv and employees.csv next to itself, never writes a password column, and prints a review summary.

If Entra Connect is not yet healthy, use Export-VisionAtlasDirectory-AD.ps1 for the same headers, then re-export from Entra before go-live so SSO emails stay aligned.

Related

• Company admin setup — organization checklist
• Roles and permissions
• Login, MFA, and account access