Skip to main content

Check out Port for yourself 

Escalate an Incident in PagerDuty

Overview​

This guide will help you implement a self-service action in Port that allows you to escalate PagerDuty incidents directly from Port. This functionality streamlines incident management by enabling users to escalate incidents without leaving Port.

You can implement this action in two ways:

  1. GitHub workflow: A more flexible approach that allows for complex workflows and custom logic, suitable for teams that want to maintain their automation in Git.
  2. Synced webhooks: A simpler approach that directly interacts with PagerDuty's API through Port, ideal for quick implementation and minimal setup.

Prerequisites​

  • Complete the onboarding process.

  • Access to your PagerDuty organization with permissions to manage incidents.

  • Optional - Install Port's PagerDuty integration learn more

    PagerDuty Integration

    This step is not required for this example, but it will create all the blueprint boilerplate for you, and also ingest and update the catalog in real time with your PagerDuty Incidents.

Set up data model​

If you haven't installed the PagerDuty integration, you'll need to create blueprints for PagerDuty incidents and PagerDuty services. However, we highly recommend you install the PagerDuty integration to have these automatically set up for you.

Create the PagerDuty incident blueprint

PagerDuty Incident Blueprint
{
  "identifier": "pagerdutyIncident",
  "description": "This blueprint represents a PagerDuty incident in our software catalog",
  "title": "PagerDuty Incident",
  "icon": "pagerduty",
  "schema": {
    "properties": {
      "status": {
        "type": "string",
        "title": "Incident Status",
        "enum": [
          "triggered",
          "annotated",
          "acknowledged",
          "reassigned",
          "escalated",
          "reopened",
          "resolved"
        ]
      },
      "url": {
        "type": "string",
        "format": "url",
        "title": "Incident URL"
      },
      "urgency": {
        "type": "string",
        "title": "Incident Urgency",
        "enum": ["high", "low"]
      },
      "responder": {
        "type": "string",
        "title": "Assignee"
      },
      "escalation_policy": {
        "type": "string",
        "title": "Escalation Policy"
      },
      "created_at": {
        "title": "Create At",
        "type": "string",
        "format": "date-time"
      },
      "updated_at": {
        "title": "Updated At",
        "type": "string",
        "format": "date-time"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "pagerdutyService": {
      "title": "PagerDuty Service",
      "target": "pagerdutyService",
      "required": false,
      "many": true
    }
  }
}

Implementation​

You can escalate PagerDuty incidents by leveraging Port's synced webhooks and secrets to directly interact with the PagerDuty's API. This method simplifies the setup by handling everything within Port.

Add Port secrets

Existing secrets

If you have already installed Port's PagerDuty integration, these secrets should already exist in your portal.
To view your existing secrets:

  1. Click on the ... button in the top right corner of your Port application.
  2. Choose Credentials, then click on the Secrets tab.

To add these secrets to your portal:

  1. Click on the ... button in the top right corner of your Port application.

  2. Click on Credentials.

  3. Click on the Secrets tab.

  4. Click on + Secret and add the following secrets:

    • PAGERDUTY_API_TOKEN: Your PagerDuty API token

    • PAGERDUTY_USER_EMAIL: The email of the PagerDuty user that owns the API token

Set up self-service action

We will create a self-service action to handle escalating PagerDuty incidents using webhooks. To create a self-service action follow these steps:

  1. Head to the self-service page.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the following JSON configuration into the editor.

    Escalation Policy ID

    The escalation policy ID is a unique identifier (e.g., P7LVMYP) that you can find in your PagerDuty dashboard:

    Escalate PagerDuty Incident (Webhook) (Click to expand)
    {
      "identifier": "escalate_incident_webhook",
      "title": "Escalate Incident (Webhook)",
      "icon": "pagerduty",
      "description": "Escalate a PagerDuty incident",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {
            "escalation_policy_id": {
              "title": "Escalation Policy ID",
              "description": "PagerDuty Escalation Policy ID (e.g., P7LVMYP)",
              "icon": "pagerduty",
              "type": "string"
            },
            "urgency": {
              "icon": "pagerduty",
              "title": "Urgency",
              "description": "New urgency level for the incident",
              "type": "string",
              "default": "low",
              "enum": [
                "high",
                "low"
              ],
              "enumColors": {
                "high": "orange",
                "low": "lightGray"
              }
            },
            "from": {
              "icon": "User",
              "title": "From",
              "description": "The email address of a valid PagerDuty user associated with the account making the request.",
              "type": "string",
              "format": "user",
              "default": {
                "jqQuery": ".user.email"
              }
            }
          },
          "required": [
            "escalation_policy_id",
            "urgency",
            "from"
          ],
          "order": [
            "escalation_policy_id",
            "urgency",
            "from"
          ]
        },
        "blueprintIdentifier": "pagerdutyIncident"
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://api.pagerduty.com/incidents/{{.entity.identifier}}",
        "agent": false,
        "synchronized": true,
        "method": "PUT",
        "headers": {
          "Authorization": "Token token={{.secrets.PAGERDUTY_API_TOKEN}}",
          "Accept": "application/vnd.pagerduty+json;version=2",
          "From": "{{.inputs.from}}",
          "Content-Type": "application/json"
        },
        "body": {
          "incident": {
            "type": "incident_reference",
            "escalation_policy": {
              "id": "{{.inputs.escalation_policy_id}}",
              "type": "escalation_policy_reference"
            },
            "urgency": "{{.inputs.urgency}}"
          }
        }
      },
      "requiredApproval": false
    }

  5. Click Save.

