1. FacilityOS Help Center
  2. FacilityOS
  3. Introduction to FacilityOS

Address Book Integration

Adam Belfield
Updated

This document is created to outline possible ways of integrating the FacilityOS Address Book with your locally hosted active directory(AD) or Azure/Microsoft Entra ID Enterprise system for the purpose of automation of data entry and maintenance. The goal is to keep the FacilityOS Address Book updated with the latest employee data via sync with another business system. The approach must be secure, efficient and maintain the desired level of compliance and confidentiality.

Security and Confidentiality of Data 

This document falls under FacilityOS’s privacy and security policies which mandate a sufficient level of encryption and data segmentation to be present throughout the platform. For the purpose of this document following guidelines are to be followed: 

  • Minimum of TLS 1.2 encryption to be used for all data transfers 
  • All data submissions must be uniquely tokenized or identified using a unique key ID and secret, issued to a specific client. Clients may have more than one key, but each key can only be assigned to one client. 
  • Expired key/tokens are not to be re-used 
  • All data must travel from the customer system, directly into the protected area of FacilityOS. No middle servers/repositories are to be used, unless they are in-scope and make up the FacilityOS platform. Under no circumstances will FacilityOS request the client to post data to an insecure server, even temporarily. 
  • VPN and IP restricted connections may be used to further safeguard the data

Synchronizing Data 

Prior to synchronizing please note, if a manual record exists of the record, in order for the AD record to sync, the manual record will need to be removed. We do not override or eliminate the duplicate record if a manual record exists, they are treated separately. Manual records must be deleted in order to avoid duplicate entries of manual and synced entries. And if a user's name surpassed 50-characters, their record will also not sync. Data is synchronized based on the email address of the address book entry. 

Few options are available for clients looking to sync address books for multiple locations. If this is a requirement, please contact support@facilityos.com for available options. 

Integration Option: Azure / Office 365

To set up synchronization between your Microsoft Azure Active Directory (Azure AD) and your FacilityOS Address Book, follow these steps: 

  1. Request Integration URL from FacilityOS: 
    • Contact FacilityOS support to provide you with a secure web URL hosted on the FacilityOS platform. This URL initiates the connection between FacilityOS and your Azure AD. 
  2. Authorize FacilityOS Access in Azure AD: 
    • Click the provided FacilityOS URL. 
    • You will be prompted to log in with your Azure AD credentials 
    • Review and approve the permission requests. FacilityOS requires read-only access to your Azure AD data to sync employee information. 
    • Upon approval, FacilityOS will receive an authentication token from Azure AD to maintain ongoing access. 
  3. FacilityOS Enterprise Application in Azure: 
    • After authorization, an Enterprise Application named "FacilityOS" (or iLobby) will appear in your Azure AD portal. 
    • This app represents the connection and can be managed or removed as needed. 
  4. Sync Behavior: 
    • FacilityOS will pull employee data based on email addresses. 
    • New employees in Azure AD will be added to the FacilityOS Address Book. 
    • Employees no longer present in Azure AD will be removed in FacilityOS. 
    • The sync is read-only and automated once set up. 
  5. Multiple Locations (if applicable): 
    • If you need to sync address books for multiple sites or locations, contact FacilityOS support for tailored options. 
  6. Verify Sync in FacilityOS: 
    • Log in to the FacilityOS Visitor Portal. 
    • Navigate to Manage > Address Book to view synced employee profiles. 
    • Confirm that employee data such as name, email, phone, and site assignments are correctly populated.
    • Please see Sample Office 365 Integration Screens at the end of this document for additional detail. 

Sample Office 365 Integration Screens 

When requested, FacilityOS support will provide the client with a unique integration link for establishing the connection between client’s O365 installation and FacilityOS. After navigating to the link, client will be presented with the following screens: 

Account Selection 

This screen will allow the client to select the user account with which the integration link will be established: 

 

Permissions Screen 

Once account is selected, our application will need to be authorized and granted the permissions required to access the contents of customer’s Office 365 installation: 

 

Application List 

Our application can now be managed in the list of installed applications and services under Enterprise Applications list within the Management tab of your Office 365 management portal: 

Integration Option: Locally hosted AD

Your FacilityOS address book can be populated with AD data by running the provided powershell script (see attachment) on the customer server. This is a push action, where the customer fully controls what data is pushed to the FacilityOS server and at what frequency. As a guideline, we recommend that only relevant data is submitted and that frequency is set at once per day. 

When requested, FacilityOS will provide the Client with an API key to be used for transmission. The key is to be inserted into the required part of the provided powershell script. The script may be modified to reflect the customer’s AD structure and consists of the following main parts: 

  • Querying AD for a list of users with specified fields and within specified AD groups 
  • Creation of a CSV file containing the list 
  • Upload of the CSV file to the FacilityOS Web API using the issued key 

Multiple sites may be synched using a single CSV file by specifying the correct site as per the sample format below, or by requesting unique API keys for each site in order to submit separate, site specific, CSV files. 

Integration Option: Custom Integration 

The FacilityOS address book can be populated with data from any source by submitting a pre-formatted CSV file to the FacilityOS API. As a guideline, we recommend that only relevant data is submitted and that frequency is set at once per day. 

When requested, FacilityOS will provide the Client and an API key to be used for transmission and the format for the URL request. The CSV file submitted must meet FacilityOS format standards in order to be processed. Sample format is attached.

Sample PowerShell script

See the example below of the updated PowerShell script for .CSV Address Book sync.

is this a powershell script? SAMPLE POWERSHELL SCRIPT, CHANGE EXTENSION TO .PS1 PRIOR TO EXECUTION#

<# 1. DEFINE SEARCH LOCATIONS #>

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

<# 2. SET API CREDENTIALS #>

$client_id = ''

$client_secret = ''

<# 3. SET OUTPUT DIRECTORY #>

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

<# 4. SET UP USER PROPERTIES TO EXPORT #>

$fields = @('mail','DisplayName','telephoneNumber','HomePhone')

 <# ACTIVE DIRECTORY USER EXPORT TO CSV FILE #> 

Import-Module ActiveDirectory                                      

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

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

<# GET TOKEN #>

$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

<# UPLOAD CSV FILE TO ILOBBY API #>

[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)

Sample CSV file format 

FIRSTNAME,LASTNAME,TITLE,DIVISION,EMAIL,MOBILE,DESKPHONE,SITE 

Rob,Jones,Manager,Management,rob.jones@test.com,4169998888,4169997777,Toronto

NOTE: When including the "SITE" column, please make sure that the values for all records match the site names in the FacilityOS portal.

Was this article helpful?
0 out of 0 found this helpful