Knowledge BaseIntegrationsAPI DocsCommunityPagerDuty University
Contact SupportMy Support Tickets

Incident Workflows

Create packaged incident response actions

Use Incident Workflows to customize an automated response for every incident. Incident Workflows reduce manual work, standardize your incident response, and they ensure no steps are missed during critical incidents. You can orchestrate your response using if-this-then-that logic to trigger the right set of incident actions for your needs.

🚧

Upgrade to Incident Workflows

  • Because Incident Workflows are a more robust and powerful version of Response Plays, we will be working to upgrade accounts from Response Plays to Incident Workflows, ultimately culminating in a Response Plays end-of-life in late 2023.
  • Please read Upgrade Response Plays to Incident Workflows for details and frequently asked questions about the upgrade process.
2160

Incident Workflow Components

Incident Workflows are comprised of two main components: triggers and actions. By customizing the right set of triggers and actions, you can adjust Workflows for your particular use case.

Triggers

Triggers determine when Incident Workflows should be run, and you can add multiple triggers to each Workflow to customize your preferred response. For example, you can use triggers to create a Workflow that only runs for high-priority incidents. There are three types of triggers: Conditional, Manual and API.

Conditional Triggers

Conditional triggers can start Incident Workflows whenever an incident is created, or only when specific conditions are met.

If you select When an incident is created, you are not required to add a condition. If you do add a condition, though, the condition will be evaluated when the incident is created.

If you select When conditions are met, the condition is evaluated any time there is a change to the incident. This means that workflow could potentially run multiples times. For example, if the condition is priority matches P-1 and a user toggles the priority back and forth between P-1 and P-2, the workflow will trigger each time the incident's priority changes to P-1.

Conditional triggers support the following incident fields:

  • Priority
  • Status
  • Urgency

Manual Triggers

Manual triggers let responders start the Incident Workflow directly from an incident. When a manual trigger is added, Incident Workflows can be triggered from the PagerDuty web app, mobile app, Slack, or Microsoft Teams.

API Triggers

You can trigger workflows using the Incident Workflows REST API endpoint. One of the following user roles is required to trigger workflows via the API:

  • Manager base role
  • Admin
  • Account Owner

Applying Triggers to Services

The last step of creating a trigger is applying it to the right services. There are two ways to apply a trigger to services:

  • Apply a trigger to all services on the account.
  • Apply a trigger to specific services.

Once a trigger has been applied to a service and the Workflow has been published, it can then be used for incidents on those services.

Actions

Every Incident Workflow is made up of a set of actions that define what the Workflow will do. Incident Workflows support the following actions:

Create an Incident Workflow

🚧

Required User Permissions

Account Owners and Global Admins can create and administer all Incident Workflows. Other users can administer workflows and triggers for services where they have Manager access to the service.

  1. Select Automation Incident Workflows from the top navigation bar.
  2. Click Create Workflow.
  3. Add a workflow Name and Description, and click Create.

Add Triggers

  1. Click Add Trigger and select from the following:
Conditional Trigger: Starts an Incident Workflow when an incident in an associated service is created or updated

a. In the section When should this Workflow start? , select When an incident is created or When conditions are met (default) from the dropdown. This selection determines if a Workflow should start on incident creation, or only when the conditions are met.

b. Select the icon to use the Visual Condition Editor, or the icon to use the Advanced PagerDuty Condition Language (PCL) Editor. Note: If you would like to add reference variables to your condition, you must select the PCL Editor.

c. Enter the condition that must be met for the trigger to run. Supported condition fields are Priority, Status and Urgency, though more fields may be added in the future. To add more OR conditions, click New Condition (OR) and repeat this step.

d. In the This trigger applies to dropdown, select whether you would like your condition(s) to apply to All services or Specific services. If you select Specific services, then select your preferred service(s).

e. Click Save.

Manual Trigger: Starts an Incident Workflow when manually updated

a. In the This trigger applies to dropdown, select whether you would like your condition(s) to apply to All services or Specific services. If you select Specific services, then select your preferred service(s).

b. Click Save.

Add Actions

  1. Click Add Action and select from the actions listed below. Note: Actions will trigger in the sequential order that they are added to the Workflow.
Add Conference Bridge

