Reference

• 1: Example configurations
• 1.1: Weekly Shift
• 1.2: Daily Shift
• 1.3: Business hours only shifts (schedule contains gaps)
• 1.4: Separate business and after-hours shifts (within team)
• 1.5: Separate business and after-hours shifts (delegated to a partner team)
• 1.6: Follow the sun (2 locations)
• 1.7: Follow the sun (multiple locations)
• 2: Constraint Optimizing Algorithm
• 3: Extension logic
• 4: Authentication and Authorization
• 5: Integration Points
• 6: Notifications
• 7: Organization Support

1 - Example configurations

Using basic and nested schedules, it is possible to create almost any configuration of on-call schedule that you require as demonstrated by the examples below.

If none of these examples meet your needs, and you need help creating a schedule to match your requirements, please get in touch.

1.1 - Weekly Shift

Shift Configuration Entries

Sample Assignment

2023-07-24 10:00 person2@example.com
2023-07-31 10:00 person3@example.com
2023-08-07 10:00 person1@example.com
2023-08-14 10:00 person3@example.com

Assignment Details

This configuration results in On-Call Optimizer balancing team members using a single shift type covering 7 days.

While this is a common rotation pattern for many teams, the full benefits of On-Call Optimizer will not be experienced in this configuration due to the limited number of shifts available to be matched to team member constraints and preferences.

It is recommended that you consider migrating to one of the later examples in the configuration library which provide more flexibility to schedule around team member constraints and preferences.

Return to the list of other examples

1.2 - Daily Shift

Shift Configuration Entries

Sample Assignment

2023-07-24 10:00 member2@example.com    # Mon
2023-07-25 10:00 member1@example.com    # Tue
2023-07-26 10:00 member3@example.com    # Wed
2023-07-27 10:00 member4@example.com    # Thu
2023-07-28 10:00 member3@example.com    # Fri
2023-07-29 10:00 member4@example.com    # Sat
2023-07-30 10:00 member1@example.com    # Sun
2023-07-31 10:00 member2@example.com    # Mon

Assignment Details

This configuration results in On-Call Optimizer balancing team members using a single shift type covering each 24 hour period, with no differentiation made between weekdays and weekends in the balancing process.

Typically each member should be assigned similar numbers of shifts for each different day of the week by the default behaviour of On-Call Optimizer’s algorithm, however if team members persistently block or prefer particular days (e.g. weekends) via their availability information, other members may find themselves consistently assigned to particular days of the week without any schedule imbalance arising.

Enforcing Weekday vs Weekend Balance

An alternative configuration that ensures all team members are assigned balanced weekday and weekend day shifts despite individual preferences would be:

This configuration results in On-Call Optimizer using two shift types for balancing purposes which contain:

1. All 24-hour duration shifts starting Mon-Fri.
2. All 24-hour duration shifts starting on Sat and Sun.

On-Call Optimizer aims for each member to have a balanced share of the shifts within each shift type.

Return to the list of other examples

1.3 - Business hours only shifts (schedule contains gaps)

In situations where out-of-hours coverage is not required, you can create a schedule which only assigns members during particular time periods, leaving gaps with no assignee(s) scheduled at all other times.

The following example demonstrates a shift configuration that will create shifts covering Mon-Fri 9am-5pm in the schedule’s time zone. No shift or assignee will be available outside those times.

Shift Configuration Entries

Sample Assignment

2023-07-24 09:00 person2@example.com    # Mon
# 2023-07-24 17:00 NO_ASSIGNEE
2023-07-25 09:00 person1@example.com    # Tue
# 2023-07-25 17:00 NO_ASSIGNEE
2023-07-26 09:00 person5@example.com    # Wed
# 2023-07-26 17:00 NO_ASSIGNEE
2023-07-27 09:00 person4@example.com    # Thu
# 2023-07-27 17:00 NO_ASSIGNEE
2023-07-28 09:00 person3@example.com    # Fri
# 2023-07-28 17:00 NO_ASSIGNEE
2023-07-31 09:00 person5@example.com    # Mon
# 2023-07-31 17:00 NO_ASSIGNEE

Assignment Details

This configuration results in On-Call Optimizer balancing team members using a single shift type covering each 8 hour period on Mon-Fri.

Return to the list of other examples

