Skip to content
  • There are no suggestions because the search field is empty.

Booking System Preparation - Google Workspace

This article will cover the process of preparing Google Workspace for HCP integration. During the process you will configure the following:

  1. Create New Project
    • Configure Project Authorization
    • Global Calendar Sharing
  2. Create & Configure Resource Calendars

Table of Contents

Common Use Cases

  • Setting up Humly Control Panel for the first time with Google Workspace as the booking backend.
  • Adding new meeting rooms or desks to an existing Google Workspace integration.
  • Updating the service account key after a key has expired or been revoked.
  • Migrating an existing P12 key setup to JSON (required for HCP version 2.3 and later).

Create New Project

  1. Navigate to Google Cloud Platform and log in using your Google Domain Admin account.

  2. Click Create Project.

    Create Project button

  3. Enter a name for your project and click Create.

    Enter project name

  4. A notification should appear when the project is created.

    Project created notification

  5. Click on the notification to reach the API Manager, or go to Menu Icon > API & Services > Dashboard.

    API Services Dashboard

  6. Click on Enable APIs and Services.

    Enable APIs and Services

  7. The API Library will appear. Search for Google Calendar API, select it and click Enable.

    Search for Google Calendar API Enable Google Calendar API

  8. Repeat the previous step to enable the Gmail API.

    Enable Gmail API

  9. Enable the last needed API: Admin SDK API.

    Enable Admin SDK API

  10. Click on the Menu Icon, select IAM & Admin, then select Service Accounts.

    Navigate to Service Accounts

  11. Click Create Service Account. Fill in the Name, ID and Description, then click Create And Continue.

    Create Service Account Fill in service account details

  12. Assign the service account the role Service Account Token Creator from the drop-down menu and click Continue.

    Assign Service Account Token Creator role

  13. Click Done. The service account should appear in the list. Press Manage Details to collect the needed information and create a key.

    Service account ready, click Manage Details

  14. Create a service account key by clicking on Keys, then Add Key.

    ⚠️ Important – HCP version 2.3 and later: From HCP version 2.3, new setups must use a JSON key. Select JSON as the key type and save the downloaded file — it will be needed when connecting HCP to Google Workspace.

    If you are running an HCP version earlier than 2.3, select P12 instead. Existing P12-based setups do not need to be changed unless you are upgrading to HCP 2.3 or later and setting up a new connection.

  15. Take note of the Client ID and the service account email address as they will be needed in later steps.

    Note Client ID and service account email

  16. Now grant the service account API access permissions. Navigate to admin.google.com, click Security, select Access and data control, then select API controls.

    API controls in Google Admin

  17. Select Manage Domain Wide Delegation.

    Manage Domain Wide Delegation

  18. Under API Clients, Add a new client using your service account Client ID. Copy and paste the following strings into OAuth scopes, then press Authorize:

    https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/gmail.send, https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly
    Add OAuth scopes

    Note: The admin.directory.resource.calendar.readonly scope is optional. All other scopes are required. The optional scope provides additional resource information such as the actual room name instead of the auto-generated name.

Create & Configure Resource Calendars

  1. Navigate to admin.google.com. Select Apps and then Calendar.

    Apps then Calendar in Google Admin

  2. Select the External Sharing option, then set external sharing options for primary calendars to "Only free/busy information (hide event details)".

    External sharing options Set free/busy sharing

  3. Create one or more calendar resources by navigating to Directory > Buildings and resources > Manage resources.

    Manage resources

  4. Click Create a new resource. Create a building first, then create rooms.

    Create new resource

  5. Add the details for your resource and click Add Resource.

    • For a meeting room, the Type field must be set to Room (or room). Any other value will prevent Humly Control Panel from importing the resource.
    • For a desk resource, set the type to desk.
    • For a parking space, set the type to parking_space.
    Add resource details

Grant Humly Admin User API Permissions

