Import many people at once

The import reads people from a CSV file—for example from HR or the directory service—checks every row before anything is saved, and then creates the new people with their rules in one go.

What the import doesn't do: It doesn't change existing people, issue keys, or set up a second factor. Those steps have their own procedures (see Notes).

stateDiagram-v2
    direction LR
    [*] --> New: row valid, name unknown
    [*] --> Existing: name already in the store
    [*] --> Error: row invalid
    New --> Created: Apply, person and rules saved
    New --> Partial: person saved, a rule rejected
    New --> Failed: person rejected
    Partial --> Created: Apply again
    Failed --> Created: Apply again
    Existing --> [*]: left unchanged
    Error --> [*]: fix the file, read it again

*Figure: The state of a row. On the left, the state after reading the file; on the right, after Übernehmen (Apply). Apply processes only “New”, “Partial”, and “Failed” rows; “Existing” and “Error” rows never write anything.*

The first line names the columns. Their order doesn't matter, and case, spaces, and hyphens in column names are ignored.

Other columns, such as Department, are listed in the summary and skipped. Include only the columns that access actually needs (see Data protection).

Name;Windows-Konto;E-Mail;Regeln
Jane Doe;CORP\jdoe;jane.doe@example.org;fachdaten-lesen
"Miller, Alex";CORP\amiller;;fachdaten-lesen,fachdaten-pflege

Format. A CSV file in UTF-8 with semicolons as separators. To save one from Excel, choose File > Save As and the file type “CSV UTF-8 (Comma delimited)”. The file is read according to RFC 4180 (“Common Format and MIME Type for Comma-Separated Values (CSV) Files,” https://www.rfc-editor.org/rfc/rfc4180): a field in quotation marks may contain separators and line breaks, and "" inside it stands for a quotation mark. Unlike RFC 4180, which specifies the comma as the separator, the separator here is the semicolon. Leading and trailing spaces in a field are removed.

1. Open Personen und Schlüssel (People and keys) and choose Weitere (More) > Personen importieren … (Import people …). Select the file.

2. Every row of the file now appears to the right of the people list, grouped by Stand (State) and with its line number in the file. The line above summarizes how many rows are new, existing, or have errors, how many requests Übernehmen will send to the service, and roughly how long that will take. Nothing has been saved yet.

   

   In the screenshot: (1) summary, (2) rows by state, (3) Übernehmen (Apply), Andere Datei (Other file), Schließen (Close).

3. Fix rows with Fehler (Error) in the file and read it again with Andere Datei … (Other file …). You can also apply first and read the corrected file afterward; people who have already been created then show up as Vorhanden (Existing).
4. Select Übernehmen (n), where n is the number of rows still to process. The line above the grid shows the person currently being processed. Anhalten (Pause) stops after the current request; selecting Übernehmen later continues where it left off.
5. Schließen (Close) frees up the list again and deletes the rows that were read.

Result: The rows show Angelegt (Created), and the people appear in the list, each with their rules. Like any other change, every new person is recorded in the change log (Protokoll (Log) area).

The service has no batch request: each person is one request, and each of their rules is another. The service limits requests per caller (300 per 60 seconds by default; see HTTP: administration (reference), section “Many operations at once” (data service documentation)). The import therefore waits at least 250 ms between two requests, which means at most 240 per minute; the rest is left for the requests the page itself makes. That's where the summary's estimate comes from: 850 people with one rule each are 1,700 requests, about 7 minutes (a guideline based on the rate limit); over a slow connection it takes longer.

If the service still responds with “too many requests” (HTTP 429), the import waits 60 seconds and repeats the same request, up to three times. After that, the row is marked Fehlgeschlagen (Failed), and the import moves on to the next one.

Whatever was saved before an error stays saved. The import therefore keeps track, for each row, of whether the person has been created and which rules are still missing. Selecting Übernehmen again never creates a person twice; it picks up whatever is missing. If the connection drops during a request, the app repeats it without the service saving anything twice.

Whether a person already exists is decided by their name alone, regardless of case; names are unique in the store. This has two consequences:

• Two different people with the same name: the second one is skipped as Vorhanden. Give them a distinguishing name (for example, with their department).
• An existing person whose Windows account or email address in the file is different: the import doesn't change the person and doesn't report the difference. Check such people in their form.

People who sign in with their Windows account or a SQL login don't need a key. Issue keys afterward where they're needed; for many people, the easiest way is by invitation email. The best way to set up the second factor for imported people is also an invitation email, for many at once from the Auswahl (Selection) card (Work with many people at once). A person can set it up themselves at sign-in only within a period after their key was issued (setting totp_enrol_hours, 24 hours by default); people who sign in only with a Windows account or SQL login have no key and therefore no such period (see Set up or reset the second factor).

Rules, database identities, and sign-in rules can be given to a Windows group as a whole; see Assign Windows accounts and groups. Only those who get a key, a second factor, or a default identity need a person entry. If a sign-in rule requires the second factor for a group, the service rejects every member who doesn't have a person entry of their own; for such groups, the import is the way to create all members as people.

The service doesn't provide the members of a Windows group. Your directory service can produce that list, for example with Get-ADGroupMember on the workstation; saved as a CSV file with the columns Name and Windows-Konto, it can be imported here. Neither the service nor the app picks up later changes to the group's membership on its own.

The list contains personal data as defined in Art. 4(1) GDPR (names, accounts, email addresses). The organization that operates the installation is responsible for the processing; the app supports the principles of data minimization and storage limitation (Art. 5(1)© and (e) GDPR) as follows:

The source file itself remains your responsibility: delete it after the import unless you need it for something else.

What stays behind: Every person created is recorded with their values in the service's change log, and that log is kept indefinitely, even if the person is deleted later (see Security and privacy). So import only people who should actually get access, and only the columns you need.

• Create a person and issue a key: one person, with every step up to the handover
• Send an invitation by email: issue keys to many people
• Work with areas, lists, and commands: cards, lists, commands
• Reference: HTTP: administration (reference), section “Many operations at once” (data service documentation)