Google Calendar Integration Overview

Overview of Ripple’s Integration with Google Calendar

Ripple features the ability to sync scheduled Ripple Events with a selected Google Calendar allowing you to seamlessly manage participant scheduling. Scheduling participants, updating event information, and editing the description are completed within Google and automatically reflected in Ripple’s Events and study calendars.

Functionality of Google Calendar

Ripple’s Google Calendar integration allows you to use all of the Google Calendar functionality you currently enjoy and link appointments in Google with your  scheduled events in Ripple! This eliminates the need to keep a separate Google and Ripple study calendars.  Having this integration helps to keep your appointments on track.

In this article we will discuss how to use specific Google features to manage your Ripple Events, but an introduction or to brush up on Google Calendar functions can be found Here.

Setting Up Your Integration

Before Integrating

Before setting up your Google Calendar integration, ensure that your team has the following:

• A web browser compatible with Google Calendar and 3rd party authorizations. All common browsers support this functionality, including Chrome, Edge, and Firefox.
• A Google account that will be used to create study calendars that are shared with all users who will be scheduling and managing events and appointments. This can be an individual Google account (e.g., the PI or Site Administrator account) or an account fully dedicated to the study.
• Custom IDs to identify study participants. You can learn more about what a Custom ID is Here.
• A separate calendar within the Google account for each study you have in Ripple, as shown below.
• To make new calendars, click the plus (+) button next to Other calendars in Google: 

Getting Started 

Note: The Google Calendar integration set-up must be done by a Study Admin who has log-in access to the associated Google Calendar. 

To set-up your Google Calendar integration we recommend that you follow these steps:

1. Link the selected Google account. To start the set up, navigate to the Study Settings tab (green), then to the Scheduling section (red) to find the Study Calendar Integration page. Select Google from the drop-down list (purple):

2. Authorize access. You will be prompted to log in and allow Ripple permission to access your calendar through Google’s log-in portal:

3. Confirm study calendar integration. Once you have connected Ripple and Google, you will see all of your available Google Calendars in Ripple that you will now be able to link to your events in your study. This list will include your study calendars as well as any other calendars used on this account:

4. Link Google Calendars to Ripple Events. Navigate to the Events set-up section on the Study Settings page. If you have not already set-up Events for this study, pause the calendar integration process and set-up your study Events.  You can learn more about how to set-up and use Events Here.

Once you have setup study Events, select the correct study calendar that corresponds to the study the Event is in. In this example, I would select the Brain Imaging calendar from the drop-down list:

When you navigate back to the Study Calendar Integration section you should see the names of all of your study’s Events linked to the study calendar:

How Google and Ripple Calendars Interact

Using Event Identifiers

All Google Calendar events MUST include a unique event identifier inside brackets (that is customizable in the event’s settings) in the title or description of the Google event for it to properly link as the intended event type on the participant’s profile card.

When typing in Google, the proper format is: [event identifier]. For example, [V2All] for an event identifier of V2All for my sample event “Visit 2 - All”. This is the only accepted format to link to Ripple, as no other characters or spaces will be recognized. 

Using Custom IDs

All Google Calendar events MUST include a pound / hashtag sign (#) and the Custom ID of the participant in the title or description of the Google event for it to properly link to your participant in Ripple.

When typing in Google, the proper format is: #(Custom ID) with no spaces. For example, #2004 for a Custom ID of 2004 in Ripple. This is the only accepted format to link to Ripple, as no other characters or spaces will be recognized. Additionally, all participants must have a Custom ID in Ripple to be able to have events scheduled for them. 

Learn more about how to schedule linked Events Here. 

Third Party Activity Log

The Third Party Activity Log keeps a log of all changes to Ripple Events made using the Google Calendar.

This includes:

• New events being created
• Events being rescheduled or cancelled
• Error messages when events are not synced correctly

When events are not created or updated properly, a log entry will be made in the Activity Log to indicate the issue occurring. Common error messages and causes include:

• CustomId/attendee not found - The event title or description did not contain a customId identifier and no attendee email was found.
• Participant not found - The custom ID or attendee was found but does not match a participant for this study.
• Participant event not found - The participant was found but they have no event of this type to match.
• Event not found for calendarId: {XYZ} - There is no matching event for the syncing calendar and study. This could be due to lingering syncing issues if a calendar was recently removed from the integration.
• Participant multiple events of same type - There are two events of the same type for the same participant.  This implies the participant is double booked.
• All day events are not supported - You must set a time for the event

Common Errors

• Creating an Event with no Custom ID, a non-valid Custom ID, or improperly formatted Custom ID in the title or description - Event will not sync to Ripple and will only be visible in Google Calendar
• Creating an Event with two Custom IDs in the title and/or description - The Custom ID that appears first in the title when the event is created will be scheduled. The event will stay scheduled to this participant until their Custom ID is removed, even if the event title is changed with a different Custom ID appearing before it. Only one participant can be scheduled per event
• Scheduling the same Event multiple times for the same participant, i.e. two identical Events in Google Calendar for one Custom ID - The event that was created first will be reflected in Ripple. Note: The order of when the events occur does not apply
• Creating an all day event - Events are required to have a start and end time. All day Events are not supported.
• Creating identical events - In the event that two events of the same type are created for a participant, the event that was updated most recently will reflect in Ripple

Resolving Syncing Errors 

If your Google Calendar and Ripple Events are not syncing and you have identified it is not due to any of the common errors listed above.  You may need to refresh the integration by manually syncing the specific calendar or your connection with Google.  

• Manually sync the events on the calendar associated with the error (blue) - Click the sync icon either next to the specific calendar link to sync all events in that calendar.
• Manually sync all calendars in the integration (red) - Click the sync icon either next to the email associated with the Google Calendar account. This must also be done when adding or removing a Google Calendar.