Integrate the Address Book with Microsoft Active Directory Domain Services

You can sync your Microsoft Active Directory Domain Services (AD DS) with the FacilityOS Address Book by running a script on your server.

Before you start

• Review the Security and confidentiality of data section.

• Contact your Customer Success Manager (CSM) or the FacilityOS Support team to receive your API credentials. Your API credentials include your client ID and client secret.

  Note:

  If you need to sync multiple sites, you can request separate API keys to upload site-specific CSV files or include all records in a single CSV file by using the correct "Site" values when editing the data fields later in this article.

• If your Address Book already contains Hosts that were added manually, syncing with AD DS will not update their information. To ensure Host details are updated automatically, delete any manually added Hosts. To learn how, see Delete a Host.

Integrate the Address Book with AD DS

1. Copy and paste the provided sample PowerShell script into a text editor, such as Windows Notepad.
2. Save the script as a .ps1 file.
3. Update the script as shown below. If you need help editing the script with your organization's information, contact your IT department.
   • AD search location: Update $OULocation="OU=Users,DC=TOR" to your organization’s correct Organizational Unit (OU) and Domain Component (DC).
   • API credentials: Locate $client_id = 'Enter client ID here' and $client_secret = 'Enter client secret here', then enter the API credentials you received from your CSM between the quotation marks.

   • Data fields: Locate $fields = @('Email Address','Full Name','Mobile Phone','HomePhone') and update the fields based on the user account properties your AD DS environment collects.

     Important:

     To ensure the data fields are properly mapped to the FacilityOS CSV file, you need to add field mapping to the script. To learn which fields the FacilityOS CSV file expects, see the table in Prepare a CSV file.

4. Run the script on your server.

Sample PowerShell script for AD DS

The following sample script shows the general structure for exporting employee data from AD DS.

$OULocation="OU=Users,DC=TOR"

$client_id = 'Enter client ID here'
$client_secret = 'Enter client secret here'

$sourceFilePath = $PSScriptRoot + "\adextract.csv"

$fields = @('Email Address','Full Name','Mobile Phone','HomePhone')

Import-Module ActiveDirectory

$Users = Get-ADUser -Filter {Enabled -eq "True"} -SearchBase $OULocation -SearchScope Subtree -Properties $fields | select $fields

$Users | Export-Csv $sourceFilePath -NoTypeInformation -Force

$headers=@{}
$headers.Add("Content-Type", "application/x-www-form-urlencoded")

$response = Invoke-WebRequest -Uri 'https://partnerapi.goilobby.com/auth/connect/token' -Method POST -Headers $headers -Body "grant_type=client_credentials&client_id=$($client_id)&client_secret=$($client_secret)"

$token = ConvertFrom-Json $response.Content
$access_token = $token.access_token

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12;

$urlDest = "https://partnerapi.goilobby.com/addressbook/uploadcsv";

$webClient = New-Object System.Net.WebClient;

$webClient.Headers.Add("Content-Type", "application/x-www-form-urlencoded")
$webClient.Headers.Add("Authorization", "Bearer $($access_token)");

$resp = $webClient.UploadFile($urlDest, "POST", $sourceFilePath);

$enc = [System.Text.Encoding]::ASCII
$enc.GetString($resp)

Verify the sync in FacilityOS

1. In FacilityOS, from the left sidebar, click Manage, then select Address Book.
   
2. Successfully synced employees have a lock icon.

3. Select an employee to view details such as name, email address, phone number, and site assignment.

   Important:

   To edit an employee's details, make the changes in AD DS.