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 use the select box to configure whether and how availability information will be imported 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 are scanned for availability information and choose how it is imported.

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 select box in each row to choose how events on each calendar will be imported as availability information from one of the following options:

Ignore all events

On-Call Optimizer will not process or import any events on this calendar.

Create from matching events

On-Call Optimizer will import only matching events, and will use the event type or tags (e.g. no-oncall, 'prefer-oncall) to select the action for the created availability information.

Block all events

On-Call Optimizer will import every event as availability information with a block action.

Prefer all events

On-Call Optimizer will import every event as availability information with a prefer action.

Default behavior

By default only the primary personal calendar associated with the account connecting the calendar to On-Call Optimizer is selected and will be configured to Create from matching events.

All other calendars available on the connection are ignored by default but can be enabled and configured as desired once the connection is established.

3 - Availability Information

Availability information is created by matching events on the calendars that have been connected to your account and configured for import.

Each piece of availability information is described by:

• The member to whom it relates.
• A start time.
• An end time.
• An action (prefer, or block).
  • Block actions cause On-Call Optimizer to avoid assigning any shifts to the member between the start and end times.
  • Prefer actions allow members to hint to On-Call Optimizer that they would prefer to be assigned shifts between the start and end times.

Creating availability information

Availability information is created from each event found on a configured calendar after it passes initial filters and when either:

• The event type indicates the event represents unavailability, OR
• The title or description contains one of the recognized tags.

Events which do not match on type or tag are completely ignored.

Event types indicating unavailability

Events of the following types on a configured calendar will always be matched, and will result in availability information being created with a block action:

• Out of office
• Holiday

Events matched by type do not perform further tag matching. Events of a matching type will always result in availability information with a block action in On-Call Optimizer. It is not possible to create availability information with a prefer action from an event matched by type.

Tag matching

Events containing one or more of the following tags in the title or description, will result in availability information with the corresponding action being created.

Recognized tags to create an availability block

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

Recognized tags to create an availability preference

• prefer oncall
• prefer-oncall

Block actions will always take precedence over prefer actions where multiple tags are found on a single event, or when multiple different events with different action tags are present with overlapping times.

Availability weighting

Availability events for each user are used in shift assignment when any minute of an availability event overlaps with any minute of the shift. Each event overlapping with a shift contributes a score to the optimization algorithm’s consideration of how optimal it would be to assign that shift to the user.

The score for each event is calculated starting from a base value determined by the action associated with the event, which is then weighted against how much of the of the overall shift duration the event overlaps with using a linear calculation:

• An event that overlaps with every minute of a shift will have a final weighted score the same as the base score for the event action.
• An event overlapping with half the minutes will result in a final weighted score that is 50% of the base score.
• An event overlapping for only a small number of minutes might result in a final weighted score that contributes only a very small score. (e.g. for a 24-hour shift containing 1440 minutes, any overlap less than 14 minutes will contribute less than 1% of the base score).

The effect is that the assignment algorithm will block or prefer a shift for a user with availability information that overlaps any portion of the shift when no other constraints exist - even in the case of very short overlaps. However, when resolving overlaps between availability information between users, or addressing prior imbalances in the schedule, availability events that overlap more of a shift will have more influence than those that only overlap a small portion of the shift.

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’s primary store as soon as the end time of the event is in the past.

A copy of the availability information used in each assignment of shifts is stored in the logs providing the history of each assignment event until the assignment event expires from On-Call Optimizer based on retention duration of the organization’s plan.

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 sourced from a specific calendar, change the event behaviour option for that calendar in the corresponding row of the configuration for that connection to Ignore all events. 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 minimizes the amount of information processed using filtering, matching and storing the minimum details required.

Initial Filters

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 be organized, or accepted by the user importing the calendar as described below, AND
   • The event must occur within 90 days of the present date.

Any event not matching both criteria is ignored and not processed further. On-Call Optimizer does not store any details of these events.

Event ownership and acceptance

Only events that are either organized or explicitly accepted by the authenticated user 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.

Event Matching

Events passing the initial filter are only imported when either:

• The event type indicates the event represents unavailability, OR
• The title or description contains one of the recognized tags.

Refer to the availability information documentation for further details on how the matching process works.

Imported Data

Calendar events which make it through the filtering and matching process are imported into On-Call Optimizer’s database.

Imported events are stored as 4 pieces of information:

• The member to whom it relates.
• The start time.
• The end time.
• An action (prefer, or block).

On-Call Optimizer does not store any of the textual details of the event (e.g. the title or description), nor any information about the invitees or participants.

On-Call Optimizer does not store any details of events on calendars not selected for import, or which did not pass the filter or matching stages.

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.