1.4 - Separate business and after-hours shifts (within team)

A common motivation for using a schedule configuration of this type would be to avoid having any team member scheduled for a consecutive 24hr period.

Shift Configuration Entries

Sample Assignment

2023-07-24 09:00 person2@example.com    # Mon
2023-07-24 17:00 person5@example.com
2023-07-25 09:00 person1@example.com    # Tue
2023-07-25 17:00 person4@example.com
2023-07-26 09:00 person5@example.com    # Wed
2023-07-26 17:00 person3@example.com
2023-07-27 09:00 person4@example.com    # Thu
2023-07-27 17:00 person2@example.com
2023-07-28 09:00 person3@example.com    # Fri
2023-07-28 17:00 person1@example.com
2023-07-29 09:00 person5@example.com    # Sat
2023-07-29 17:00 person2@example.com

Assignment Details

This configuration results in On-Call Optimizer balancing team members using two shift types which contain:

1. All 8-hour duration shifts starting 9am.
2. All 16-hour duration shifts starting 5pm.

On-Call Optimizer aims for each member to have a balanced share of the shifts within each shift type.

Return to the list of other examples

1.5 - Separate business and after-hours shifts (delegated to a partner team)

This schedule configuration is commonly used when two teams in different time-zones are able to provide coverage during different hours of the day.

Note how (unlike the basic after hours) example where every day of the week is treated the same, this example also demonstrates the use of the Weekdays wildcard in the shift configuration to achieve the result of having Saturday and Sunday also treated as after-hours and assigned to the partner team for the full 48-hour period.

Shift Configuration Entries

Sample Assignment for the main schedule

2023-07-24 09:00 person2@example.com    # Mon
2023-07-24 17:00 partner-rotation
2023-07-25 09:00 person1@example.com    # Tue
2023-07-25 17:00 partner-rotation
2023-07-26 09:00 person3@example.com    # Wed
2023-07-26 17:00 partner-rotation
2023-07-27 09:00 person2@example.com    # Thu
2023-07-27 17:00 partner-rotation
2023-07-28 09:00 person3@example.com    # Fri
2023-07-28 17:00 partner-rotation
2023-07-31 09:00 person1@example.com    # Mon

Assignment Details

This configuration results in On-Call Optimizer balancing team members in a very similar way to the business hours example, using a single shift type covering each 8 hour period on Mon-Fri.

There are two additional shift types (16-hour overnight shifts, and 64-hour weekend shifts) assigned to the partner team in the main schedule, however as explained below, these shift types are not used for balance and assignment purposes.

Partner Team Schedule

The shifts delegated to the partner team will be assigned in the final output of this schedule by referencing the existing assignments of the referenced partner schedule which are unchanged by the fact that it has been referenced from this schedule. This allows the partner team to use any rotation configuration they like, independently of any scheduling choices made in the the main schedule.

In this example, the partner team is using the Simple Daily Rotation configuration which assigns a single shift per day, and therefore will continue to aim to assign a balanced number of daily shifts to each member.

Fully Rendered Schedule

When viewed in the On-Call Optimizer web UI, or exported to an on-call products the “fully rendered” schedule combining the above two rotations will be as follows:

2023-07-24 09:00 person2@example.com    # Mon
2023-07-24 17:00 member2@example.com    # Mon 10:00 in partner-rotation America/Los_Angeles
2023-07-25 09:00 person1@example.com    # Tue
2023-07-25 17:00 member1@example.com    # Tue 10:00 in partner-rotation America/Los_Angeles
2023-07-26 09:00 person3@example.com    # Wed
2023-07-26 17:00 member3@example.com    # Wed 10:00 in partner-rotation America/Los_Angeles
2023-07-27 09:00 person2@example.com    # Thu
2023-07-27 17:00 member2@example.com    # Thu 10:00 in partner-rotation America/Los_Angeles
2023-07-28 09:00 person3@example.com    # Fri
2023-07-28 17:00 member3@example.com    # Fri 10:00 in partner-rotation America/Los_Angeles
2023-07-29 17:00 member3@example.com    # Sat 10:00 in partner-rotation America/Los_Angeles
2023-07-30 17:00 member1@example.com    # Sun 10:00 in partner-rotation America/Los_Angeles
2023-07-31 09:00 person1@example.com    # Mon
2023-07-31 17:00 member2@example.com    # Mon 10:00 in partner-rotation America/Los_Angeles

