EMS Google Workspace Integration Installation
Installation Checklist
Requirement | On-prem Customers | Cloud Customers |
---|---|---|
Obtain New License | Yes | Yes |
Configure Service Account | Yes | No |
Verify Domain in GCP Project | Yes | No |
Enable Platform Services NSQ | Yes | No |
Enable Google Workspace Marketplace App | No | Yes |
Configure Organizational Sync G Suite Mailbox OAuth | Yes | No |
Create and Add Service Account Mailbox | Yes | Yes |
Enable Integration in Platform Services | Yes | Yes |
Update Parameters in EMS Desktop Client | Yes | Yes |
Allow and Whitelist EMS for Google Calendar Chrome Extension | Yes | Yes |
Update Configuration in EMS Desktop Client | Yes | Yes |
- Everyday Users can't choose a setup type. EMS for Google Calendar books a room based on the default setup type. Administrators must configure a default setup type for any room used by EMS for Google Calendar.
- List type user defined fields (UDFs) are supported, and without dependent UDFs.
- Categories, service orders, billing reference, and PO numbers are not supported.
- Selection of contacts within groups is not available. EMS for Google Calendar uses the group's default contact.
- If you are not deploying EMS for Google Calendar domain verification is not necessary.
Get New License
Existing customers need a new license. Contact your EMS Account Representative.
Import your license from the EMS Desktop Client:
-
In EMS Desktop Client, navigate to System Administration > Settings > Registration.
The Registration dialog opens.
-
Click Import.
The Open File dialog opens.
-
Locate and select the license file (License.lic).
-
Click Open.
The license file imports.
Configure Service Account
If you're a EMS Cloud customer licensed for EMS Google Workspace Integration, the EMS team creates and manages the service account for you.
You can skip ahead to Enable Google Workspace Marketplace App.
Configure the service account for the EMS Google Workspace Integration:
-
You must be an active Google Workspace Customer.
-
Create Service Account Credentials (Service Account ID and Private Key).
Enable Google Calendar and Google Drive APIs
-
Navigate to the Google Cloud Platform page.
-
To manage the Google Workspace integration with EMS Software, create a separate project.
-
On the Google Cloud Platform page, on the side navigation, select APIs & Services.
-
On the Google API Dashboard, click Enable APIs and Services.
-
Search for Admin SDK and click Enable.
-
Search for Calendar API and click Enable.
-
Search for Drive API and click Enable.
Create Service Account Credentials
The step 10. d of this procedure changed starting with Update 34.
EMS integrations requires the Service Account ID and Private Key.
-
From the Google Cloud Platform console, on the side navigation, select IAM & Admin.
-
Select your project.
-
Select Service Accounts.
-
Click Create New Service Account.
-
Add a Service Account name.
-
Do not select a Role from the field.
-
Click Create Key, select JSON.
-
Click Done.
Save and securely store the .JSON file that downloads automatically as it cannot be regenerated. If lost or compromised, you'll need a new key and JSON file.
You should now see the service account and key ID that you just created.
-
Under Actions for the service account, click the three dots and select Edit.
-
Select Enable Google Workspace Domain-wide Delegation and then Save.
Note the Client ID now displays. Save this for the next step.
-
To grant permissions to the service account for your Google Workspace domain:
-
To view users on the domain, access the Google Workspace Admin Console.
-
Navigate to Security > Advanced Settings > Manage API Client Access.
Advanced Settings is not available under the Security menu in the main navigation pane.
-
In the Client Name field, enter the client ID that you saved in step 10.
To access the API client ID , in the GCP Console, navigate to IAM & Admin > Service Accounts > View Client ID.
-
Copy and paste the following scopes in the One or More API Scopes field:
If you are not using EMS for Google Calendar Chrome Extension:
- https://www.googleapis.com/auth/admin.directory.user.readonly,
- https://www.googleapis.com/auth/calendar.events,
- https://www.googleapis.com/auth/calendar.readonly,
- https://www.googleapis.com/auth/drive.file,
If you are using the EMS for Google Calendar Chrome Extension (additional license required), the full set of scopes required are as follows:
- https://www.googleapis.com/auth/admin.directory.user.readonly,
- https://www.googleapis.com/auth/drive.file,
- https://www.googleapis.com/auth/userinfo.email,
- https://www.googleapis.com/auth/userinfo.profile,
- https://www.googleapis.com/auth/calendar.events,
- https://www.googleapis.com/auth/calendar.readonly,
- https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly
- https://www.googleapis.com/auth/calendar.settings.readonly
-
-
Click Authorize.
Verify Domain in GCP Project
If you are not deploying EMS for Google Calendar domain verification is not necessary.
This step will allow EMS Platform Services to use web hooks to subscribe to changes to your Google Calendar room mailboxes without waiting for a polling interval. The user impact is that actions like drag and drop from the users’ calendars or edits from mobile devices will be synchronized back to EMS very quickly, usually within seconds (for meetings reserved using EMS Web App with Google Workspace integration enabled or EMS for Google Calendar).
Authorize domains/URLs for subscribing to events from Google Workspace:
-
Go to: https://console.developers.google.com/apis/credentials/domainverification
-
Select your EMS Integration GCP project.
Verify the name of your selection in the top left.
-
Click Add Domain.
-
In Domain, enter your EMS Domain name. For example: 'my-ems-subdomain.myorganization.com'.
This must be an externally resolvable DNS where your installation of EMS Platform Services can be reached.
-
Click Add Domain.
-
On the Verify Ownership dialog, click TAKE ME THERE.
-
In Domain Name Provider, choose Other.
-
Click the Add a CNAME record link.
-
Use the CNAME Label / Host and the CNAME Destination / Target to update your DNS configuration for your EMS domain.
For example: 'my-ems-subdomain.myorganization.com'
For more information, refer https://support.google.com/a/answer/47283?hl=en
-
Click VERIFY.
If you end up away from this page, you can follow the steps again to produce the same records.
Enable NSQ Messaging in EMS Platform Services
Enable NSQ Messaging
EMS Cloud Services Customers
The configuration information in this topic does not apply to EMS Cloud Services customers. For more information regarding the configuration of EMS software with Cloud Services, refer to the EMS Cloud Services documentation.
NSQ Messaging Type must be enabled to use EMS for Google Calendar or EMS Exchange Room Integration (ERI) (Exchange-to-EMS sync option). NSQ Messaging Type is a feature built within EMS Platform Services. Once NSQ is enabled, no additional software installation is required for NSQ.
To enable NSQ Messaging Type, follow the instructions below based on the type of environment where EMS Platform Services is installed:
Environments with a Single Application Server
For environments with a single application server where EMS Platform Services is installed, add the following environment variables to the web.config file for the application:
<environmentVariable name="ems_messaging_type" value="nsq" />
<environmentVariable name="TMP" value="C:\inetpub\wwwroot\Platform2wLogs" />
All environment variables added to the Platform Services web.config should be added inside the aspNetCore section and grouped between lines to open and close the section with:
<environmentVariables>
</environmentVariables>
To enable NSQ, you must add an "ems_messaging_type" variable (note that the value MUST be lower case) and a "TMP" variable, as seen below. Note that the value specified for "TMP" is a folder that must be created on the server and must be a folder that is not overwritten by the OS (for example c:\temp is not a good choice here) and must be writable by Platform Services (typically by adding write and modify access for the folder to the IIS_IUSRS user under the folder properties > security tab).
If using a version later than EMS 44.1.35, you don't need <environmentVariable name="ems_messaging_type" value="nsq" />. You can remove it if previously added.
An example for Update 34:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified"/>
</handlers>
<aspNetCore processPath="./restapi.exe" arguments="" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="true">
<environmentVariables>
<environmentVariable name="ems_messaging_type" value="nsq" />
<environmentVariable name="TMP" value="C:\inetpub\wwwroot\PlatformNSQLogs" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</configuration>
From Update 35 and later, the value "nsq" is no longer case-sensitive.
Environment with Multiple Nodes Behind a Load Balancer
For environments with multiple nodes behind a load balancer, you must configure additional environment variables to successfully enable NSQ. The IP addresses or hostnames used will depend on those assigned to each node.
Example—Enabling NSQ in a Three Node Environment
For this example, the following instructions will assume a three-node environment: Node A, Node B, and Node C. You will need to complete the same type of configuration for every node within the cluster. For the NSQ to function properly, the EMS Platform Services instances need to know where each other are located on the network.
In the following example, 192.168.1.1, HOSTNAME-A, HOSTNAME-B, and HOSTNAME-C are for demonstration purposes only.
Web.config Environment Variables for Example Node A:
EMS_MESSAGING_NSQ_TCPAddr and EMS_MESSASGING_NSQ_HTTPAddr Variables
Set the variables EMS_MESSAGING_NSQ_TCPAddr and EMS_MESSASGING_NSQ_HTTPAddr to an internal IP address assigned to the server running EMS Platform Services for which the current web.config is being edited. The IP address should be actually assigned to the machine, but not necessarily reachable. Using the Node A example, this configuration would reference the internal IP for Node A—192.168.1.1.
<environmentVariable name="EMS_MESSAGING_NSQ_TCPAddr" value="192.168.1.1" />
<environmentVariable name="EMS_MESSASGING_NSQ_HTTPAddr" value="192.168.1.1" />
EMS_MESSAGING_NSQ_BroadcastAddr Variable
Set the variable EMS_MESSAGING_NSQ_BroadcastAddr to an internal IP or a hostname (that is assigned to an internal IP) that other instances of EMS Platform Services can use to reach this one—set to the reachable hostname for Node A at which other nodes can reach it. The EMS_MESSAGING_NSQ_BroadcastAddr variable is only required if the reachable address is different from EMS_MESSAGING_NSQ_TCPAddr and EMS_MESSASGING_NSQ_HTTPAddr, which can happen due to the server being behind a NAT router, for example.
<environmentVariable name="EMS_MESSAGING_NSQ_BroadcastAddr" value="HOSTNAME-A" />
EMS_MESSAGING_NSQ_AdditionalNSQDAddrs and EMS_MESSAGING_NSQ_AdditionalLookupdAddrs Variables
Set the variables EMS_MESSAGING_NSQ_AdditionalNSQDAddrs and EMS_MESSAGING_NSQ_AdditionalLookupdAddrs to the broadcast IP addresses or hostnames of the other nodes within the cluster, as defined by the EMS_MESSAGING_NSQ_BroadcastAddr variable in the web.config for each EMS Platform Services instance. Each variable should exist only once per web.config with the value for the variable containing all the values within the cluster (comma separated with no spaces within the string).
<environmentVariable name="EMS_MESSAGING_NSQ_AdditionalNSQDAddrs" value="HOSTNAME-B,HOSTNAME-C" />
<environmentVariable name="EMS_MESSAGING_NSQ_AdditionalLookupdAddrs" value="HOSTNAME-B,HOSTNAME-C" />
NSQ uses four ports on every node in the cluster and these ports must be open on each: 4150,4151,4160,4161
Enable the Google Workspace Marketplace App
The EMS Cloud team will manage the service account used for the integration for you, for which access is controlled by separate Google Workspace Marketplace App. Contact your implementation consultant to begin this process. The EMS team will also be responsible for uploading the JSON in EMS Platform Services.
Configure Organizational Sync G Suite Mailbox OAuth
The Organizational Sync Mailbox OAuth must be configured for your OAuth project.
- Update the application to version 220.1.
-
In your GCP instance, create a new OAuth 2.0 Web Application.
- Navigate to Main Menu > APIs & Services > Credentials.
- On top of the page, click Create Credentials > OAuth client ID.
-
Create a new web application.
You can specify your redirect URLs during the creation or add them later.
-
Find your new web application in the OAuth 2.0 Client IDs pane of the Credentials page, and click the name of the application to open it for editing.
Add your environment to the web application if you did not add it during its creation.
-
Add your URL to the Authorized JavaScript Origins pane.
It can't contain a wildcard (https://*.example.com) or a path (https://example.com/subdir). If you're using a nonstandard port, you must include it in the origin URL.
- Navigate to your platform admin UI and login.
- On the Integrations pane, click the EMS Admin integration.
-
In the Audience field of the EMS Admin Integration, enter the Client ID provided in the GCP.
The Client ID can be found on the Credentials page to the right of the name of your web application.
- Clear the platform cache.
- Refresh the page.
Create and Add a Service Account Mailbox
As of Update 31, you need a Service Account Mailbox for the Google Workspace Integration. The Service Account Mailbox can be any mailbox within your domain or your organizational unit if you are not integrating the entire domain. The mailbox does not require special permissions.
This is NOT the mailbox associated with the service account created in the previous step. This is a separate mailbox.
After you create a Service Account Mailbox, add the mailbox to the Google Workspace Integration.
-
From the EMS Platform Services Admin Portal, select the Calendaring tab.
-
In Service Account Mailbox, enter the mailbox address.
-
Click Update.
The Google Workspace Integration updates with the Service Account Mailbox.
Enable Integration in EMS Platform Services
-
In EMS Platform Services, select the Calendaring tab.
-
Upload the JSON file for Google Workspace configuration.
-
Click Enable.
Update Parameters in EMS Desktop Client
When G Suite integration is enabled, Sync events from G Suite to EMS parameter should be set to yes. This can be found by logging in as an administrator to the EMS Desktop Client and navigating to System Administration > Settings > Parameters > Desktop Client tab.
The Platform Services URL parameter should be set to the correct URL for your environment. This can be found under System Administration > Settings > Parameters >Everyday User Applications tab.
The URL must include “/api/v1” after the virtual directory name – for example https://yourdomain.com/EmsPatform/api/v1
Allow and Whitelist the EMS for Google Calendar Chrome Extension
Manage the Chrome Extensions in Google Workspace Admin Console under Device Management > Chrome > Apps & extensions. Search for EMS for Google Calendar in the Chrome Web Store, then you can allow users to install EMS for Google Calendar themselves or force install to the entire domain or specific organizational units (OU).
For some organizations, the Google Workspace Administrator may be required to whitelist the OAuth Client ID for your Google Workspace domain.
EMS for Google Calendar OAuth Client ID:
317959924954-mels609gce2f9f4onhti7r09gubka3fs.apps.googleusercontent.com
The Platform Services URL must be shared with users for them to add it to the extension, and that users must have Chrome sync enabled for their account that corresponds with their EMS Everyday User account (email addresses must match). The user must be signed into both Chrome and Google Calendar with this same account.
Enable EMS for Google Calendar as an individual user:
-
Navigate to the Chrome Web Store.
-
Search for EMS for Google Calendar.
-
Add to your browser.
A prompt indicates the extension will access your account.
-
Click Allow.
-
Enter the EMS Platform Services URL.
Configure EMS for Google Calendar in EMS Desktop Client
Administrators must configure EMS for Google Calendar in their EMS Desktop Client.
-
Create an Everyday User Process Template for EMS for Google Calendar.
To create an Everyday User Process Template for EMS Google Calendar:
-
In Everyday User Application Settings, select the Enable Integration to Google Workspace.
-
Select Enable EMS for Google Calendar.
-
-
Create a TBD Room with a mailbox
Everyday Users resolving a booking conflict may need to skip adding a room to their reservation in EMS for Google Calendar. Configure a TBD room with an associated mailbox. One TBD room is needed per building.
-
Ensure a Default Setup Type is configured
-
Ensure all rooms have mailboxes.
A mailbox must be configured for TBD rooms.
To configure a mailbox for a room:
-
Create a mailbox in Google.
-
From the EMS Desktop Client, navigate to Configuration > Facilities > Rooms. Filter the dialog to display the rooms you want to edit. Only add email addresses to rooms and not resources.
-
Click Edit.
-
Enter the room mailbox on the Google Integration tab.
-
Enter valid emails from the Google Workspace domain with which you are integrating EMS; if invalid emails or emails from other domains are added to EMS configuration they will not be synchronized to EMS and can have other negative impacts.
-