Now you should see the Escalate Incident (Webhook) action in the self-service page. 🎉

Create an automation to upsert entity in port

After each execution of the action, we would like to update the relevant entity in Port with the latest status.

To achieve this, we can create an automation that will be triggered when the action completes successfully.

To create the automation:

  1. Head to the automation page.

  2. Click on the + Automation button.

  3. Copy and paste the following JSON configuration into the editor.

    Update PagerDuty incident in Port automation (Click to expand)
        {
          "identifier": "pagerdutyIncident_sync_status",
          "title": "Sync PagerDuty Incident Status",
          "description": "Update PagerDuty incident data in Port after escalation",
          "trigger": {
            "type": "automation",
            "event": {
              "type": "RUN_UPDATED",
              "actionIdentifier": "escalate_incident_webhook"
            },
            "condition": {
              "type": "JQ",
              "expressions": [
                ".diff.after.status == \"SUCCESS\""
              ],
              "combinator": "and"
            }
          },
          "invocationMethod": {
            "type": "UPSERT_ENTITY",
            "blueprintIdentifier": "pagerdutyIncident",
            "mapping": {
              "identifier": "{{.event.diff.after.response.incident.id}}",
              "title": "{{.event.diff.after.response.incident.title}}",
              "properties": {
                "status": "{{.event.diff.after.response.incident.status}}",
                "url": "{{.event.diff.after.response.incident.self}}",
                "urgency": "{{.event.diff.after.response.incident.urgency}}",
                "responder": "{{.event.diff.after.response.incident.assignments.0.assignee.summary}}",
                "escalation_policy": "{{.event.diff.after.response.incident.escalation_policy.summary}}",
                "created_at": "{{.event.diff.after.response.incident.created_at}}",
                "updated_at": "{{.event.diff.after.response.incident.updated_at}}"
              },
              "relations": {
                "pagerdutyService": ["{{.event.diff.after.response.incident.service.id}}"]
              }
            }
          },
          "publish": true
      }

  4. Click Save.

Now when you execute the webhook action, the incident data in Port will be automatically updated with the latest information from PagerDuty.

Let's test it!​

  1. Head to the self-service page of your portal

  2. Choose either the GitHub workflow or webhook implementation:

    • For GitHub workflow: Click on Escalate Incident
    • For webhook: Click on Escalate Incident (Webhook)

  3. Select the PagerDuty incident you want to escalate

  4. Enter the required information:

    • Escalation Policy ID
    • Urgency level (high/low)
    • From (email address of a valid PagerDuty user)

  5. Click on Execute

  6. Done! Wait for the incident to be escalated in PagerDuty

More Self Service PagerDuty Actions Examples​