Escalation Policy Basics

Escalation policies notify on-call users about incidents

Escalation policies are used to automate incident assignment and they connect services to individual users and/or schedules. They are designed to notify a single target at a time until one individual acknowledges the incident. By adding rules to your escalation policy, you can ensure that each incident has a thorough response plan in the event that initial responders cannot acknowledge. Services in PagerDuty can only be associated with one escalation policy. An escalation policy, however, can be associated with as many services as you like.

📘

Pricing Plans

Escalation policies are available on all pricing plans, although the Free plan is limited to a single escalation policy. All other plans may have unlimited escalation policies.

🚧

Required User Permissions

The following user roles can create, edit and delete escalation policies:

  • Account Owner, Admin, and Global Admin users
  • Users with a Manager base role
  • Users on a Team who’ve been granted Manager access to an escalation policy

Create an Escalation Policy

In every new PagerDuty account, there is an escalation policy called Default with the Account Owner on it.

To create a new escalation policy:

  1. Navigate to People Escalation Policies New Escalation Policy.
  2. Name your escalation policy. Add a Description (optional).
  3. In the Notify the following users or schedules field, search and select the target(s) you want to notify when an incident triggers.

📘

Note

  • If you have created any schedules and you want users on those schedules to receive incident notifications, you must add your schedule to an escalation policy and then add the escalation policy to a service.
  • If you select more than one user/schedule, each user and/or schedule will be notified at the same time per escalation rule.
    If you do not want to add another layer to your escalation policy, skip to step 8. If you do want to add another layer, continue to step 4.
  1. Optional: You can then add a second rule to the escalation policy, which will serve as a secondary line of responders who will be notified in the event that no one in the first rule responds. To do this, enter the number of minutes that should pass before the incident escalates to the next rule in the escalates after ___ min. field. This time period is called the escalation timeout. Incidents will not escalate if they are acknowledged or resolved before the timeout is reached.
  2. Click Add a new Escalation Rule to create the second rule.
  3. Search and select the target(s) you want to notify when an incident triggers.
  4. Configure additional escalation rules as required.
  5. Click Save.
  6. Next, you will need to add your escalation policy to a service so that users can be notified of incidents. Follow our instructions on creating a service if you haven't created one yet, or edit an existing service to add your escalation policy.

👍

Tip

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.

Escalation Timeout

The escalation timeout is the amount of time in which a user must acknowledge or resolve an incident before it escalates to the next rule. The default escalation timeout is 30 minutes but can be adjusted.

16821682

Escalation timeout

Edit an Escalation Policy

  1. In the web app, navigate to People Escalation Policies.
  2. Click the to the right of your desired escalation policy, or click an escalation policy's name, then click Edit Escalation Policy.
  3. You may edit the following, based on your preferences:
    • Escalation policy name: Enter a new name for the escalation policy.
    • Description: Enter a new description for the escalation policy.
    • Team (Available on Business and Digital Operations plans): Click the dropdown and select a new Team.
    • Send On-Call Handoff Notifications: Select the condition when the escalation policy should send on-call handoff notifications; always or when in use by a service.
    • Tags: To add a tag, search and select the tag. To delete a tag, click . To create a new tag and add it to the escalation policy, type your preferred tag name and then select [TAG-NAME] (Create new tag) from the dropdown.
    • Escalation Rules:
      • To add users or schedules to an escalation rule: In the Notify the following users or schedules field, search and select the target(s) you want to notify when an incident triggers.
      • To delete users or schedules from an escalation rule: In the Notify the following users or schedules field, click the to the right of the user or schedule you would like to delete.
      • Assign via Round Robin: You may check or uncheck this checkbox on each escalation rule.
      • If no one acknowledges, repeat this policy [X] times: If you would like the policy to repeat, check the checkbox and select the number of times you would like it to repeat. If you would not like it to repeat, uncheck this checkbox.
      • To add a new escalation rule: Click Add a new escalation rule
      • To reorder escalation rules: Click and drag the on the bottom right of the escalation rule.
      • To delete an escalation rule: Click the to the right of the escalation rule.
      • Edit Escalation Timeout Period: To edit the escalation timeout, enter a new time in minutes. The time period must be over 3 minutes for multiple targets.
  4. Click Save.

Delete an Escalation Policy

❗️

Deletion Warning

  • Please note that if you delete an escalation policy, the users and schedules on that policy will no longer be associated with the service they were supporting. If the service that uses your escalation policy still needs on-call responders, we highly recommend editing the escalation policy instead to suit your needs.
  • Deleting an escalation policy is most appropriate when the service it was supporting is no longer in use.
  1. Navigate to People Escalation Policies.
  2. Click the to the right of your desired escalation policy, or select an escalation policy, then click Edit Escalation Policy.
  3. At the bottom of the page, select Delete.
  4. Confirm your selection in the modal.
    • There is no undo for this action.

Add an Escalation Rule

If a responder does not acknowledge an incident, you’ll likely want one or more “backup” rules on an escalation policy. PagerDuty addresses this need with “Escalation Rules”.

  1. In the web app, navigate to People Escalation Policies.
  2. Select an escalation policy, then click Edit Escalation Policy.
  3. At the bottom of the first escalation rule, enter a value for escalates after _ min.
    • This represents the number of minutes that will pass before PagerDuty notifies the next escalation rule.
  4. Click Add a new Escalation Rule.
  5. Select a user or schedule to notify if responders at the previous rule do not acknowledge an incident.
  6. Click Save.

Delete an Escalation Rule

  1. In the web app, navigate to People Escalation Policies.
  2. Select an escalation policy, then click Edit Escalation Policy.
  3. On the escalation rule you’d like to delete, click .
  4. Click Save.