Return to the list of other examples

1.6 - Follow the sun (2 locations)

This schedule configuration enables each team to have the majority of their on-call hours within typical day/waking hours. It involves 3 separate schedules, one for each of the local teams and a third schedule which is then used to co-ordinate and join the local schedules together.

Main Schedule Shift Configuration Entries

The main schedule is configured in the America/Los_Angeles time zone and uses a simple shift configuration pattern that rotates between a nested schedule for each team at the appropriate time each day.

Sample shifts

2023-07-24 10:00 sfo-team
2023-07-24 22:00 lon-team
2023-07-25 10:00 sfo-team
2023-07-25 22:00 lon-team
2023-07-26 10:00 sfo-team
2023-07-26 22:00 lon-team
2023-07-27 10:00 sfo-team
2023-07-27 22:00 lon-team
2023-07-28 10:00 sfo-team
2023-07-28 22:00 lon-team
2023-07-31 10:00 sfo-team

London Team Shift Configuration Entries

The London team’s schedule is configured in the GMT time zone and the team has chosen to schedule themselves using a 4 day/3 day split across the week.

The 06:00 UTC shift start time is selected to match the 22:00 America/Los_Angeles shift start time in the main schedule.

Sample shifts

2023-07-24 06:00 london-member1@example.com    # Mon
2023-07-28 06:00 london-member3@example.com    # Fri
2023-07-31 06:00 london-member2@example.com    # Mon
2023-08-04 06:00 london-member4@example.com    # Fri
2023-08-07 06:00 london-member3@example.com    # Mon
2023-08-11 06:00 london-member1@example.com    # Fri
2023-08-14 06:00 london-member4@example.com    # Mon
2023-08-18 06:00 london-member2@example.com    # Fri

US Team

The US team uses a simple daily rotation (specifically the Simple Daily Rotation example ).

Sample shifts

2023-07-24 10:00 member2@example.com    # Mon
2023-07-25 10:00 member1@example.com    # Tue
2023-07-26 10:00 member3@example.com    # Wed
2023-07-27 10:00 member4@example.com    # Thu
2023-07-28 10:00 member3@example.com    # Fri
2023-07-29 10:00 member4@example.com    # Sat
2023-07-30 10:00 member1@example.com    # Sun
2023-07-31 10:00 member2@example.com    # Mon

Fully Rendered Schedule

When viewed in the On-Call Optimizer web UI, or exported to an on-call products the “fully rendered” schedule combining combining all of the above configuration will result in the following shifts:

# Rendered in UTC
2023-07-24 05:00 london-member1@example.com    # Mon 6am LON / 10pm Sun SFO
2023-07-24 17:00 member2@example.com           # Mon 6pm LON / 10am Mon SFO
2023-07-25 05:00 london-member1@example.com    # Tue 6am LON / 10pm Mon SFO
2023-07-25 17:00 member1@example.com           # Tue 6pm LON / 10am Tue SFO
2023-07-26 05:00 london-member1@example.com    # Wed 6am LON / 10pm Tue SFO
2023-07-26 17:00 member3@example.com           # Wed 6pm LON / 10am Wed SFO
2023-07-27 05:00 london-member1@example.com    # Thu 6am LON / 10pm Wed SFO
2023-07-27 17:00 member4@example.com           # Thu 6pm LON / 10am Thu SFO
2023-07-28 05:00 london-member3@example.com    # Fri 6am LON / 10pm Thu SFO
2023-07-28 17:00 member3@example.com           # Fri 6pm LON / 10am Fri SFO
2023-07-29 05:00 london-member3@example.com    # Sat 6am LON / 10pm Fri SFO
2023-07-29 17:00 member4@example.com           # Sat 6pm LON / 10am Sat SFO
2023-07-30 05:00 london-member3@example.com    # Sun 6am LON / 10pm Sat SFO
2023-07-30 17:00 member1@example.com           # Sun 6pm LON / 10am Sun SFO
2023-07-31 05:00 london-member2@example.com    # Mon 6am LON / 10pm Sun SFO
2023-07-31 17:00 member2@example.com           # Mon 6pm LON / 10am Mon SFO

