Calendar Integration

• 1: Connect a calendar provider
• 2: Configuration
• 3: Availability Information
• 4: Event Filtering
• 5: Supported Calendars
• 5.1: Google Calendar
• 5.2: Microsoft Outlook

1 - Connect a calendar provider

To establish a connection between On-Call Optimizer and a supported calendar provider follow these steps.

1. Login to On-Call Optimizer and navigate to the Calendars section.

1. Select Calendars from the side bar
2. From the Calendars page, select Add a new calendar provider at the bottom of the page.

After following these steps you should be at https://app.oncall-optimizer.com/calendar_connections/new and be able to see the logo of your Calendar on screen.

2. Select your calendar provider and provide authorization

1. Click on the connect button under the logo of the calendar provider you wish to connect to.
2. You will be redirected to the website of your calendar provider and asked to grant On-Call Optimizer the necessary permissions to read your calendars.
3. Follow the instructions and grant the requested permissions.

3. Configure which calendars to import

Once you have completed the authorization process you will be redirected back to On-Call Optimizer and shown a list of calendars that are available to configure as sources for availability information.

1. For each calendar in the list choose whether or not to import availability information from it.
2. Click Finish at the bottom of the list.

Refer to the configuration documentation for more detailed information on the options available in this step.

Finish

Once you cilck Finish, the process of importing availability information will begin in the background and may take a few minutes to complete.

You can view the status of the import for each calendar on the main Calendars page accessible via the Calendars entry in the side bar at any time.

2 - Configuration

Once you have established a connection between On-Call Optimizer and a calendar provider you have the ability to customize which calendars available at the provider are scanned for availability information to import, and how previously imported availability information will be handled if and when the calendar is disconnected.

Accessing calendar configuration

1. Select Calendars from the side bar
2. From the list of available connections click the Edit icon at the bottom of the connection you wish to configured.

Calendar selection

Use the drop-down selector in each row to select whether or not to use each of the accessible calendars as a source of availability information.

When selected, each calendar is regularly checked for any matching availability events and the results are cached for use in future assignments and swaps.

Calendars which are not selected for use are completely ignored by the import process and no information about their events is read or accessed by On-Call Optimizer.

By default only the primary personal calendar associated with the account connecting the calendar to On-Call Optimizer is selected and all other calendars are ignored. Once the connection is established any of the accessible calendars can then be enabled as desired.

Event retention

The Retain Availability setting for each calendar controls what happens to previously imported availability information when the calendar is disconnected, or deselected.

By default this setting is enabled, which results in any previously imported availability information being kept in On-Call Optimizer when the calendar is disconnected or deselected.

If you choose to disable this setting for any calendar, all previously imported availability information will instead be removed when the calendar is disconnected or deselected.

Previously assigned shifts are not affected by operation of the Retain Availability setting, and any availability information previously used in creating an assignment remains visible in the history of that assignment even after the calendar is disconnected or deselected.

3 - Availability Information

Availability information enables On-Call Optimizer to assign on-call shifts around the existing commitments in the life of each team member.

Availability information is imported from the calendars that have been connected to your account and configured for import.

Each piece of availability information consists of the following attributes:

• The member to whom it relates.
• The start time.
• The end time.
• An action (prefer, or block).
• Descriptive details (title & summary).

Availability blocks

Block actions prevent On-Call Optimizer from assigning any shifts to the named member between the start and end times.

Blocks are created for any holiday or out of office event types and can also be triggered using one of the following strings in the title or description of an event:

• not oncall
• no oncall
• not-oncall
• no-oncall
• noc

Availability preferences

Prefer actions allow members to hint to On-Call Optimizer that they would prefer to be assigned shifts between the start and end times.

Preferences must be manually triggered using one of the following strings in the title or description of an event:

• prefer oncall
• prefer-oncall

Event ownership and acceptance

Only events that are either organized or explicitly accepted by you are processed as sources of availability information.

Events created by other users which appear on a calendar (e.g. because you have been invited to participate in the event), will be ignored by On-Call Optimizer until you accept the event on the calendar. This check is in place to prevent any user with the permissions to place invited events on your calendar from being able to create availability information for you.

These rules are also applied if you configure a team or shared calendar which you have access to as a source of availabilty information in your On-Call Optimizer account. Only those events on the shared calendar which you have directly organized, or explicitly accepted will be imported as availability information for you in On-Call Optimizer.

Availability Lifecycle

New availability information is imported to On-Call Optimizer from configured calendars on a regular basis to cover the time period from the present time until 90 days in the future. Any previously imported availability information that has been removed or updated in the source calendar will also be removed or updated as necessary in On-Call Optimizer.

