Supported On-Call Products

• 1: PagerDuty
• 2: Opsgenie

1 - PagerDuty

• Synchronize On-Call Optimizer’s flexible, calendar aware on-call assignments to your PagerDuty schedules.
• Import PagerDuty schedule configuration and history into On-Call Optimizer.
• Enjoy automated shift swap handling synchronized from On-Call Optimizer to PagerDuty.

How it Works

• On-Call Optimizer will import the list of members and shift history from a PagerDuty schedule to an On-Call Optimizer schedule.
• On-Call Optimizer will maintain override entries in one or more PagerDuty schedules to synchronize the on-call shifts assigned to members with the flexible, calendar aware assignments and swaps generated and managed by On-Call Optimizer.
  • Refer to the Destination documentation for more details on how this synchronization takes place.

Requirements

• Connecting PagerDuty to On-Call Optimizer requires a PagerDuty API Key with read-write permissions to the PagerDuty schedule(s) you wish to connect.

Support

If you need help with the integration of PagerDuty and On-Call Optimizer please raise a support case from the help page within On-Call Optimizer, or contact us at support@oncall-optimizer.com.

Integration Walkthrough

In PagerDuty

1. From the Integrations menu, select API Access Keys from the Developer Tools column.
2. Click Create New API Key.
3. Enter a description for the key (e.g. “On-Call Optimizer”) and click the Create Key button.
   • The Read-only API Key checkbox must remain unchecked.

Keep the generated key in a safe place for later use. You can now proceed to the In On-Call Optimizer section below.

In On-Call Optimizer

1. Click On-Call Products in the side menu.
2. Click Create New Connection at the bottom of the page.
3. Click the PagerDuty logo.
4. Enter the API Key obtained in the previous section into the API Key field and click Continue

On-Call Optimizer will begin the connection process and present the list of available PagerDuty schedules when complete. To continue onwards from this point, follow the Link an existing schedule getting started guide.

How to Uninstall

To remove a PagerDuty connection it must not be in use by any schedule in On-Call Optimizer.

1. Identify all PagerDuty linked schedules using the green PagerDuty badge that appears to the right of their name.
   1. From the Configuration tab of the schedule, click the permanently delete link at the bottom of the page.
   2. Enter the name of the schedule in the Confirm permanent deletion text field and click the Permanently Delete Schedule button.
2. Delete any destinations referencing the PagerDuty connection you want to remove from any schedule where they are configured.
   1. For each schedule, click the Destinations tab and review the list of configured destinations.
   2. For each destination using the connection being removed, click the Remove button on the right-hand side.

Once the connection is no longer in use by any On-Call Optimizer schedule:

1. Select On-Call Products from the side menu.
2. Click on the unused PagerDuty connection in the list of connections.
3. Click the Destroy Connection button.

Additional Details

Permissions and Data Access Reference

On-Call Optimizer requires read-write PagerDuty API key to link to a PagerDuty schedule and export shifts to it as a destination.

Data accessed

On-Call Optimizer exclusively uses the Schedule and User endpoints of the PagerDuty API, and does not require access to any other API object types.

On-Call Optimizer reads the name, members and shift configuration of any available PagerDuty schedules for the purposes of presenting a list of available schedules to the user in the On-Call Optimizer application.

For any PagerDuty schedule linked to an On-Call Optimizer schedule, On-Call Optimizer will, in addition to the basic data described above, also read a list of assigned shifts and overrides on an ongoing basis for the purposes of maintaining and validating synchronization between On-Call Optimizer and PagerDuty.

For any PagerDuty schedule configured as a destination, On-Call Optimizer will create and delete override entries on the PagerDuty schedule for the purposes of bringing the PagerDuty schedule into alignment with the shift assignments in On-Call Optimizer.

While executing the above primary functions, On-Call Optimizer will also read the list of users available in the PagerDuty account for the purposes of mapping between the PagerDuty user ID and the user’s email address and full name which are required by On-Call Optimizer. On-Call Optimizer does not access or store any other attributes of PagerDuty users (e.g. phone numbers or contact methods).

2 - Opsgenie

On-Call Optimizer supports the import of configuration details and the export of shift assignments to one or more Opsgenie schedules.

Connection Process

To link an Opsgenie account to your On-Call Optimizer account:

1. Select On-Call Products from the side menu.
2. From the On-Call Products page, select Create New Connection at the bottom of the page.
3. Click on the Opsgenie logo.
4. Enter your API Key in the provided field and click Continue
5. On-Call Optimizer will begin the connection process and present the list of available Opsgenie schedules when complete.

Opsgenie Schedules and Rotations