Return to the list of other examples

1.7 - Follow the sun (multiple locations)

In this example there are 3 teams, one in London, one in Sydney and one in San Francisco, who work together to provide an overall on-call schedule. The London and San Francisco teams are equally sized and participate every day of the week, while the Sydney team with fewer people only participates during their week days, with the weekend shifts covered only from London and San Francisco.

As with the more basic follow the sun example this example is constructed with one schedule per team, combined with a fourth co-ordinating schedule that is used to provide the overall schedule.

Main Schedule Shift Configuration Entries

The main schedule is configured in the Australia/Sydney time zone in order to easily highlight the shift start times that relate to weekend coverage being provded in London and San Francisco.

The first 3 shift configurations follow a simple repeating pattern for each of the weekdays, while the final 3 shift configuration entries deal with the slightly more complex set of shifts required to implement the different shift lengths for London and San Francisco that are required to provide the desired weekend coverage.

Sample shifts

2023-07-24 03:00 sfo-team
2023-07-24 10:00 syd-team
2023-07-24 18:00 lon-team
2023-07-25 02:00 sfo-team
2023-07-25 10:00 syd-team
2023-07-25 18:00 lon-team
2023-07-26 02:00 sfo-team
2023-07-26 10:00 syd-team
2023-07-26 18:00 lon-team
2023-07-27 02:00 sfo-team
2023-07-27 10:00 syd-team
2023-07-27 18:00 lon-team
2023-07-28 02:00 sfo-team
2023-07-28 10:00 syd-team
2023-07-28 18:00 lon-team
2023-07-29 02:00 sfo-team
2023-07-29 15:00 lon-team
2023-07-30 03:00 sfo-team
2023-07-30 15:00 lon-team
2023-07-31 03:00 sfo-team
2023-07-31 10:00 syd-team
2023-07-31 18:00 lon-team

London Team Shift Configuration Entries

The London team schedule (configured in the GMT time zone) uses the same 4 day/3 day split as seen in the previous follow the sun example.

The 06:00 UTC shift start time is selected to match the 22:00 America/Los_Angeles shift start time in the main schedule.

Sample shifts

2023-07-24 06:00 london-member1@example.com    # Mon
2023-07-28 06:00 london-member3@example.com    # Fri
2023-07-31 06:00 london-member2@example.com    # Mon
2023-08-04 06:00 london-member4@example.com    # Fri
2023-08-07 06:00 london-member3@example.com    # Mon
2023-08-11 06:00 london-member1@example.com    # Fri
2023-08-14 06:00 london-member4@example.com    # Mon
2023-08-18 06:00 london-member2@example.com    # Fri

US Team

The US team uses a simple daily rotation (specifically the Simple Daily Rotation example ).

Sample shifts

2023-07-24 10:00 member2@example.com    # Mon
2023-07-25 10:00 member1@example.com    # Tue
2023-07-26 10:00 member3@example.com    # Wed
2023-07-27 10:00 member4@example.com    # Thu
2023-07-28 10:00 member3@example.com    # Fri
2023-07-29 10:00 member4@example.com    # Sat
2023-07-30 10:00 member1@example.com    # Sun
2023-07-31 10:00 member2@example.com    # Mon

Sydney Team

The small Sydney team uses basic week long rotations.

2023-07-24 10:00 person2@example.com
2023-07-31 10:00 person3@example.com
2023-08-07 10:00 person1@example.com
2023-08-14 10:00 person3@example.com

Fully Rendered Schedule

When viewed in the On-Call Optimizer web UI, or exported to an on-call products the “fully rendered” schedule combining all the individual shifts will be as follows:

# Rendered in UTC
2023-07-24 00:00 person2@example.com           # Mon 10am SYD / Sun 5pm SFO / Mon 1am LON
2023-07-24 08:00 london-member1@example.com    # Mon 6pm SYD / Mon 1am SFO / Mon 9am LON
2023-07-24 16:00 member2@example.com           # Tue 2am SYD / Mon 9am SFO / Mon 5pm LON
2023-07-25 00:00 person2@example.com           # Tue 10am SYD / Mon 5pm SFO / Tue 1am LON
2023-07-25 08:00 london-member1@example.com    # Tue 6pm SYD / Tue 1am SFO / Tue 9am LON
2023-07-25 16:00 member1@example.com           # Wed 2am SYD / Tue 9am SFO / Tue 5pm LON
2023-07-26 00:00 person2@example.com           # Wed 10am SYD / Tue 5pm SFO / Wed 1am LON
2023-07-26 08:00 london-member1@example.com    # Wed 6pm SYD / Wed 1am SFO / Wed 9am LON
2023-07-26 16:00 member3@example.com           # Thu 2am SYD / Wed 9am SFO / Wed 5pm LON
2023-07-27 00:00 person2@example.com           # Thu 10am SYD / Wed 5pm SFO / Thu 1am LON
2023-07-27 08:00 london-member1@example.com    # Thu 6pm SYD / Thu 1am SFO / Thu 9am LON
2023-07-27 16:00 member4@example.com           # Fri 2am SYD / Thu 9am SFO / Thu 5pm LON
2023-07-28 00:00 person2@example.com           # Fri 10am SYD / Thu 5pm SFO / Fri 1am LON
2023-07-28 08:00 london-member3@example.com    # Fri 6pm SYD / Fri 1am SFO / Fri 9am LON
2023-07-28 16:00 member3@example.com           # Sat 2am SYD / Fri 9am SFO / Fri 5pm LON
2023-07-29 05:00 london-member3@example.com    # Sat 3pm SYD / Fri 10pm SFO / Sat 6am LON
2023-07-29 17:00 member4@example.com           # Sun 3am SYD / Sat 10am SFO / Sat 6pm LON
2023-07-30 05:00 london-member3@example.com    # Sun 3pm SYD / Sat 10pm SFO / Sun 6am LON
2023-07-30 17:00 member1@example.com           # Mon 3am SYD / Sun 10am SFO / Sat 6pm LON
2023-07-31 00:00 person3@example.com           # Mon 10am SYD / Sun 5pm SFO / Mon 1am LON

Return to the list of other examples

2 - Constraint Optimizing Algorithm

On-Call Optimizer uses constraint programming algorithms to solve the challenge of producing an optimal schedule.

Goals

To determine what an optimal schedule looks like, On-Call Optimizer is programmed with a series of goals that are desired for a schedule. A perfect schedule would meet every goal, an optimal schedule comes as close as possible to meeting each goal given the constraints dictated by the shift configuration of the schedule and the availability information for each of the members.

The goals that On-Call Optimizer tries to achieve focus on maximizing the balance of the schedule over the mid to long term, while also maintaining the quality of each individual assignment in the short term. Typical goals that On-Call Optimizer tries to achieve include:

• A member should not be assigned to a shift blocked in their availability information.
• Each member should have a fair share of shifts, taking into account weekends, holidays and out-of-business hours shifts as distinct types.
• A member should be assigned a shift marked as preferred in their availability information.
• A member should not have consecutive shifts.

High Level Overview

On-Call Optimizer uses a constraint satisfying algorithm to find an solution (aka assignment) that is both feasible and comes closest to meeting each goal.

The input to the algorithm starts with a set of variables referenced by a tuple of (start time, assignee role, member). So for an example assignment for a single primary assignee in a schedule of 5 members for 7 shifts, there will be 35 different shift variables input into the algorithm.

Next hard constraints which determine whether or not a particular assignment is feasible or not are configured. In the simplest case the only hard constraint would be that the sum of all variables matching (start time, assignee type, *) must be equal to 1 - e.g. only solutions that assign a single member to a shift are feasible.

After the hard constraints additional constraints representing each desired goal for the schedule are configured. Goal based constraints utilize a weight factor rather than requiring equality to a fixed value and match against particular combination of shift variables that are set to represent each potential solution, A score is calculated for each constraint in each potential solution by multiplying the value of the matching shift variables against the weight of the constraint. The overall sum of these scored constraints is reported as the “cost” of the assignment solution, and the assignment solution with the lowest overall cost represents the optimal assignment given the set of inputs.

Example weighting factors

Illustrative weighting factors for the typical goals above might look like the following:

• Any assignment matching a blocked shift: >2.0, ensuring that such assignments are only ever used as a last resort if no other possibilities exist.
• Any shift assignment above or below the ideal balance are penalized: 1.0
• Any assignment of a preferred shift: -0.5, the negative weighting results in a favourable score, making any assignment containing this shift preferred over an assignment that does not.
• Any consecutive shift assignment for a member: 0.3

