Outlook Calendar Integration Overview

Summary of Ripple’s Integration with Outlook Calendar

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

Functionality of Outlook Calendar

Ripple’s Outlook Calendar integration allows you to use all of the Outlook Calendar functionality you currently enjoy and link appointments in Outlook with your scheduled events in Ripple! This eliminates the need to keep separate Outlook and Ripple study calendars.  Having this integration helps to keep your appointments on track. In this article, we will discuss how to use specific Outlook features to manage your Ripple Events, but for an introduction or to brush up on Outlook Calendar functions can be found Here.

Setting Up Your Integration

Before Integrating

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

• A web browser compatible with Outlook Calendar and 3rd party authorizations. All common browsers support this functionality, including Chrome, Edge, and Firefox.

• An Outlook 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 Outlook 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 by following this link.

• A separate calendar within the Outlook account for each study you have in Ripple, as shown below.

• To make new calendars, click the New Items button in the top left corner of the Outlook calendar tab and select Add Folder (Adding a folder while in the calendar tab will create a new calendar instead of a mail folder): 

Getting Started

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

1. Link the selected Outlook 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 Outlook 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 Outlook’s log-in portal: 

3. Confirm study calendar integration. Once you have connected Ripple and Outlook, you will see all of your available Outlook Calendars in Ripple and 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 Outlook 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 by following this link.

Once you have set-up 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:

Using Event Identifiers

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

When typing in Outlook, the proper format is: [event identifier]. For example, [V2All] for an event identifier of V2All in Ripple 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. Follow this link to read more about how to schedule linked events.

Using Custom IDs

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

When typing in Outlook, 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. Follow this link to read more about how to schedule linked events.

Third Party Activity Log

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

This includes:

• New events being created

• Events being rescheduled or canceled

• Error messages when events are not synced correctly

When events are not created or updated properly, a log entry will be made in the 3rd Party Activity Log to indicate the issue occurring.

Common 3rd Party Activity Log Error Messages

• 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 has multiple events of the 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 Scheduling Mistakes

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

• 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 Outlook Calendar account. This must be done when adding or removing an Outlook Calendar.