Importing People from a Directory

Importing people from Active Directory or LDAP

Bring your staff into FreeITSM from your existing directory, so they are there to assign equipment to, raise tickets for and look up before they ever sign in.

Why this is separate from signing in. Directory sign-in creates somebody the first time they log in. That is a complete answer to "let my staff log in" and no answer at all to "let me assign a laptop to Jane" - because Jane has to exist first, and the staff who hold equipment are largely the staff who never log in at all. Warehouse, shop-floor and shift workers are exactly the population that holds kit and never touches a computer.

You can use importing on its own, with sign-in switched off entirely, if all you want is the people.

---

Before you start

You need a directory already configured under System → Authentication. If you have not done that yet, follow LDAP and Active Directory first - the connection, the read-only service account and the base DN are shared between signing in and importing.

Nothing else. Importing needs no write access to your directory, ever.

---

Turn it on

System → Authentication → your directory → Importing people, and tick Import people from this directory.

The page has five tabs. Three of them matter here:

Tab	What it is for
Importing people	Which parts of the directory to bring in, the safety settings, and the Preview and Import buttons
Field mapping	Which attribute in your directory becomes which field in FreeITSM, with a Test button
History	Every run, including previews, and what each one did person by person

---

Step 1 - choose what to import

Press Browse directory. FreeITSM draws your directory as a tree with a head count on every branch:

▾ ⊟ Contoso                        0 here · 412 in branch
    ☐  C̶o̶n̶t̶r̶a̶c̶t̶o̶r̶s̶                   18 here · 18 in branch
    ☐  Service Accounts             6 here · 6 in branch
  ▾ ☑ Staff                         3 here · 388 in branch
      ☑  Finance                   24 here · 24 in branch
      ☑  IT                        31 here · 31 in branch
    ▾ ☑ Operations                 12 here · 142 in branch
        ☑  Warehouse              130 here · 130 in branch

The counts are the point: you can see that ticking Staff brings in 388 people before running anything.

Ticking a branch takes the whole branch, including anything added to it later. So a department created next year imports on its own, without anybody remembering to come back to this screen. To leave a part out - contractors, service accounts, a site that belongs to somebody else - untick it inside the ticked branch. It is shown struck through and skipped.

If your service account cannot browse the directory, Type a starting point instead still accepts a distinguished name by hand, exactly as before. It is used only when nothing is ticked, and the page says so plainly when the tree is overriding it.

---

Step 2 - check the field mapping

Directories name things differently: Active Directory uses sAMAccountName, OpenLDAP uses uid, and nothing can guess between them. The Field mapping tab pairs each FreeITSM field with its directory attribute.

Press Test. It reads one real person and shows the value each row would actually import:

FreeITSM field	Directory attribute	Example
Full name	displayName	Nia Hughes
Sign-in name	sAMAccountName	n.hughes
Email	mail	n.hughes@contoso.com
Job title	title	2nd Line Analyst
Employee number	employeeID	NW-1011

This catches the mistake nobody notices, because a mistyped attribute name does not fail - it just leaves a column permanently empty, and that usually goes unremarked for weeks.

Where a field comes back empty the test also lists every attribute that person actually has, which is what tells "the attribute name is wrong" apart from "this person has not filled it in". Nothing is saved and nothing is changed by testing, and it tests what is on the screen rather than what was last saved - so you can check a change before committing to it.

What comes across

Name, sign-in name, email, job title, department, office, phone, mobile, employee number, and who they report to. The reporting line is read as a directory entry and matched to the person it points at, so your org chart survives the import and Assets → Users can show who somebody manages.

Office matters more than it looks: the ticket equipment picker searches an asset's location, and this is usually where that information comes from.

---

Step 3 - preview, then import

Always press Preview first. It runs exactly the same job with every write suppressed, and lists the people it would touch:

Person	What happens	Detail
Priya Newstarter	Will be added	Email: p.newstarter@contoso.com; Job title: Sales Executive; Department: Sales
Nia Hughes	Will be updated	Job title: 1st Line Analyst → 2nd Line Analyst; Phone: 020 7946 0011 → 020 7946 0099

Note the wording: a preview says "Will be added", a real import says "Added". Nothing was changed.

When it looks right, press Import now.

Every run is kept under History, previews included, and each row opens the same view - so "updated how, and who?" still has an answer weeks later.

---

Nobody is ever deleted

This is the part worth reading before you run anything against a real directory.

Situation	What FreeITSM does
Somebody disappears from the directory	Marked as having left after they have been missing for several imports running. Safety sets how many; 0 never does it automatically. They keep every ticket, asset and handover document they were ever part of
Their account is disabled in the directory	Marked as having left here too
They come back	Reactivated
The import suddenly finds far fewer people than last time	It stops and changes nothing. A mistyped starting point, or a service account quietly losing read rights, looks exactly like everybody leaving at once - this is what stops that emptying your list. The threshold is a percentage; 0 switches the check off, which is a decision worth making deliberately
A branch you ticked has been renamed or moved	The run refuses and changes nothing, naming the branch. Importing only the branches that still exist is precisely how everybody in the missing one would end up marked as left
A branch you excluded has been renamed or moved	The run goes ahead but says so loudly - the people you deliberately left out have started arriving

---

Somebody who already exists in FreeITSM

If your directory has a person who already exists here with the same email address - they registered on the self-service portal themselves, say - When somebody is already here decides what happens:

• Link them to this directory attaches the two records. After that their FreeITSM portal password stops working and they sign in through the directory instead. That is why this is a choice rather than something done automatically.
• Leave them alone and flag it for me changes nothing and records it, so you can look.

Email is how the two are matched, and the match is scoped to the directory's company on a multi-company install - two companies can legitimately share an address, and matching across them would merge two customers' people.

---

Running it regularly

Importing is manual today: you press the button. Scheduling is the one part of this feature not yet built.

In the meantime, the command line works and can be put on a scheduled task or cron job:

php scripts/directory_sync.php --provider=1            # import
php scripts/directory_sync.php --provider=1 --preview  # dry run, changes nothing
php scripts/directory_sync.php --all                   # every directory with importing enabled

---

If something is not right

What you see	Usually means
"The search found nobody"	Nothing is ticked, or the ticked branch holds no user accounts. Press Browse directory and look at the head counts
A column is empty for everybody	An attribute name is wrong. Field mapping → Test, and check the list of attributes the sample person actually carries
"An import would skip them"	Neither the sign-in name nor the unique id resolved. Fix those two first; nothing else matters until they do
The run stopped and changed nothing	The safety brake. Read the message - it says how far the count fell, and it is almost always a scope or permissions problem rather than real departures
The run refused, naming a branch	Somebody renamed or moved that part of the directory. Browse directory and tick again
People you excluded are arriving	The branch you carved out has been renamed or moved. Same fix

---

See also

• LDAP and Active Directory - directory sign-in, and the connection settings this shares
• Directory sync - the design - why importing works the way it does, and the reasoning behind each decision
• Setting up OpenLDAP & Samba AD in Docker - try all of this against a test directory without touching your real one
• LDAP - Developer Guide - how it is built