To connect HCP to your Google tenant, you will need a Humly Admin email — a dedicated user who will be authenticated from HCP to Google during the initial setup wizard and will act as Global Admin in HCP. API permissions are only needed for this user.

  1. Go to Directory > Users and click on the user you want to use as the Humly Admin.

  2. Scroll down and press Admin roles and privileges.

    Admin roles and privileges

  3. Apply the necessary API permissions by selecting one of the default Google roles: Super admin, Groups Admin, User Management Admin or Help Desk Admin. If you need a more restricted role, follow step 4–6 below to create a custom role.

    Apply default Google role

  4. To create a custom admin role, go to Account > Admin roles and press Create new role.

    Create new admin role

  5. Give the role a name and click Next. Scroll down to Admin API privileges, select Read under Users. That is the only permission needed. Click Continue.

    Set Admin API read privilege

  6. Apply the newly created admin role to your Humly Admin user.

Note: We strongly recommend creating a dedicated user specifically for Humly as the Admin email, rather than using a super admin account, to avoid potential issues in the future.

Grant Service Account and Humly Admin User Permissions to Resources

  1. Go to Google Calendar. In the side menu next to Other calendars, press the + icon and browse for your newly created resource. Click the checkbox to add it.

    Add resource to calendar

  2. Select the newly created resource calendar from My Calendar list, click the three-dot menu icon and select Settings and Sharing.

    Settings and Sharing for resource calendar

  3. Scroll down to Share with specific people or groups and click Add people and groups.

    Share with specific people

  4. Add the service account with the permission set to See only free/busy.

  5. Add the Humly Admin user with the permission Make changes to events or Make changes and manage sharing.

    Grant Humly Admin user permissions

  6. Log in to Gmail with the Humly Admin account and accept the sharing invitation by adding the resource to your own calendar.

    Accept calendar sharing invitation

  7. Repeat the previous steps for all resources in the project.

Note: It may take up to 72 hours for changes to be applied in Google Workspace. See also: Google's documentation on calendar sharing.

Important: The Humly Admin user must accept the shared resource by adding it to their own calendar (step 6 above). The resource will fail to import into Humly Control Panel otherwise.

You should now be able to proceed to step 2 – installing the Humly Control Panel.

Best Practices

  • Use a dedicated Humly Admin account. Avoid using a personal super admin account as the Humly Admin email. A dedicated account makes it easier to manage permissions and avoids disruptions if the personal account changes.
  • Use JSON keys for new setups on HCP 2.3+. P12 keys are not supported for new connections on HCP version 2.3 and later. Always create a JSON key for new setups.
  • Store the service account key securely. The downloaded JSON (or P12) file is sensitive. Store it in a secure location and do not share it unnecessarily.
  • Set resource types correctly from the start. Rooms must be typed as Room, desks as desk and parking spaces as parking_space. Incorrect types cannot be imported by HCP and require correction in Google Admin before retrying.
  • Accept the calendar sharing invitation promptly. The Humly Admin user must accept the resource sharing invitation before HCP can import the resource. Without this acceptance the import will fail.
  • Allow time for changes to propagate. Google Workspace changes can take up to 72 hours to fully apply. If the integration does not work immediately after setup, wait and retry before troubleshooting.

Troubleshooting

Resources do not appear in HCP during import

  • Verify that the resource Type is set to exactly Room, desk or parking_space in Google Admin. Any other value will prevent HCP from recognising the resource.
  • Confirm that the Humly Admin user has accepted the calendar sharing invitation and that the resource appears in their calendar.
  • Check that the service account has been granted See only free/busy access to the resource calendar.
  • Wait up to 72 hours after making changes in Google Workspace before retrying the import.

Authentication fails when connecting HCP to Google Workspace

  • If you are on HCP 2.3 or later, ensure you are using a JSON key and not a P12 key. P12 keys are not supported for new connections on HCP 2.3+.
  • Verify that the service account email and Client ID are correct and match what was created in Google Cloud Platform.
  • Ensure that Domain Wide Delegation has been configured with all required OAuth scopes.
  • Check that the service account has the Service Account Token Creator role assigned.

Bookings created in HCP do not appear in Google Calendar

  • Confirm that the Humly Admin user has Make changes to events or Make changes and manage sharing permission on the resource calendar.
  • Verify that the Gmail API and Google Calendar API are enabled in Google Cloud Platform for the project.
  • Check that all required OAuth scopes are present under Domain Wide Delegation.

The service account key has expired or been revoked

  • Go to IAM & Admin > Service Accounts in Google Cloud Platform, select the service account, click Keys and create a new key.
  • For HCP 2.3 and later, create a JSON key. For older versions, create a P12 key.
  • Update the key in HCP under Settings > Global Settings > Booking System.