🚧

Heads Up

There is no undo or confirmation alert with this action. That said, you may click Cancel at the bottom of the page if you’ve made an incorrect selection and have not saved your changes yet.

Escalation Rules

Escalation policies are made up of rules that allow you to escalate incidents if responders in the first rule do not respond within the escalation timeout. We recommend at least two rules, with the option of adding more. Escalation rules can also be used to achieve more complex use cases involving schedules.

Notify Multiple Users at Once

Escalation policies are designed to notify a single target at a time until one individual acknowledges the incident. That said, there may be times when you wish to notify more than one user at a time. An escalation policy can be configured to notify more than one user when an incident is triggered or escalated (multi-user notifications).

There are three methods of configuring multi-user notifications based on your intended use case:

  • Notifying multiple users at once regardless of their on-call status. This method is covered below.
  • Notifying multiple users and/or groups at once based on a specific span of time. For instance, if you want more than one person to be notified during the weekend or after business hours. This method is also covered in our article Escalation Policies and Schedules.
  • Notifying a Secondary on-call user when a Primary on-call user does not respond based on their schedule and escalation rule. This method is covered in our article Escalation Policies and Schedules.

📘

Note

To create a predetermined set of incident actions that assist with assembling a response team of multiple responders and/or escalation policies independently, you can also use a Response Play to mobilize a coordinated response.

Notifying Multiple Users at Once Regardless of Their On-Call Status

To notify two or more users at once regardless of their on-call status, you will want to set up an escalation policy with multiple users on the same escalation rule:

  1. Go to People Escalation Policies.
  2. Click New Escalation Policy to create a new escalation policy, or select Edit to edit an existing one.
  3. Click in the field below Notify the following users or schedules and select all of the responders who should be notified when an incident is triggered or escalated.
  4. Click Save.

❗️

FAQ: Can I use a schedule on its own to achieve multi-user notifications?

No. Please visit Why Schedules Alone Are Ineffective For Multi-User Notifications for more information. This section covers essential concepts to understand, and how to properly configure multi-user notifications.

Escalation Targets

Each rule of an escalation policy requires at least one target, so that PagerDuty knows who to notify when an incident triggers. A target can be either a user or a schedule:

  • User Targets: Select users as targets if you always want a specific person to be notified when an incident is triggered, assigned or escalated to their rule on an escalation policy.
  • Schedule Targets: Select on-call schedules as targets if you want to notify the user who is currently on-call when an incident is triggered, assigned or escalated to the schedule’s rule on an escalation policy. For more information on common use cases, please visit our article on Escalation Policies and Schedules.

Notification Behavior

When an incident triggers, we'll attempt to notify responders at the first rule of the escalation policy. If the responder does not acknowledge within the escalation timeout period, it will escalate to the next escalation rule, until a user acknowledges.

Once a user acknowledges the incident, the escalation policy will stop escalating, and PagerDuty will stop sending notifications.

If nobody is on-call in the first rule (due to a coverage gap in a schedule, for example), PagerDuty assigns the incident to the next escalation rule with an on-call responder.

Limits on Escalation Policies

Escalation Rules

You can add up to 20 escalation rules to an escalation policy.

Repeat 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.

Multi-User Notifications

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 on schedules on Digital Operations and Business plans and 5 on Professional and Free plans. This community post addresses best practices about when to notify one user vs. many users.

Escalation Timeouts

With a single target on an escalation rule, the minimum escalation timeout is 1 minute. Alternatively, if there is more than one target in an escalation rule the minimum escalation timeout is 5 minutes. These restrictions are displayed in the web app.

Escalation Policy Changes

An incident follows the escalation policy’s structure as it was when the incident triggered. Changes made to an escalation policy after an incident triggers will not affect any currently open incidents.

🚧

Deleting Users and Schedules

When an incident triggers, PagerDuty records a snapshot of a service's escalation policy and uses this version of the escalation policy throughout the entirety of the incident's lifecycle. This means you will not be able to delete any users or schedules that were on the escalation policy when the incident triggered. If you need to delete such a user or schedule, you have two options:

  1. Resolve any associated incidents.
  2. After making the desired changes to the escalation policy, reassign the incident to the same escalation policy.
    • This will record a new escalation policy snapshot and allow you to delete any users or schedules that were captured in the previous snapshot.

Live Call Routing

If you have Live Call Routing enabled to Connect Directly and there is more than one responder on an escalation rule, PagerDuty will randomly cycle through all responders on that rule. 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 rule can expect to receive notifications via their configured notification methods.

Add an Escalation Policy to a Team

If your account has the Teams feature, you can use escalation policies to connect other core PagerDuty objects to your Teams. When you add an escalation policy to a Team, PagerDuty will assign all of the escalation policy's associated users, schedules and services to that Team. For more information, please check out our Teams article.

On-Call Handoff Notification Settings

On-call hand off notifications (OCHONs) can notify users up to 48 hours before they go on-call, and are configured on a user’s profile. There are a few escalation policy-related items to be aware of to make sure users receive OCHONs:

  • The target user must have on call handoff notifications configured.
  • The user must be a target on the escalation policy.
  • The escalation policy must be set to send OCHONs.
    • If the escalation policy is attached to a service, PagerDuty will automatically send OCHONs. If it is not attached to a service, instructions to turn them on follow:
  1. Navigate to People Escalation Policies click the name of your desired escalation policy click Edit Escalation Policy.
  2. In the Send On-Call Handoff Notifications dropdown, select Always.
  3. Click Save.

When viewing escalation policies in the web app at People Escalation Policies, you can see whether OCHONs are enabled on the right hand side: when in use by a service or always.


Did this page help you?