Calendar Integration

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

1 - Connect a calendar product

To establish a connection between On-Call Optimizer and a supported calendar product 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 connection 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 product

Click on the button corresponding to the row of the calendar product you wish to connect to. After selecting a product you will either be:

1. Redirected to the website of your calendar product (e.g. Google, Outlook) and asked to grant On-Call Optimizer the necessary permissions to read your calendars. OR
2. Prompted to enter the configuration details required to connect to your calendar (e.g. ICS URL).

Complete the authorization process provided by the calendar product, or supply the requested configuration details to continue.

3. Configure which calendars to import

Once you have completed the authorization and/or configuration process On-Call Optimizer will validate that it can successfully access the new calendar connection.

If On-Call Optimizer can successfully access the configured calendar product, you will be shown a list of calendars that are available to configure as sources for availability information.

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

Finish

Once you cilck Save, 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.

Any imported availability information will be visible on your home page once the import process is complete.

2 - Configuration

Once you have established a connection between On-Call Optimizer and a calendar product you have the ability to customize which calendars available via the product are scanned for availability information to import.

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 toggle button in each row to select whether or not to use each of the 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

When a calendar is deselected, or the connection is disconnected, any availability information previously imported from that calendar is removed and will not be used in future assignments.

Previous assignments are not affected by the removal or deselection of a calendar and any availability information used in the assignment of shifts will remain visible in the display history for the assignment.

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, turn-off the toggle button for that calendar in the corresponding row of the configuration for that connection. You can also disconnect a calendar product entirely from On-Call Optimizer which will remove all events that were imported from calendars provided by that connection.

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.

5.3 - iCalendar

On-Call Optimizer supports the import of availability information from one any calendaring product that is able to provide a web-accessible iCalendar feed.

Connection Process

To add an ICS feed to your On-Call Optimizer account follow the connection instructions and click the Add ICS URL button.

Disconnecting

To remove an ICS feed:

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.

Supported Products

On-Call Optimizer’s ICS support is compliant with the RFC 5545 specification and should work with any calendar product producing a valid iCalendar feed in this format. On-Call Optimizer has been specifically tested with ICS feeds generated by the following products:

• Google Calendar
• Microsoft Outlook

Required Permissions and Data

The URL provided to On-Call Optimizer must not required authentication.

Data accessed

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