Authentication
After installing the app, users will need to authorize the app to sync with an existing Google Calendar account in order to retrieve calendar data. By clicking the Link to Google Calendar button from the Settings tab of the app, users will be prompted to authenticate using a Google account they’ve recently signed in with. After selecting the account used for authentication, they will be prompted to grant the app access to:
View and edit events on all of their calendars.
See, edit, share, and permanently delete all the calendars you can access using Google Calendar.
Please note that all of these permissions aren’t actually utilized by the application upon installation, and the integration will not share calendar or event data in Google Calendar. The integration will only edit and delete calendar data if the district has enabled write-back functionality for the app.
After clicking Allow, users will then be prompted to select one of the calendars read from the authenticated Google account. Only one calendar is supported to sync at a time.
After selecting a calendar, select Save. There are additional options available:
Sync Error Email Recipients: This option allows district Admins and Agents to receive notifications for any sync errors that prevent events from being created for Locations and Rooms for which the district has enabled sync error notifications for.
Please see the section below for details on email frequency and email copy for these error emails.
Import Past Events: When this option is enabled, the app will sync the most recent 999 events that took place in the past.
Ignore Availability Rules: override the availability setting for all rooms and locations.
Double Booking Settings
The following field will be available only to users with the Double Book Events permission option enabled.
The Double Booking dropdown offers three options for handling double-booked events.
Block all incoming events that conflict with existing events in iiQ: When syncing events via Google or MS Calendar integrations, all double-booked events will be blocked and not created.
Set all incoming events to “approved” and allow overlap with existing events: Syncing events via Google or MS Calendar integrations will create all double-booked events with the ‘Approved’ status.
If the existing event is updated in the external Calendar and the update creates a new conflict, the sync in iiQ will update the event. The event status will remain ‘Approved’.
Set all incoming events to “conflict pending” and allow overlap with existing events. Conflicted events will need approval: When syncing events via Google or MS Calendar integrations, all double-booked events will be created with a ‘Conflict Pending’ status and will require approval. You can go to the event and change the status from ‘Conflict Pending’ to ‘Approved’.
If an event with the status ‘Conflict Pending’ from an external calendar was created in iiQ during a previous sync, the following rules apply:
Title or Description Change: If the event's title or description has been updated in the external calendar but the room, location, date, or time have not changed, the event status in iiQ will not change. It will remain ‘Conflict Pending’ during the sync update.
Room, Location, Date, or Time Change with Ongoing Conflict: If the event's room, location, date, or time has been updated in the external calendar and there is still a conflict with another event, the status will remain ‘Conflict Pending’. This allows the user to review the new conflict.
Room, Location, Date, or Time Change without Conflict: If the event's room, location, date, or time has been updated in the external calendar and there is no longer a conflict, the status will still be ‘Conflict Pending’. However, the user can manually change the status to ‘Approved’ within the event details.
If a non-conflicting event from an external Calendar was previously created with the ‘Approved’ status in iiQ in a previous sync,
If that event’s room, location, date, or time was updated in the external calendar and created a conflict with an existing event, the event status in iiQ will be changed to ‘Conflict Pending’ so the user can review the new conflict.
If that event's room, location, date, or time has been updated in the external Calendar, AND there is no conflict with another event, the event status will remain ‘Approved’.
You can manually change an event’s status from ‘Approved’ to ‘Conflict Pending’, even without a technical scheduling conflict. You can create entirely new events with the ‘Conflict Pending’ status. Doing so effectively “locks” the time slot, ensuring that any subsequent events scheduled during the same time will also be assigned the Conflict Pending status until reviewed and resolved.
The Double Booking Email Recipients section allows you to select recipients to receive an email when double-booked events are synced into iiQ.
Based on the Double Booking setting selection, the Double Booking Email Recipients may receive either a Conflict Pending email or an Approved email. This will be based on whether double-booked events will be created in the Conflict Pending status or whether a double-booked event will be auto-approved.
Conflict Pending Email
Approved Email
The email will contain a Summary section explaining the event conflict, a Status section showing ‘Conflict Pending’ or ‘Approved’ status, and a list of double-booked events showing the title, date, and time range for each. Up to 10 double-booked events will be displayed in the email. If there are more than 10 double-booked events, the user should use the button at the bottom of the email ‘View upcoming events in iiQ’ to log into iiQ to view the additional double-booked events.
Write-Backs Capabilities
Two use cases are supported with write-back functionality for the Google Calendar integration. When either of these options are enabled, any events synced from Google Calendar should become editable within iiQ. There are no special permissions associated with this functionality, and any user with access to edit or manage events in iiQ can also push changes to Google Calendar by updating the event in iiQ.
Edit Google Calendar events in iiQ - When enabled, this setting will allow the integration to automatically create new events in Google Calendar as they are created in iiQ.
Enable iiQ events to Google Calendar write-backs - When enabled, this setting will allow the integration to update existing events in Google Calendar as changes are made to them in iiQ.
After saving next, you will need to run a sync and then go map the locations. Navigate to the locations mapping tab.
Calendar integrations will not sync events that do not have mapped locations or rooms. This rule ensures that no rooms are missed during the syncing process. To map locations and rooms, use the Resource Mapping tab.
Sync Error Recipients
This option allows district Admins and Agents to receive notifications for any sync errors that prevent events from being created. Notification preferences are managed on the Location Mappings tab of the app settings page.
Email Frequency: These notifications are triggered on a daily basis as the app “syncs” with Google Calendar to process updates or new events. If there aren’t any sync errors encountered with the most recent sync, these notifications will not be sent.
Email copy: A screenshot is included below of the email notification copy. This notification will include a recap of all errors encountered This will include scenarios where the district has subscribed to notifications for a particular location and room, but an event couldn’t be created at the mapped location and room in iiQ due to:
the location or room being unavailable at the time of the event due to another event already being scheduled at the room and location during the time of the event being imported from Google Calendar.
the availability settings for the mapped Room or Location in iiQ, not including the time of the event on the day that it occurs
If the email contains updates that aren’t pertinent information to the district admin, they are encouraged to either:
Update the availability of the Room to include the time of the event
Resolve the double-booking of that Room within Google Calendar or in iiQ (IE reschedule one of the events in their source system).
Disable notifications for the Site or Sub-site the event is associated with in Google Calendar.
Location Mappings
After authenticating with your Google calendar, you will need to run a Sync. This will sync all unique location values currently included for all events in the selected calendar.
Please note that any events without a value in the event location field in Google will automatically be excluded from the sync, as Location and Room are required fields for event creation in iiQ.
As users are completing mappings, the row will be highlighted in grey. Admins can also search this page using the search bar at the top of the page to quickly find Location values and room values being pulled from Google Calendar for quicker mapping.
Below describes each column on the location mapping tab:
Google Event Location Column
Values contained in the location field for an event in Google Calendar are listed here.
Google Event Room
Rooms or “resources” as defined in Google associated with an event will be included in this mapping column for events synced from Google Calendar. Please note that rooms or resources are defined by a district’s Google admin and cannot capture free-form text.
Maps to iiQ Location/Room
Admins can use these columns to map values for event locations in Google Calendar to the corresponding Location and Room number for the event in iiQ. These fields are required for event creation, and any missing mappings in this column will result in the events being skipped during the sync, resulting in no events being created for that location in iiQ.
After selecting an iiQ Location for mapping, the select menu included in the “Maps to iiQ Room” column will populate with a list of room numbers at the selected iiQ Location.
Sync/Pause
Admins have the ability to “pause” syncs for locations and rooms as needed by using the “pause” or “sync” option included next to the mapping. These buttons function similarly to the “play” button included in most media player interfaces, and the button reflects the opposite of the status a location/room is currently in. Therefore, if a user sees “pause” next to the location’s mapping, that means the location is currently syncing and they can click this option to “pause” the sync.
Sync/Pause is also supported in bulk by selecting the option included at the top of this column.
Notifications
The notifications column only applies to the sync error notifications for this integration and has no effect on a ticket or event-related notifications that are supported elsewhere throughout the iiQ platform. By “muting” notifications for a specific location from this interface, users are indicating that they do not wish to receive error notifications for this location.
Syncs
Syncs occur every hour for this integration. Manual syncs can also be initiated via the “sync” button included in the upper-right-hand corner of the page.
Calendar integrations will not sync events that do not have mapped locations or rooms. This rule ensures that no rooms are missed during the syncing process. To map locations and rooms, use the Resource Mapping tab.
Resource Mappings
The resource mappings tab allows users to map any configured resource values from Google Calendar to Locations and Rooms in iiQ for a cleaner mapping process. Mappings contained in this tab will take priority over location mappings for any events that utilize a Google Calendar resource.
On the left side of this page, Admins will see a full list of any “building” resource types from their district’s instance of Google Calendar, regardless if they are associated with events that the integration is currently reading from Google Calendar. Buildings can be searched for via the search bar in the top-left corner of this tab.
After selecting a building from the left, Admins will then be prompted to map this building to a location in iiQ. This mapping tailors the list of mappable rooms included in the select menus only to include room values at that particular location. If a district does not wish to import any events that are associated with any given resource, they can “pause” the sync for that building resource and disable error notifications at the building level.
Once the building has been mapped to a location in iiQ, Admins will then need to map room resources from Google to a room in iiQ. Rooms can also be searched via the search bar included on the page of their corresponding building resource. If an admin does not wish to create events associated with any room resources in Google, they can “pause” the sync for that room and mute any error notifications to prevent any events that utilize that room resource in Google Calendar from being imported to iiQ and from being included in the sync error notifications.
It’s recommended that districts use this mapping tab for mapping locations for Google Calendar events as:
This tab will populate all resources associated with the district’s instance of Google Calendar instead of a list of text values read from the first 999 events iiQ syncs from Google Calendar, which reduces the volume of mappings needed to create events successfully and reduces the need for districts to map location values as new locations are discovered continuously.
Buildings resources > Room resources are 1:1 match for Locations and Rooms in iiQ, which are required fields for event creation.
Event Mapping
During the Event Mapping process, you can specify a Default Event Type for events. This Default Event Type will be set to all events pulled in from the Calendar integration. This field is automatically set to the event type of Other.
There must be a default mapping in place for the event to be created.
If a user chooses to set the dropdown to no default value, only the events that match the chosen Regex mappings will be synced.
If the dropdown is set to nothing and no regex mappings are added, no events will sync into iiQ
To map specific events to corresponding event types, expand the Event Regex Mapping section. Access the Event Regex Mapping by clicking the small arrow to reveal a drop-down menu.
First, select the Event Type you want to map. Next in the Regex Mapping field enter the expression that you want to map to this Event Type. This field is looking at the Events Title.
Anything event that does not match the Regex Mapping will be set to the Default Event Type set above.
Mappings will be evaluated in the order provided.
Regex Mapping - A regular expression is a sequence of characters that specifies a match pattern in text. You can think of regular expressions as wildcards on steroids.
When the sync process is done successfully, the events on the Calendar will show as a specific type on the Events Details page.
Sync History Tab
This tab allows you to look up the data for any sync between Google Calendar and Incident IQ. Every sync, whether completed successfully or not, is logged for reference purposes and available for review. After selecting this tab, a list of past syncs will be included on the left. After selecting a specific sync from the list located on the left-hand side of the screen, district admins can expand sync details for that sync on the right side of the page.
Sync history details will include a log for every event read from the synced Google Calendar that reflects the sync status of each event. District admins can also search for specific events or filter them by a particular status.
Sync Statuses for Events
Create: New events being created within a given sync will be logged with this status.
Error: Events that are unable to be created for any reason will be logged with this status. Majority of the time this will be a result of a missing location or room mapping.
Skip: Events that are skipped due to no changes detected will be logged with this sync status.
Update: Events that are updated (either date, time, location, description, or name) will be logged with this sync status.
Delete: Events being deleted due to being removed in source system will be logged with this sync status.
Events Tab
After selecting a specific event from a sync history log, a user will be directed to view that event in the Events tab of the Google Calendar app. Event records can also be searched by their event ID or their name after navigating to this tab. After selecting or searching for a specific event, admins will be able to view the following details for each event as captured in the most recent sync with Google Calendar (within the last hour):
Event Title and Event ID
Start Date/Time
End Date/Time
Event Status
Event Notes
---
Hannah Bailey - Director, Customer Engagement