On-Call Optimizer relies on external calendars to provide availability information for each member of an on-call schedule.
This is the multi-page printable view of this section. Click here to print.
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.
- Select
Calendars
from the side bar - 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:
- 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
- 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.
Authorization when re-connecting a calendar
If you have previously authorized On-Call Optimizer to access your calendar you may find that you are immediately taken to step 3 below without requiring any additional configuration or authorization steps.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.
- For each calendar use the select box to configure whether and how availability information will be imported from it.
- 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
- Select
Calendars
from the side bar - 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
- 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.
- 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:
- Select
Calendars
from the side bar - From the list of available connections click the
Disconnect
icon at the bottom of the connection you wish to remove.
OAuth permissions
Disconnecting a calendar in On-Call Optimizer will delete all credentials to the calendar held by On-Call Optimizer and prevent any further attempts to read the calendar by On-Call Optimizer, however the OAuth grant of permissions remains in place on the Google side even though it can no longer by utilized by On-Call Optimizer.
For completeness you may want to also visit your Google Account Connections Page and revoke any permissions grants for On-Call Optimizer.
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:
- Select
Calendars
from the side bar - From the list of available connections click the
Disconnect
icon at the bottom of the connection you wish to remove.
OAuth permissions
Disconnecting a calendar in this way will delete all credentials to the calendar held by On-Call Optimizer and prevent any further attempts to read the calendar by On-Call Optimizer, but the OAuth grant of permissions remains in place on the Microsoft side even though it can no longer by utilized by On-Call Optimizer.
For completeness you may want to also visit one of the following pages and revoke any permissions grants for On-Call Optimizer:
- My account consent page - for consumer/live.com accounts.
- My apps pages - for work accounts.
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:
- Select
Calendars
from the side bar - 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:
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.