a. Enter the following:

  • Conference Number: The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input.
  • Conference URL: A URL for the conference bridge. This could be a link to a web conference or Slack channel.
    • You may optionally add reference variables in either of the above fields by clicking {+}, or entering {{, and selecting your preferred variable.

b. Click Save.

Add Escalation Policy as Responder

a. Perform the following:

  • Escalation Policy IDs: Select the escalation policy (or policies) to be added from the dropdown.
  • Message (optional): Enter the message to be sent with the request. You may optionally add reference variables to this field by clicking {+}, or entering {{, and selecting your preferred variable.

b. Click Save.

Add Teams as Stakeholders

a. Team IDs: Select the Team(s) to be added from the dropdown.
b. Click Save.

Add Users as Responders

a. Enter the following:

  • Responder User IDs: Select the user(s) to be added from the dropdown.
  • Message (optional): Enter the message to be sent with the request. You may optionally add reference variables to this field by clicking {+}, or entering {{, and selecting your preferred variable.

b. Click Save.

Add Users as Stakeholders

a. User IDs: Select the user(s) to be added from the dropdown.
b. Click Save.

Create a Slack Channel for an Incident

a. Perform the following:

  • Slack Team Name: Select the name of the Slack workspace the channel is in (ex: "PagerDuty").
  • Desired Channel Name (optional): Enter the name of the channel to create in Slack. You may optionally add reference variables to this field by clicking {+}, or entering {{, and selecting your preferred variable. If you do not enter a channel name, it will default to incident_{incident-number}.

b. Click Save.

Create a Zoom Meeting

a. Adds a per-incident Zoom Meeting. Once selected, click Save.

Link a Slack Channel to an Incident

a. Perform the following:

  • Channel Name: Enter the name of the channel to link in Slack (ex: "incident-{{incident.id}}").
  • Channel ID: Enter the in-browser ID of the Slack channel to link. It always starts with "C".
    • You may optionally add reference variables to the above fields by clicking {+}, or entering {{, and selecting your preferred variable.
  • Slack Team Name: Select the name of the Slack workspace the channel is in (ex: "PagerDuty").
  • Channel Privacy: Select the privacy level of the linked channel in Slack.

b. Click Save.

Send Status Update

a. In the Status Update Template dropdown, select Custom Message or a pre-configured Status Update Template. You will see a preview in the Message and Email sections below.

Select Custom Message or Status Update Template

Select Custom Message or Status Update Template

Note: If you select Custom Message, enter a Message to be sent with the request. You may optionally add reference variables to this field by clicking {+}, or entering {{, and selecting your preferred variable.

c. Click Save.


  1. Repeat steps 4-5 until all of the appropriate triggers and actions have been added to the Incident Workflow.
  2. Click Publish in the upper right-hand corner of the page, and then click Publish again in the modal to confirm that the Incident Workflow should be published.

Incident Workflow Drafts

Until an Incident Workflow is published, it exists as a draft. Draft Incident Workflows will not run, even when they have fully configured triggers. If you leave the workflow builder before an Incident Workflow has been published, it will remain in a draft state.

When you edit a published Workflow it creates a draft version, where changes can be safely made without affecting the published version. You can only have one draft at a time. When you publish a draft, it will replace the previous live version.

Edit an Incident Workflow

🚧

Required User Permissions

Account Owners, Global Admins and Managers have access to edit Workflows.

  1. To edit an Incident Workflow as a draft, navigate to Automation Incident Workflows.
  2. Click to the right of the Incident Workflow you would like to edit and select Open in Builder.
    • If the Incident Workflow being edited has already been published, your edits will be applied to a draft Incident Workflow. This allows you to make changes to published Incident Workflows without impacting the Workflow currently being used. When you’re ready to apply those changes, you can re-publish the Workflow to make those changes live.
  3. Make your edits to Triggers, Actions and/or Settings and then click Save.

How Edit Permissions Work for Incident Workflows

You have two options when setting who can edit a workflow: All admins and global managers, or Team managers on a specific team. Editors will also be able to run the workflow via API.

When using Team managers on a specific team, because of how permissions are handled, users on that Team with an Observer or Responder role can also run the workflow via API, though they cannot edit it. Additionally, any user added as a responder to an incident that triggered a workflow, regardless of Team, can also run the workflow via API.

Reference Variables

Reference variables can be used to dynamically insert incident data into your Incident Workflow conditions and actions. During configuration, you may add data such as incident_id, incident.status, incident.priority, etc., to condition and action fields, resulting in the Workflow pulling the corresponding incident’s data each time it is run. This feature allows you to customize and standardize the information, settings, and flow of every response.

Examples

  • Add Users as Responders: When you select this action, you have the option to include a message to responders. You may want to include standard incident data in the Message field, such as {{incident.service.name}} and {{incident.priority}}, so that responders see the service name and priority in the responder request.
  • Send Status Update: When you select this action, you may want to include {{incident.title}} and {{incident.priority}} in the Message field so that stakeholders see the incident’s title and priority in their status updates.
  • Create a Slack Channel for an Incident: When you select this action, you have the option to set a Slack channel name. You may want to include the {{incident.id}} in the Desired Channel Name field to get a unique channel name every time.

Supported Reference Variables

Incident Workflows support reference variables in most trigger condition and action configuration fields. Reference variables use the syntax {{example}}, which are called “double curly braces,” or sometimes "double handlebars".

Field name{{field-name}}
current_date{{current_date}}
time_zone{{time_zone}}
incident.id{{incident.id}}
created_at{{incident.created_at}}
incident.updated_at{{incident.updated_at}}
incident.resolved_at{{incident.resolved_at}}
incident.incident_key{{incident.incident_key}}
incident.incident_number{{incident.incident_number}}
incident.title{{incident.title}}
incident.status{{incident.status}}
incident.urgency{{incident.urgency}}
incident.priority{{incident.priority}}
incident.escalation_policy_id{{incident.escalation_policy_id}}
incident.account_id{{incident.account_id}}
incident.service.id{{incident.service.id}}
incident.service.name{{incident.service.name}}

Run a Workflow

There are two ways to run Workflows:

Manually Run an Incident Workflow

🚧

Required User Permissions

If an Incident Workflow has a manual trigger, any responder can start the Workflow from an incident.

Manually Run a Workflow via Web or Mobile App

  1. In the web or mobile app, click the incident's Title to view its details page, and then click Run a Workflow in the actions menu.
    • In the mobile app you may also tap More and select Run a Workflow.
  2. Select your desired Workflow.
  3. Click Run Workflow.

To configure a manual trigger, follow the instructions in Create an Incident Workflow and select Manual Trigger when you Add Triggers to the Workflow.

Manually Run a Workflow via Slack

Please see our Slack Integration Guide for instructions.

Manually Run a Workflow via Microsoft Teams

Please see our Microsoft Teams Integration Guide for instructions.

Run an Incident Workflow when a Condition is Met

Incident Workflows with conditional triggers will run automatically when their preconfigured conditions are met. To run a Workflow automatically, the Workflow must have a conditional trigger.

To configure a conditional trigger, follow the instructions in Create an Incident Workflow and select Conditional Trigger when you Add Triggers to the Workflow.

View Incident Workflow Audit Trail Reporting

Please read our Audit Trail Reporting article for more information.

FAQ

Why can't I add a trigger to all services?

Expand

Users can only select services that they have edit permissions on. To apply the trigger to a service you don't have edit permissions on, you'll need to request edit permissions on that service.

What happens if I change the trigger in a draft?

Expand

Incident Workflows in a draft state will not trigger under any circumstance. No changes made in a draft will affect live, published Workflows or incidents. Changes will only take effect after publishing.

Why can't I see a specific Incident Workflow in the Run a Workflow dropdown menu?

Expand

To run a Workflow manually, the Workflow must have a manual trigger. From the trigger, you can configure which services to associate with the Workflow.

If a Workflow is not appearing from the Run a Workflow menu on the incident, it is because of one of the following reasons:

  1. The Workflow does not have a manual trigger.
  2. The service or incident is not associated with the Workflow.
  3. The Workflow is associated to the incident, but did not meet the trigger conditions and is not available.

Do Incident Workflow actions run sequentially?

Expand

Yes. The order in which you add actions to an Incident Workflow defines the sequence in which they execute. For example, if you subscribe stakeholders and then send a status update, those stakeholders will be subscribed to the incident before the status update is generated.

Updated 11 days ago