How does this app work?
Google Workspace is a set of intelligent apps including Gmail, Docs, Drive and Calendar to connect the people in your company, no matter where in the world they are.
If your team uses Google Workspace, you can use this app to automatically keep your Envoy employee directory up to date. With the Envoy + Google Workspace app, your Google Workspace directory will sync to Envoy every 24 hours. You can also choose to manually sync at any time if you need an immediate update.
Note: You can manually create new employees or add employees from other locations while maintaining your directory sync. This feature is helpful for contractors, temps or other people who may host visitors/receive deliveries but are not core team members. Learn more about manually adding employees.
Enabling the Envoy + Google Workspace app
Note: You’ll need to have Google admin privileges to complete this installation (see below). Either become an admin or ask your admin for help before completing these steps:
Go to Apps > All Apps.
Under Directory and SSO, select "Directory Settings," find the Google logo and click “Install”.
Choose the Google account with the appropriate admin permissions.
When prompted to provide offline access, click “Allow”.
Choose an employee sync filter
When you connect a Google Apps account, you have three options on how to sync employees to your directory. Choose the one that’s right for you:
Sync all employees: This is good for companies with one location, or if you prefer to have the same master Envoy employee directory at all locations within your company.
Sync specific employees company-wide: Choose this option if you’d like to exclude certain Google users from your Envoy directory (such as team accounts, bot accounts, etc).
Sync specific employees per location: Choose this option if you’d like to sync certain Google users to certain locations (i.e., creating different Envoy employee directories per location). Additionally with this option, you can exclude certain users (such as team accounts, bot accounts, etc). from any Envoy directory.
How to sync all employees
Click on sync all employees to select this option.
Click “Test filter,” and you’ll see your full list of all Google users appear.
Review your list. If everything looks correct, click “Save filter and sync.”
Go to Employees > Directory to view your newly populated employee directory.
How to sync employees company-wide
Note: this option requires you to configure your filters within your Google directory using the Google Directory API. See On filtering, for more details.
Click on sync specific employees company-wide to select this option.
Type your field and description in the company-wide search string field to set the filter. In this example, we’re using a custom orgUnitPath field to filter out team and bot accounts.
Important Notes:
Your OrgUnitPath can be one word or combined with
_. If your OrgUnitPath has a space you can format is asorgUnitPath='/City Name'.You can add different fields to create a more complex filtering system. When filtering based on two parameters, just put a space in between to create one long string.
Envoy looks for users that match both parameters, not one or the other. So this example will return users that are both in employees orgUnit and are not suspended.
Review your list. If everything looks correct, click “Save filter and sync.”
Go to Employees > Directory to view your newly populated employee directory.It could take a few hours to fully sync over.
How to sync employees per-location
Note: this option requires you to configure your filters within your Google directory using the Google Directory API.
Click on sync specific employees per-location to select this option.
Type your field and description in the each location’s search string field to set the filter. In this example, we’re using a custom orgUnitPath field to filter out team and bot accounts and using the addressLocality field to filter by location.
When filtering based on two parameters, just put a space in between to create one long string.
Review your list. If everything looks correct, click “Save filter and sync.”
Go to Employees > Directory to view your newly populated employee directory.
On Filtering
We use the Google API filters to filter employees in your Google Workspace directory. Use the Google Directory API documentation to build your filters (queries).
Tips:
The 'AND' operator in the filter is designated by a space.
For example,
orgUnitPath=/Employees isSuspended=falsewill return users from from Org Unit 'Employees' who are not suspended.
If you have a space in your OrgUnit name, you must put single quotes around the name and BEFORE the '/'.
For example,
OrgUnitPath='/My Employee Org Unit'
Common Filters
Sync per OrgUnit:
OrgUnitPath=/<your org unit name>
The Google Directory API filters only support one OrgUnit at a time. So if you wanted to put users from two different Org Units into the same location, you would need to filter another way (e.g. custom attribute like Primary Location).
OrgUnitPath=/OrgUnit1 OrgUnitPath=/OrgUnit2 will not work due to limitations of the Google Directory API filtering.
Sync only employees that are not suspended (this works for any boolean attribute)
isSupended=false
Sync by a custom attribute
<schemaName>.<fieldName>:"<value for attribute">
For example,
EnvoyAttributes.defaultLocationName:"Avengers"
This would return all users who have a custom attribute defaultLocationName that equals 'Avengers'. <schemaName> is pulled from the higher category of the attribute in the employee's Google Workspace profile.
Syncing Employee Profile Attributes
Envoy offers the option to sync the following attributes from Google: Job title, Manager, Department, Primary location, and Remote status.
Configuration of profile attributes
Job title, Manager's email, and Department are standard attributes in Google Workspace which should populate in Envoy automatically so long as they are filled out in Workspace.
To sync the manager profile field in Envoy, please fill out the manager's email field within the employees's Google Workspace profile. This email must be also be a synced user. The manager field will not sync if the email you are adding comes from an employee that has been manually added to Envoy.
Primary Location & Remote Status
Primary location and remote status must be added as custom attributes in Google Workspace in order to be synced.
How to add the custom attributes:
From the Google Admin dashboard, navigate to Directory > Users
Click the More Options drop-down and select Manage Custom Attributes
Click Add Custom Attribute
For Category, enter "EnvoyAttributes"
For Primary location, enter the following values
Name: defaultLocationName
Info type: Text
Visibility: Visible to organization
No. of values = Single Value
For Remote status, enter the following values
Name: remoteStatus
Info type: Text
Visibility: Visible to organization
No. of values: Single Value
Click the Add button
You should now be able to return to the user's profile and fill in the values.
Note: For Primary Location to map, the location name must exactly match the value entered. For example, if the name of the location is "Austin" then the primary location field value must be "Austin".
Only certain values will be accepted for Remote status - we encourage using Remote and In person. Please see the following table for other values that can be used to map Remote status:
Accepted Value | Envoy |
remote
working from home
wfh | Remote |
in person
telecommuting
in-office, in office
on-site, on site, onsite
office-based, office based
hybrid
flexible
blended | In person |
Important notes
Regarding phone numbers
If you have employee cell phone numbers listed in Google, they will sync to your Envoy employee directory automatically. If you do not have employee cell phone numbers listed in Google, you may want to consider adding them to Google now. To do so, follow the steps below.
Log in to your Google Admin portal, and click on Users.
Find the user you’d like to assign a phone number, and click on their entry.
Within the user entry, click on “User information.”
Scroll down to locate “Contact” and click on the Add Mobile Phone.
Add in their mobile phone number. In the drop down on the right, select Mobile. Then click on Save.
Regarding custom sync settings per employee
Once your directory has synced with Envoy, you can decide if you’d like to keep syncing enabled or disable syncing for each employee.
Regarding Google Workspace Admin privileges
To enable the Envoy + Google Workspace app, you’ll need to connect with the Super Admin on your Google Apps account. This person will have access to the Google admin console. Please share this guide with them to ensure they correct permissions are granted.
Guide for the Google admin:
Enable API Access. Depending on other apps and tools you use at your location, this may already be enabled. If you need help, view this step-by-step guide from Google.
The employee who will log into Envoy to complete the sync needs user read privileges. You can either provide these privileges to the office manager/receptionist or just assist them by syncing all employees using your account.
To check if an employee has user read privileges. Go to their account (Users > “User Name”), and click “View Privileges.” Scroll down to Users and ensure that “Read” is checked.
Note: If you do not have the above privileges enabled, you will likely receive an error when authenticating into your Google instance. That error message will read: Authorization Error: Error 400: admin_policy_enforced
To correct this, follow the steps above to enable necessary privileges for the Envoy app.