Availability information will expire and be removed from On-Call Optimizer once the end time of the event is in the past, however any such information that was used for assignment of shifts will remain available in the history attached to the assignment event record even after it has expired from On-Call Optimizer’s cache of upcoming availability information.

Removing availability information

Individual events in the future

To remove availability information for a future time from On-Call Optimizer, update or remove the calendar event that the information is sourced from (e.g. remove the associated holiday or out of office event, or update the event title or description to remove any no-oncall or similar tags).

On-Call Optimizer will detect the changes on the next refresh, or you can trigger an immediate refresh on the main Calendars page.

All future events sourced from a specific calendar

To remove all upcoming availability events sources from a specific calendar, disable the retain availability configuration setting and then deselect, or disconnect the calendar from On-Call Optimizer.

Future events retained from a previously disconnected or deslected calendar

Retained entries for calendars which are no longer connected to On-Call Optimizer can be manually removed by clicking the red cross to the right of the entry.

More Information

For further details on how availability information is used in shift assignment, refer to the algorithm details documentation.

4 - Event Filtering

Calendar data is sensitive and often contains personal details. On-Call Optimizer is designed and built to minimize the amount of information processed and retained using the following filtering principles:

1. On-Call Optimizer only requests event details for those calendars which have been specifically enabled.
   • Event details on other calendars will not be read or accessed by On-Call Optimizer even if access to them is incidentally available.
2. When processing events on configured calendars On-Call Optimizer filters events using the following set of criteria
   • The event must occur within 90 days of the present date, AND
   • The event must be organized, or accepted by the user importing the calendar, AND
   • The event must be an “Out of Office” or “Holiday” event type, OR
   • The event must contain an exact match for at least one of the strings listed in the availability block or availability preference definitions (e.g. no-oncall, 'prefer-oncall)
3. Any events not matching the filter criteria are ignored. No data or information about them is retained by On-Call Optimizer.
4. For events matching the filter criteria, On-Call Optimizer stores only the 5 pieces of availability information.

5 - Supported Calendars

On-Call Optimizer supports the import of availability information from the products listed below.

If the calendar you use is not shown, please get in touch, and we will see if support can be added.

5.1 - Google Calendar

On-Call Optimizer supports the import of availability information from one or more Google calendars.

Connection Process

To link a Google Calendar to your On-Call Optimizer account follow the connection instructions and click the Connect Google button.

You can connect any number of Google calendars (e.g. work and personal) to a single On-Call Optimizer account so long as you have permission to log-in and complete the authorization process with each Google account.

Updating calendar selection

You can change or update which of the accessible calendars will be used as a source of availability information following the instructions for calendar configuration.

Disconnecting

To remove a Google Calendar connection:

1. Select Calendars from the side bar
2. From the list of available connections click the Disconnect icon at the bottom of the connection you wish to remove.

Required Permissions and Data

On-Call Optimizer uses the minimum possible set of OAuth permissions and takes steps to minimize the amount of calendar data accessed and stored.

OAuth scopes requested

• https://www.googleapis.com/auth/calendar.readonly
  • Used to retrieve the list of available calendars to allow you to select which calendars On-Call Optimizer should process.
  • Used to read event information from selected calendars to match to your availability preferences.

Data accessed

On-Call Optimizer filters events to minimize the amount of information processed and retained.

5.2 - Microsoft Outlook

On-Call Optimizer supports the import of availability information from one or more Outlook calendars.

Connection Process

To link an Outlook Calendar to your On-Call Optimizer account follow the connection instructions and click the Connect Outlook button.

You can connect any number of Outlook calendars (e.g. work and personal) to a single On-Call Optimizer account so long as you have permission to log-in and complete the authorization process with each Microsoft account.

Updating calendar selection

You can change or update which of the accessible calendars will be used as a source of availability information following the instructions for calendar configuration.

Disconnecting

To remove an Outlook Calendar connection:

1. Select Calendars from the side bar
2. From the list of available connections click the Disconnect icon at the bottom of the connection you wish to remove.

Required Permissions and Data

On-Call Optimizer uses the minimum possible set of OAuth permissions and takes steps to minimize the amount of calendar data accessed and stored.

OAuth scopes requested

• Calendars.Read
  • Used to retrieve the list of available calendars to allow you to select which calendars On-Call Optimizer should process.
  • Used to read event information from selected calendars to match to your availability preferences.

Data accessed

On-Call Optimizer filters all accessed events and only retains the description and start/end time details for matched events. No other calendar data is retained or stored.