In practice the specific weighting factors used are much more complex and are selected based on On-Call Optimizer’s accumulated expertise of the ideal weightings for different schedule configuration patterns.

BEST_MEMBER

The “BEST_MEMBER” placeholder is used in the shift configuration for each schedule to denote that the assignee for the specified shift should be chosen from among the members of the schedule based on the output of the above algorithm.

Therefore the “BEST_MEMBER” for a shift will be the member assigned to the shift variable for that shift in the solution that resulted in the lowest overall cost.

Importantly “best” does not mean “perfect”. In situations where there are competing constraints, the best solution may require assigning a member to consecutive shifts or ignoring their preferences in order to achieve an overall optimum assignment.

3 - Extension logic

On-Call Optimizer shifts are defined by the day of the week, hour and minute at which they start (e.g. Mon 10:00) and therefore no shift can ever be longer than 7 calendar days. The following details describe at a high-level how On-Call Optimizer uses this configuration data to generate specific shifts with fully-defined start and end times.

Basic procedure

Given a starting timestamp:

1. Loop through all defined shift configurations; discard any with a starting day that does not match the weekday.
2. From the remaining shift configurations; discard any with a starting hour before the hour of the day.
3. From the remaining shift configurations; discard any with a starting minute before the minute of the hour.
   • Sort any remaining shift configurations by hour, then minute in ascending order and then select the first (earliest hour, minute). The Day, Hour and Minute from this selected configuration is the starting time of the next shift in the schedule.
   • If no matching shift configurations remains, advance the timestamp to the end of the day (00:00 next day) and repeat the process.

Use

The basic procedure can be used directly with an arbitrary timestamp to find the starting time of the next shift in the schedule.

To find the starting time of the shift that will follow an existing shift in the schedule, the procedure must be executed with the starting timestamp set to 1 minute after the starting time of the shift to be followed - any end time for the existing shift should be ignored. See the example below for an illustration of why this is important.

All time and date calculations during the extension process must be performed with respect to the time zone of the schedule itself.

Matching of day wildcards

• A shift configured with the day set to the Daily wildcard will match any timestamp.
• A shift configured with the day set to the Weekdays wildcard will match any timestamp, where the abbreviated name of the day of the week (e.g. %a strftime(3) component) in the time zone of the schedule is one of the Mon-Fri set.
• A shift configured with the day set to the Weekends wildcard will match any timestamp, where the abbreviated name of the day of the week (e.g. %a strftime(3) component) in the time zone of the schedule is one of Sat or Sun.

Examples

For simplicity these examples do not display the time zone, which is not relevant but can be assumed to be UTC.

Basic

Assuming a shift configuration of Mon 10:00, Fri 17:00, when executed for the week starting April 1st 2024, the next 4 returned shifts would be:

• 2024-04-01 10:00
• 2024-04-05 10:00
• 2024-04-08 10:00
• 2024-04-12 10:00

This provides a schedule with a ~5-day shift covering the working week, and a ~2-day shift covering the weekend.

Daily and Weekends

Assuming a shift configuration of Daily 10:00, Weekends 22:00, when executed on April 4th 2024, the next 7 returned shifts would be:

• 2024-04-04 10:00
• 2024-04-05 10:00
• 2024-04-06 10:00
• 2024-04-06 22:00
• 2024-04-07 10:00
• 2024-04-07 22:00
• 2024-04-08 10:00

This provides a schedule with 24-hour shifts during weekdays, but adds an additional “overnight” shift on weekends resulting in a split of each weekend day (Sat, Sun) into two 12-hour shifts.

Extension after configuration change

This example explains why it is important to extend from 1 minute after the start of the final existing shift, rather than from the end of the existing shift.

• Original shift configuration: Mon 10:00
• Existing shift: Mon 1st Apr 2024 10:00 - Mon 8th Apr 2024 09:59
• New shift configuration: Mon 09:00
• Expected next shift: Mon 8th Apr 2024 09:00 - Mon 15th Apr 2024 08:59

