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 FacilityOS support 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 FacilityOS support 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.

     Note:

     To know which fields you can enter in your script, see the table in Data field mapping.

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)

Data field mapping

The table below lists the names of the data fields your script can include.

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.