OS4X Enterprise user import via Microsoft Active Directory - Revision history

Admin: /* Import of user data via XML */

2025-09-26T06:06:00Z

Import of user data via XML

Admin: /* Parameters */

2025-09-25T12:08:25Z

Parameters

Admin: /* PowerShell requirements */

2024-10-24T07:30:38Z

PowerShell requirements

Admin: Created page with "= Active Directory user synchronization = OS4X offers a script to export user information from the connected Microsoft Active Directory and export the data into an XML file wh..."

2024-10-24T07:29:51Z

Created page with "= Active Directory user synchronization = OS4X offers a script to export user information from the connected Microsoft Active Directory and export the data into an XML file wh..."

New page

= Active Directory user synchronization =
OS4X offers a script to export user information from the connected Microsoft Active Directory and export the data into an XML file which is then supported by the user import function of OS4Xapi.

The functionality consists of two partners:
#Export of user data from AD, written to an XML file.
#Import of the given XML file via OS4Xapi.

You can skip the export of the AD data for crafting an own user data export.

= Requirements =
== PowerShell requirements ==
In order to be able to run unsigned PowerShell scripts from OS4X, you must change the execution policy in a PowerShell started in administrative mode:
Set-ExecutionPolicy -ExecutionPolicy Unrestricted

The module for Active Directory is required for execution of the script. If not installed, you can install it in an administrative PowerShell:
Get-WindowsCapability -Online | Where-Object {$_.Name -like "*ActiveDirectory.DS-LDS*"} | Add-WindowsCapability -Online

On Linux, it may be required to install the AD module. For this, you must be able to download either directly or via HTTPS proxy:
pwsh -Command 'Install-Module -Name PSWSMan'
pwsh -Command 'Install-WSMan'

== OS4X ==
*The server running the import script must have PHP installed for CLI.
*A defined "[[OS4X_Core_configuration#define_own_company|own company]]" must be set.

= Export of AD data =

== Configuration ==
The header of the PowerShell script contains variables to be changed. These are:
*<code>$GroupNames</code>: A list of group for export. All members of these groups are exported.
*<code>$OutputFilename</code>: Absolute path to the output XML file.
*<code>$Debug</code>: Write more debug output to the console.

In case of specialities in Active Directory schema, you can define with the following variables which field matches the required OS4X field. The defaults are (names are self-explaining):
*<code>$OS4X_Firstname = "GivenName"</code>
*<code>$OS4X_Lastname = "Surname"</code>
*<code>$OS4X_Telephone = "telephoneNumber"</code>
*<code>$OS4X_Email = "mail"</code>
*<code>$OS4X_Username = "SamAccountName"</code>
*<code>$OS4X_Street = "StreetAddress"</code>
*<code>$OS4X_ZIPCode = "PostalCode"</code>
*<code>$OS4X_City = "l"</code>
*<code>$OS4X_Department = "Department"</code>
*<code>$OS4X_CountryAlpha2 = "Country"</code>
*<code>$OS4X_ObjectGUID = "objectGUID"</code>

The country field referred by <code>OS4X_CountryAlpha2</code> follows the [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2] definition of countries and is supported by at least Windows Server 2022 AD schema.

== Execute command ==
On a client connected to the target AD, execute the PowerShell script as a user who is allowed to crawl the AD data:
powershell -File "\\tsclient\Active Directory\OS4X AD-Export.ps1"

= Import of user data via XML =
Use the OS4Xapi in command line mode:
php /var/www/html/os4x/os4xapi/index.php admin usersync "file=/opt/os4x/tmp/AD-user-export.xml"

== Parameters ==
*<code>file</code>: Path of the user XML file (either absolute or available from relative path).
*<code>disableUnavailable</code>: "<code>true</code>" or (default) "<code>false</code>": Deactivate all users with a UUID in the reference field of the own company. Manually created users are not affected.

== Logging ==
All logs are being added to the configured [[OS4X_Core_configuration#Absolute_path_to_logfile_of_OS4X_API_.28CLI.29|OS4Xapi CLI logfile]].

@@ Line 52: / Line 52: @@
 = Import of user data via XML =
-Use the OS4Xapi in command line mode:
+Use the OS4Xapi in command line mode. Examples:
   php /var/www/html/os4x/os4xapi/index.php admin usersync "file=/opt/os4x/tmp/AD-user-export.xml"
 == Parameters ==

@@ Line 58: / Line 58: @@
 *<code>file</code>: Path of the user XML file (either absolute or available from relative path).
 *<code>disableUnavailable</code>: "<code>true</code>" or (default) "<code>false</code>": Deactivate all users with a UUID in the reference field of the own company. Manually created users are not affected.
 == Logging ==
 All logs are being added to the configured [[OS4X_Core_configuration#Absolute_path_to_logfile_of_OS4X_API_.28CLI.29|OS4Xapi CLI logfile]].

@@ Line 19: / Line 19: @@
   pwsh -Command 'Install-Module -Name PSWSMan'
   pwsh -Command 'Install-WSMan'
 == OS4X ==