Moving the expected start time back by 1 hour creates an ambiguous situation for the schedule, either the next shift needs to start 1 hour prior to the end of the existing last shift, or if the end of the last shift is strictly observed and extension begins from 10am on Monday the 8th, the next starting time is not until 9am the following Monday, creating a 7-day gap in the schedule!

While either scenario will likely require user input to resolve and confirm the desired intention, On-Call Optimizer prefers to generate schedules that provide continuous coverage and therefore adopts the rule describe above - extension starts from the minute after the last existing shift starts, resulting in shifts that overlap the existing schedule by returned.

4 - Authentication and Authorization

On-Call Optimizer exclusively uses OAuth and OIDC for authorization and authentication, there is no support for accessing On-Call Optimizer via username/password.

On-Call Optimizer adheres to the principle of least privilege, requesting only the minimum OAuth permissions and scopes required to complete the action requested following the principle of incremental authorization. This allows users to mix and match between different providers without needing to grant an overly wide set of permissions to On-Call Optimizer.

Permissions requested at Login

On-Call Optimizer requests an OIDC login flow from the authentication provider requesting the OIDC standard email and profile grants. On-Call Optimizer stores the email and name returned in the provided ID token.

When logging in with a Google Workspace, or Microsoft organizational account, On-Call Optimizer will also retrieve and store the ID, name and primary domain of the workspace/organization of your account in order to create and associate your On-Call Optimizer account with a corresponding On-Call Optimizer Organization. For Microsoft accounts the User.Read permission is requested in order to retrieve this information as it is not included directly in the ID token.

All other information available to On-Call Optimizer during the login process is discarded. In particular, once the login process has completed, On-Call Optimizer does not retain or store the access or refresh tokens provided by the OIDC login flow.

Permissions requested when connecting a calendar

When connecting to a calendar provider, On-Call Optimizer uses a standard OAuth 2.0 authorization code flow to obtain a read-only access token, along with an offline access (refresh) token to allow continuing access to the users calendar.

Permissions requested when connecting an on-call product

On-Call Optimizer uses API tokens for access to any configured on-call product schedules. A read-only API token is supported when an on-call product is used a a source for On-Call Optimizer schedule configuration. A read-write API token is required when an on-call product is configured as a destination for a schedule.

Permissions requested when connecting to Slack

When the On-Call Optimizer Slack app is installed for a Slack Workspace, On-Call Optimizer receives an OAuth 2.0 access and refresh token which are used to access the Slack API. The following scopes are required for the On-Call Optimizer Slack app:

• app_mentions:read - to allow the app to receive app_mention notifications, in order to respond when the app is directly mentioned.
• channels:read, groups:read, im:read - to allow the app to receive member_joined_channel and member_left_channel events in order to keep track of the channels it has been invited to be present in, and to make conversations.info API requests to retrieve the name of those channels. On-Call Optimizer only receives these events and requests information for channels which it has been invited to join.
• chat:write - to allow the app to send messages to channels using the chat.postMessage and chat.postEphemeral API requests. On-Call Optimizer only sends messages in response to a command request or to deliver a configured notification.
• im:history - to allow the app to receive message.im notifications when a user directly interacts with the app from the messages tab of the App Home surface. On-Call Optimizer does not make any API requests using this scope.
• reactions:read, reactions:write - to allow the make reactions.* API requests in order to provide reactions indicating the status of On-Call Optimizer’s response to a command request issued by a user. On-Call Optimizer does not read or write reactions to any other messages.

Permissions Summary

[0]: The OIDC protocol includes the offline access scope by default, however On-Call Optimizer does not retain the provided refresh (or access) tokens, so no offline access is available to On-Call Optimizer, even though the permissions screen seen by the user indicates it may be.

[1]: Refer to the calendar provider for details on the specific scope name: Google, Outlook

5 - Integration Points

Schedule Configuration

On-Call Optimizer supports import of the basic configuration of a schedule from supported on-call products.

Schedule Assignments

On-Call Optimizer supports export of the shift assignments for a schedule to supported on-call products.

Availabilty Information

• On-Call Optimizer supports import of member availability information from supported calendars.
• On-Call Optimizer supports the use of external schedules to provide cross-schedule availability information from supported on-call products.

Notification and Messaging

• On-Call Optimizer supports email notifications for new assignments and new swap requests.
• On-Call Optimizer has an integrated Slack App which in addition to providing notification and messaging functionality, also allows interaction with On-Call Optimizer schedules from within the Slack UI.

