EMS G Suite 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 G Suite 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.

ClosedGet New License

Existing customers need a new license. Contact your EMS Account Representative.

To import your license from the EMS Desktop Client:

  1. In EMS Desktop Client, navigate to System Administration > Settings > Registration.

    The Registration dialog opens.

  2. Click Import.

    The Open File dialog opens.

  3. Locate and select the license file (License.lic).

  4. Click Open.

    The license file imports.

ClosedConfigure Service Account

If you're a EMS Cloud customer licensed for EMS G Suite Integration, the EMS team creates and manages the service account for you.

You can skip ahead to Enable G Suite Marketplace App.

To configure the service account for the EMS G Suite Integration:

  1. You must be an active G Suite Customer.

  2. Enable Admin API and Admin SDK.

  3. Enable Calendar and Drive APIs.

  4. Create Service Account Credentials (Service Account ID and Private Key).

Known Issue for Update 32If you click the G Suite Integration enable/disable button after the first time the integration is enabled, the integration breaks.

After you enable G Suite Integration the first time and then click enable/disable again on the Calendaring tab, G Suite Integration stops working.

To fix the integration:

  1. From the Calendaring tab of the EMS Platform Services Admin Portal, set enable/disable to enabled. Refresh the page.

    • Enabled – red and displays Disable GSuite Integration.
    • Disabled – green and displays Enable GSuite Integration.

  2. Re-upload the JSON file.

    Do not click enable/disable after re-uploading the JSON file.

  3. After the JSON file upload ends, restart the app pool used by EMS Platform Services.

    EMS Cloud Services Customers – EMS Cloud Operations must restart the app pool for EMS Platform Services.

    To request a restart, contact EMS Support.

Enable Google Calendar and Google Drive APIs

To enable Google Calendar and Google Drive APIs:

  1. Navigate to the Google Cloud Platform page.

  2. To manage the G Suite integration with EMS Software, create a separate project.

  3. On the Google Cloud Platform page, on the side navigation, select APIs & Services.

  4. On the Google API Dashboard, click Enable APIs and Services.

  5. Search for Admin SDK and click Enable.

  6. Search for Calendar API and click Enable.

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

To create service account credentials:

  1. From the Google Cloud Platform console, on the side navigation, select IAM & Admin.

  2. Select your project.

  3. Select Service Accounts.

  4. Click Create New Service Account.

  5. Add a Service Account name.

  6. Do not select a Role from the field.

  7. Click Create Key, select JSON.

  8. 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.

  9. Under Actions for the service account, click the three dots and select Edit.

  10. Select Enable G Suite Domain-wide Delegation and then Save.

    Note the Client ID now displays. Save this for the next step.

  11. To grant permissions to the service account for your G suite domain:

    1. To view users on the domain, access the G Suite Admin Console.

    2. Navigate to Security > Advanced Settings > Manage API Client Access.

      Advanced Settings is not available under the Security menu in the main navigation pane.

    3. 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.

    4. 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
  12. Click Authorize.

ClosedVerify 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 or Mobile app with G Suite integration enabled or EMS for Google Calendar).

To authorize domains/URLs for subscribing to events from G Suite:

  1. Go to: https://console.developers.google.com/apis/credentials/domainverification

  2. Select your EMS Integration GCP project.

    You can verify the name of your selection in the top left.

  3. Click Add Domain.

  4. 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.

  5. Click Add Domain.

  6. On the Verify Ownership dialog, click TAKE ME THERE.

  7. In Domain Name Provider, choose Other.

  8. Click the Add a CNAME record link.

  9. 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

  10. Click VERIFY.

    If you end up away from this page, you can follow the steps again to produce the same records.

ClosedEnable 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, please refer to the EMS Cloud Services documentation.

NSQ Messaging Type must be enabled to use EMS for Google Calendar or EMS for Microsoft Exchange (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).

Note:

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>

Note:

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

ClosedEnable the G Suite Marketplace App

The EMS Cloud team will manage the service account used for the integration for you, for which access is controlled by separate G Suite 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.

ClosedConfigure Organizational Sync G Suite Mailbox OAuth

The Organizational Sync Mailbox OAuth must be configured for your OAuth project.

To perform the Organizational Sync G Suite Mailbox OAuth:

  1. Update the application to version 220.1.
  2. In your GCP instance, create a new OAuth 2.0 Web Application.

    1. Navigate to Main Menu > APIs & Services > Credentials.
    2. On top of the page, click Create Credentials > OAuth client ID.
    3. Create a new web application.

      You can specify your redirect URLs during the creation or add them later.

  3. 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.

  4. 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.

  5. Navigate to your platform admin UI and login.
  6. On the Integrations pane, click the EMS Admin integration.
  7. 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.

  8. Clear the platform cache.
  9. Refresh the page.

ClosedCreate and Add a Service Account Mailbox

As of Update 31, you need a Service Account Mailbox for the G Suite 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 G Suite Integration.

To add the mailbox to the G Suite Integration:

  1. From the EMS Platform Services Admin Portal, select the Calendaring tab.

  2. In Service Account Mailbox, enter the mailbox address.

  3. Click Update.

    The G Suite Integration updates with the Service Account Mailbox.

ClosedEnable Integration in EMS Platform Services

To enable integration in EMS Platform Services:

  1. In EMS Platform Services, select the Calendaring tab.

  2. Upload the JSON file for G Suite configuration.

  3. Click Enable.

ClosedUpdate 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

ClosedAllow and Whitelist the EMS for Google Calendar Chrome Extension

Manage the Chrome Extensions in G Suite 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 G Suite Administrator may be required to whitelist the OAuth Client ID for your G Suite 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.

To enable EMS for Google Calendar as an individual user:

  1. Navigate to the Chrome Web Store.

  2. Search for EMS for Google Calendar.

  3. Add to your browser.

    A prompt indicates the extension will access your account.

  4. Click Allow.

  5. Enter the EMS Platform Services URL.

ClosedConfigure EMS for Google Calendar in EMS Desktop Client

Administrators must configure EMS for Google Calendar in their EMS Desktop Client.

To configure EMS for Google Calendar in your EMS Desktop Client:

  1. ClosedCreate an Everyday User Process Template for EMS for Google Calendar.

    To create an Everyday User Process Template for EMS Google Calendar:

    1. In Everyday User Application Settings, select the Enable Integration to G Suite.

    2. Select Enable EMS for Google Calendar.

  2. Configure at least one intent.

  3. ClosedCreate 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.

  4. Ensure a Default Setup Type is configured

  5. ClosedEnsure all rooms have mailboxes.

    A mailbox must be configured for TBD rooms.

    To configure a mailbox for a room:

    1. Create a mailbox in Google.

    2. 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.

    3. Click Edit.

    4. Enter the room mailbox on the Google Integration tab.

    5. Enter valid emails from the G Suite 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.