You can easily sync your Receptionist Contacts with your team's Active Directory system, enabling automatic Contact updates!
Overview
To sync your Active Directory with our system, your team must be familiar with PowerShell V.3 or above, the names of the Organization Units in your Active Directory instance, and how to schedule jobs with a Powershell script.
We provide a PowerShell template to get started, and it can be configured or modified to connect to your Active Directory. The template exports your employees to a CSV file and then uploads the CSV to our servers for processing.
Getting Started
Navigate to the Active Directory Integration page on the web portal to find our template and additional information.
Configuring the Script
The script includes built-in documentation, so it can be easily configured as you go, but this article contains a few critical points of reference.
The script is broken into two different sections: Configuration and Execution. It will be helpful to look through both sections and ensure the script conforms to your AD environment. We recommend paying particular attention to the $OUS variable, and we detail different ways you may use this variable in the script. It is especially handy when mapping different Organization Units to different locations.
The Export-OrganizationUnit function should be altered if you want to include additional contact data that is not represented by this template.
The following is a complete list of attributes that you can specify in the CSV file and an explanation of each column (please note which fields are required):
First Name - This required field should be populated with the employee's first (or given) name.
Last Name - This required field should be populated with the employee's last (or family) name.
Email - This field should be set to the employee's unique email address. It is required if you do not include an SMS number.
SMS Phone - This field should be set with the unique SMS-capable phone number of the employee. It is required if you do not include an email.
Business Title - This optional field can be populated with a relevant title for your organization.
Department - This optional field can be populated with a department name that is meaningful to your organization. The iPad will automatically group your contacts based on their department if this is entered. If you are a co-working space, this could also be used to enter the company name to make it easy for visitors to find their contacts. Read more about Departments here.
Image - This optional field can be populated with a publicly accessible URL to download and use as the CoContact'sicture.
PIN - This optional field can be used to configure employees' PINs that they can use when checking in or out using an Employee Button. A PIN should be at least four and not longer than six digits.
Location Slug - This field should be populated with the identifier of the location where the Contact is available to be chosen by your visitors and is required for accounts with multiple locations. This field is configured on the Location Edit screen using the "Identifier" field.
Identification - This optional field is intended to represent the internal identifier associated with an employee in your system. The importer will first use the value in this field to determine whether the Contact already exists in our system. Using this field, you can update a Contact's phone number or email address without creating a new contact in our system.
Slack - This optional field can be populated with the Slack username of the employee (without the @ symbol) to enable The Receptionist to send Slack notifications to the employee. The Slack integration must be turned on for your account to use this section.
The Execution section of the script should only be changed if you have issues and are attempting to troubleshoot.
Active Directory and Multiple Locations
If you have multiple locations, each Organizational Unit in your Active Directory that contains Contacts needs to be paired with the corresponding location (i.e., your Headquarters location gets one Organization Unit and your Warehouse location gets another).
First, verify that the location is spelled exactly as it is on your account under Locations > edit > identifier. You'll need that identifier to edit into your script.
To make a Contact available for multiple locations, put the Contact's Active Directory User Profile into the corresponding Organizational Units. When the script is run, it will export the Contact for each Organizational Unit and import it into each corresponding location. If your configuration is global, contacts will automatically be added to All Locations.
Testing & Scheduling the Script
Now that you have configured the script, you can run it and ensure it works properly. Any errors that are encountered will be printed for you to see and troubleshoot; if you have any trouble interpreting the errors, please hop on a chat with us by clicking on the orange text box in the lower right corner of your screen. If the script succeeds, the email address associated with your Receptionist for iPad account will receive a sync summary.
Once you feel confident that the script is working correctly, you should schedule it (using Windows Scheduler) to run regularly. Each time your script runs, an import summary email will be sent.
What Does The System Do With The Imports?
When the import runs, the CSV is processed one row at a time. With each row, the import attempts to find an existing contact using the Identification, Email, and SMS Phone attributes.
If a Contact is found by any of these attributes, that Contact is updated with the data in the row.
If a contact is not found, then a new contact is created.
If the Contact did not previously have a message rule, messaging rules will automatically be created for any included notification types (e.g., email, SMS, or Slack).
At the end of the import, any Contacts that were not found, updated, or created will be archived; this means they will not be counted against your plan's Contact count or visible to visitors checking in.
What about LDAP?
If your organization uses vanilla LDAP instead of Active Directory, the PowerShell template should give you a good idea of what a script must do to sync with our system. If you have an account with us, the Contact Import Integration page is another resource that outlines the details of the CSV file that you will need to create and how that file will need to be transmitted to us.
Troubleshooting
Our PaaS no longer supports TLS 1.1 and 1.0 connections as of July 31st, 2021. Unfortunately, PowerShell will use these older versions of TLS by default. To correct this, you should add the following command just before the Invoke-RestMethod line in your script to force TLS 1.2 to be used:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
If you're having errors, ensure this line has been added first and foremost!
The most common other issues we see with this script are:
Incorrect or Invalid Data: The easiest way to troubleshoot an import that is not achieving the results you expect on our side is to view the raw CSV file that the script creates before sending it to us.
To view the file, comment out the Invoke-RestMethod line in the script, run the script, and then open the generated CSV file in a text editor or spreadsheet. You will then be able to see any incorrect formatting or data mapping and adjust the script accordingly.
Import Errors: Any issues our importer has processing the CSV file that this script generates will be reported back via an email associated with the API Key specified at the top of this script. If you see something like "invalid UTF-8 byte sequence", "here is data in Active Directory that could not correctly be converted to UTF-8. The easiest way to troubleshoot this issue is to open the CSV file in Notepad and look for odd characters, such as �. You will need to edit the relevant data in the Active Directory to make it a valid character.
Attribute Mapping: If your Active Directory installation doesn't have the attributes specified in the Export-OrganizationUnit function, the script will give error reports about the missing attribute. You will need to adjust the Expression items to use the correct attribute.
Environment: This script assumes you are running PowerShell version 3 or higher. If you ever see a message about a command not being available, please check the version of PowerShell that you are using and update it to the latest version available.
While we can't build your script for you, we're happy to troubleshoot any errors or answer specific questions regarding script elements or lines! If you're having trouble, please click on the orange chat bubble on the lower right of your screen to live chat with a team member!