Additional Integrations

Additional integrations will be added as demand and development capability allow.

Please contact us, if you would like to request integration with a product not yet supported.

API and Event Notifications

On-Call Optimizer functionality can be made available via API or event (e.g. webhook) based methods upon request.

6 - Notifications

Notification Philosophy

On-Call Optimizer aims to provide relevant and useful notification of key events and situations to all interested parties while minimizing unnecessary distraction and noise. To achieve this aim On-Call Optimizer provides a highly configurable notification framework which recognizes that what is relevant varies can vary significantly between individuals, teams and schedules!

This page describes the available notifications that On-Call Optimizer can generate, how they can be customized and how they are configured.

Notification Methods

To select your preferred notification method, use the selector on the profile page (also accessible by clicking the user icon in the top right corner of On-Call Optimizer and selecting My profile from the drop-down menu).

By default, all users will be notified via email, to the address associated with the account used to login.

Some users of On-Call Optimizer may also have the option to receive notifications via Slack. Slack notifications are available to members with an organization linked account where the organization in On-Call Optimizer has been linked to a Slack workspace. Details on whether these conditions are met can be found by clicking the Messaging item from the Integrations section of the menu sidebar.

Schedule Assignments

On-Call Optimizer supports export of the shift assignments for a schedule to supported on-call products.

Availabilty Information

• On-Call Optimizer supports import of member availability information from supported calendars.
• On-Call Optimizer supports the use of external schedules to provide cross-schedule availability information from supported on-call products.

Notification and Messaging

• On-Call Optimizer supports email notifications for new assignments and new swap requests.
• On-Call Optimizer has an integrated Slack App which in addition to providing notification and messaging functionality, also allows interaction with On-Call Optimizer schedules from within the Slack UI.

Additional Integrations

Additional integrations will be added as demand and development capability allow.

Please contact us, if you would like to request integration with a product not yet supported.

API and Event Notifications

On-Call Optimizer functionality can be made available via API or event (e.g. webhook) based methods upon request.

7 - Organization Support

Organization support in On-Call Optimizer provides many benefits for larger teams including the ability for members to view schedules within the organization that they are not directly members of.

Organization Basics

An organization in On-Call Optimizer is inherited from the organizational information provided by the login identify provider. When the identity token resulting from a successful login provides organizational metadata your On-Call Optimizer account will be associated with the corresponding organization entity in On-Call Optimizer.

The supported organizational identity providers are:

• Google Workspace
• Microsoft Work accounts with an associated organization.

On-Call Optimizer’s organizational features cannot be used when authenticating from a consumer Gmail or Outlook personal account.

To check whether your On-Call Optimizer account is associated with an organization, click on the profile icon in the top right corner of the app. Organization accounts will show an organization icon and name between your name and email and the ‘My profile’ link. If you do not see this entry, your On-Call Optimizer account is not associated with an organization.

Organizational details can be viewed on the organization profile page which is accessible by clicking on the link in the user profile menu described in the previous paragraph.

Organization Resource Ownership

Most resources (including Schedules, On-Call Product and Messaging integrations) created by an On-Call Optimizer account belonging to an organization will be owned by the organization rather than the individual.

The only exception to this are Calendar integrations, which by their nature are always owned by the individual who created them.

Organization Roles

Each member of an organization in On-Call Optimizer belongs to a role which grants permissions to perform certain actions. The available roles are:

Organization Admin

• Can participate in the schedules they have been added to according to their assigned schedule role.
• Can change the organization role of any member of the organization.
• Are automatically granted all of the organizational permissions available to members described below.

The first user to login to On-Call Optimizer from an organization will be assigned the organization admin role, subsequent users will be assigned as organization members.

Organization Member

Organization members can participate in the schedules they have been added to according to their assigned schedule role.

The organization member role can also be granted any or all of the following permissions on the organization:

• View all schedules - Defaults to true. Allows members of your organization to view schedules in the organization that they are not members of.
• Manage schedules - Defaults to false. Allows members of your organization to create schedules, and delete schedules on which they hold the schedule admin role.
• Manage Integration Connections - Defaults to false. Allows members of your organization to create, update and delete integration connections such as On-Call and Messaging products.