The data model for representing an on-call schedule and an associated set of assigned shifts differs between On-Call Optimizer and Opsgenie:

• An On-Call Optimizer schedule has a single configuration describing how and when shifts rotate between members. Each shift within the schedule may have one or more assignees (e.g. primary, secondary, tertiary).
• An Opsgenie schedule can contain one or more rotations, and each rotation can have an individual configuration for both how shifts rotate between members and the list of members for the rotation.
  • Alerts in Opsgenie may only be routed to a schedule, not a rotation.
  • Alerts routed to a schedule will be delivered to any member currently assigned to any rotation within the schedule.
• To achieve the primary/secondary on-call functionality supported in a single schedule in On-Call Optimizer requires the use of two individual schedules each with their own rotation in Opsgenie.

To provide consistent behaviour despite these differences, On-Call Optimizer uses the following process:

• Only an Opsgenie schedule can be the source or destination of/for an On-Call Optimizer schedule. On-Call Optimizer cannot be configured from or targeted to a particular rotation within an Opsgenie schedule.
• When importing shifts from an Opsgenie schedule, assignees from each configured rotation within the schedule will be merged into a single On-Call Optimizer shift in the position indicated by their ordering in the Opsgenie interface (e.g. the first rotation will take the primary role in On-Call Optimizer, the second rotation will take the secondary role and so on).
• When exporting shifts to an Opsgenie schedule, the override entries created by On-Call Optimizer in Opsgenie will not specify any particular rotation, and will therefore apply to all rotations within the schedule. The On-Call Optimizer shift role that is exported to the override entries for each Opsgenie schedule is selected at the time the destination is configured and can be any of the available roles for the On-Call Optimizer schedule.

Opsgenie Override Entries

On-Call Optimizer uses the Opsgenie override functionality to represent the assigned shifts for each schedule. An override entry is created for each shift assigned by On-Call Optimizer resulting in continuous override coverage being provided in the Opsgenie UI to match the schedule assigned by On-Call Optimizer.

On-Call Optimizer tracks the latest (most distant) date for which it has successfully exported assigned shifts to Opsgenie as override entries and does not make any further modifications to overrides prior to this date unless they are directly changed in On-Call Optimizer (e.g. by replacing an earlier assignment or using On-Call Optimizer’s swap functionality).

This allows last-minute and short-term changes to overrides (e.g. to cover a commute window from home to the office) to be made directly in Opsgenie without conflicting with On-Call Optimizer, however if you make a planned change to the schedule in On-Call Optimizer, Opsgenie will be updated.

Pre-existing overrides in Opsgenie for dates beyond the date to which On-Call Optimizer has previously exported will be overwritten when On-Call Optimizer exports the assigned shifts for that time period for the first time.

During normal operation the latest date exported to Opsgenie will match the shifts that have been assigned up to the configured horizon of the On-Call Optimizer schedule. This date can always be viewed in the tooltip associated with the destination in the bottom of the Schedule Details sidebar of any On-Call Optimizer schedule.

Disconnecting

To remove a Opsgenie connection it must not be in use by any schedule in On-Call Optimizer.

1. Deleted any schedules in On-Call Optimizer which are linked via the Opsgenie connection you want to remove.
2. Delete any other destinations using the Opsgenie connection you want to remove from any schedule where they are configured.

Once the connection is no longer in use by any On-Call Optimizer schedule:

1. Select On-Call Products from the side menu.
2. Click on the unused Opsgenie connnection in the list on the page.
3. Click the “Destroy Connection” button.

Required Permissions and Data

On-Call Optimizer requires a read-write Opsgenie API key to link to a Opsgenie schedule and export shifts to it as a destination.

If destination export functionality is not required, On-Call Optimizer will work with a read-only API key, but will only be able to list and import configuration data from the available Opsgenie schedules.

Data accessed

On-Call Optimizer exclusively uses the Schedule, Schedule Rotation and Schedule Override endpoints of the Opsgenie API, and does not require access to any other API object types.

On-Call Optimizer reads the name, members and shift configuration of any available Opsgenie schedules for the purposes of presenting a list of available schedules to the user in the On-Call Optimizer application.

For any Opsgenie schedule linked to an On-Call Optimizer schedule, On-Call Optimizer will in addition to the basic data described above, also read a list of assigned shifts and overrides on an ongoing basis for the purposes of maintaining and validating synchronization between On-Call Optimizer and Opsgenie.

For any Opsgenie schedule configured as a destination, On-Call Optimizer will create and delete override entries on the Opsgenie schedule for the purposes of bringing the Opsgenie schedule into alignment with the shift assignments in On-Call Optimizer.