Escalation policies make sure the right people are notified at the right time. They connect services to schedules. A service can only have one escalation policy, though an escalation policy can be associated with multiple services.
Escalation policies are found under Configuration → Escalation Policies. There is a Default escalation policy in the account from the start. The Account Owner will be the only target on the default escalation policy, though this can be changed at any time.
Required User Permissions
To create an escalation policy:
- Go to Configuration → Escalation Policies.
- Click New Escalation Policy.
- Name your escalation policy. Add a description (optional).
- Select the targets you want to notify when an incident is triggered:
- Select a user if you always want that person to be notified when an incident is assigned and/or escalated to an escalation level.
- Select an on-call schedule if you want to notify the user who is on-call from that schedule.
- If desired, you can add a second level to the escalation policy. To do this, choose the number of minutes that should pass before the incident escalates. This time period is the escalation timeout. Incidents will not escalate if they are acknowledged or resolved before the timeout is reached.
- Then click Add a new Escalation Rule to create the second level.
- Select targets for the second escalation rule.
- Configure additional escalation rules as required.
- Click Save.
We suggest configuring your policy to repeat. To do this, check the box next to If no one acknowledges, repeat this policy __. Then, select the number of times to repeat. An escalation policy can be repeated up to 9 times.
In the example below, if an on-call user in the Primary On-Call Schedule schedule does not acknowledge an incident in 30 minutes, it will escalate to Jason Collison. The escalation timeout at the second level is also 30 minutes. Jason will have 30 minutes to acknowledge the incident before it escalates and starts over from the beginning of the policy. This escalation policy is set to repeat 9 times.
You can select users or schedules as targets on an escalation policy. When an incident triggers, we'll attempt to notify responders at the first level of the escalation policy. If the incident is not acknowledged within the escalation timeout period, it will escalate to next escalation level, and so on down the line.
If nobody is on-call in the first level, we will assign the incident to the on-call responder at the subsequent escalation level.
An incident follows the escalation policy as it was at the time the incident triggered. Any changes to the escalation policy made after an incident triggers will not affect open incidents (triggered or acknowledged).
- You can add up to 20 escalation rules to an escalation policy.
- You have the option to repeat an escalation policy 9 times. Once an escalation policy reaches the amount of loops configured, the incident will stay assigned to the last user and will not continue to notify once it has cycled through all of the responder's contact methods.
- Notifying too many users at once runs the risk of creating confusion about who owns an incident. With this is mind, multi-user notifications on each escalation rule are limited to 50 users or schedules on Enterprise plans or accounts with Modern Incident Response, 10 on Platform Business plans, and 5 on Platform Team and Starter plans. This topic addresses best practices about when to notify one user vs. many users.
- The minimum escalation timeout is 1 minute if there is a single target on an escalation rule. Alternatively, if there is more than one target in an escalation level the minimum escalation timeout is 5 minutes. These restrictions are displayed in the web UI.
An escalation policy is designed to engage one person in incident response, and it will escalate until one person has responded. Once one person has responded, the escalation policy will stop escalating, and no further notifications will be sent.
Multi-user notifications will notify multiple users at once when an incident is triggered or escalated, and can be configured within an escalation policy. To notify two or more users at once with the goal of engaging one person, you will want to configure an escalation policy so that multiple on-call schedules and/or users are in the same escalation level.
To notify multiple people and/or escalation policies independently, you can use a response play—see How to: Mobilize a Coordinated Response.
To notify two or more users at once, you will want to set up an escalation policy with multiple on-call schedules/users on the same escalation level:
Go to Configuration → Escalation Policies.
Click New Escalation Policy to create a new escalation policy, or click an existing escalation policy's gear icon and then Edit to edit an existing one.
Click in the field below Notify the following users or schedules and select the on-call schedules and/or users you want to notify at the same time when an incident is triggered or escalated.
In the example below, Harriet Spy and Rocko Wallaby will be notified at the same time since they are both in escalation level 1. If neither of them respond within 30 minutes, it will then escalate to escalation level 2 and Donatello Turtle will then be notified.
- Click Save and you're done!
If you have Live Call Routing enabled to Connect Directly and there is more than one responder on an escalation level, PagerDuty will randomly cycle through all responders on at that level. If an incident triggers via Live Call Routing (if either no one answers, or you've selected "Leave a Message"), however, all users on an escalation level can expect to receive notifications via their configured notification methods.
Don't: Create On-Call Schedules For Multi-User Notifications
An important concept to grasp is that only one user can be on call per schedule, and using a schedule on its own (without an escalation policy) will not notify multiple users at once. A natural first instinct would be to add multiple layers to a schedule, however, the way PagerDuty's system works, the lowest layer on a schedule takes precedence over any others.
The following screenshot demonstrates what will happen if multiple layers are stacked on top of each other (Layer 3 takes precedence over Layers 1 and 2):
Thus, adding schedules and/or users to escalation policies is the only way to notify multiple users at once.