Manage and visualize your PagerDuty incidents

This guide demonstrates how to bring your incident management experience into Port using PagerDuty.
You will learn how to:

Set up self-service actions to manage incidents (trigger, acknowledge, and resolve).
Build dashboards in Port to monitor and take action on your incident response.

Common use cases

Empower on-call teams to quickly respond to incidents with self-service actions.
Monitor the status and health of all incidents across services from a single dashboard.
Track incident metrics and response times to improve incident management processes.
Get visibility into incident trends and patterns across your organization.

Prerequisites

This guide assumes the following:

You have a Port account and have completed the onboarding process.
Port's PagerDuty integration is installed in your account.
Access to your PagerDuty organization with permissions to manage incidents.

Set up data model

If you haven't installed the PagerDuty integration, you'll need to create blueprints for PagerDuty incidents.
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
    }
  }
}

Set up self-service actions

Now let's set up self-service actions to manage your PagerDuty incidents directly from Port.
We will implement three key incident management workflows using webhook-based actions for simplicity.

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:

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

First, add the required secrets to your portal:

Click on the ... button in the top right corner of your Port application.
Click on Credentials.
Click on the Secrets tab.
Click on + Secret and add the following secrets:
- PAGERDUTY_ROUTING_KEY: Your PagerDuty routing key for the service.
- PAGERDUTY_API_KEY: Your PagerDuty API token.

Multiple services support

If you want to create incidents for multiple PagerDuty services, you can modify the action to use routing key as an input field instead of a secret. This allows you to specify different routing keys for different services when triggering incidents.

To implement this:

Remove PAGERDUTY_ROUTING_KEY from secrets.
Add routing_key as a required input property in the action configuration.
Update the webhook body to use {{.inputs.routing_key}} instead of {{.secrets.PAGERDUTY_ROUTING_KEY}}.

Trigger PagerDuty incidents

Trigger PagerDuty incidents directly from Port when issues are detected.

Head to the self-service page.
Click on the + New Action button.
Click on the {...} Edit JSON button.

Copy and paste the following JSON configuration into the editor:

Trigger PagerDuty incident (click to expand)

{
    "identifier": "trigger_pagerduty_incident",
    "title": "Trigger PagerDuty incident",
    "icon": "pagerduty",
    "description": "Trigger a new PagerDuty incident directly from Port",
    "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
        "properties": {
        "summary": {
            "icon": "DefaultProperty",
            "title": "Summary",
            "type": "string"
        },
        "source": {
            "icon": "DefaultProperty",
            "title": "Source",
            "type": "string",
            "default": "Port"
        },
        "severity": {
            "icon": "DefaultProperty",
            "title": "Severity",
            "type": "string",
            "default": "critical",
            "enum": [
            "critical",
            "error",
            "warning",
            "info"
            ],
            "enumColors": {
            "critical": "red",
            "error": "red",
            "warning": "yellow",
            "info": "blue"
            }
        },
        "event_action": {
            "icon": "DefaultProperty",
            "title": "Event Action",
            "type": "string",
            "default": "trigger",
            "enum": [
            "trigger",
            "acknowledge",
            "resolve"
            ]
        }
        },
        "required": [
        "summary",
        "source",
        "severity",
        "event_action"
        ],
        "order": [
        "summary",
        "source",
        "severity",
        "event_action"
        ]
    },
    "blueprintIdentifier": "pagerdutyIncident"
    },
    "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://events.pagerduty.com/v2/enqueue",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
        "Content-Type": "application/json"
    },
    "body": {
        "payload": {
        "summary": "{{.inputs.summary}}",
        "source": "{{.inputs.source}}",
        "severity": "{{.inputs.severity}}"
        },
        "routing_key": "{{.secrets.PAGERDUTY_ROUTING_KEY}}",
        "event_action": "{{.inputs.event_action}}"
    }
    },
    "requiredApproval": false
}

Click Save.

Create PagerDuty incident trigger automation

Create an automation to update Port when PagerDuty incidents are triggered:

Head to the automation page.
Click on the + Automation button.

Copy and paste the following JSON configuration:

Trigger PagerDuty incident automation (click to expand)

{
  "identifier": "pagerdutyIncident_sync_after_trigger",
  "title": "Sync PagerDuty Incident After Trigger",
  "description": "Update PagerDuty incident data in Port after triggering",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "RUN_UPDATED",
      "actionIdentifier": "trigger_pagerduty_incident"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.after.status == \"SUCCESS\""
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "UPSERT_ENTITY",
    "blueprintIdentifier": "pagerdutyIncident",
    "mapping": {
      "identifier": "{{.event.diff.after.response.dedup_key}}",
      "title": "{{.event.diff.after.properties.summary}}",
      "properties": {
        "status": "triggered",
        "urgency": "high",
        "created_at": "{{.event.diff.after.createdAt}}"
      }
    }
  },
  "publish": true
}

Click Save.

Acknowledge PagerDuty incidents

Acknowledge PagerDuty incidents to signal that someone is working on the issue.

Head to the self-service page.
Click on the + New Action button.
Click on the {...} Edit JSON button.

Copy and paste the following JSON configuration:

Acknowledge PagerDuty incident (click to expand)

{
  "identifier": "acknowledge_pagerduty_incident",
  "title": "Acknowledge PagerDuty incident",
  "icon": "pagerduty",
  "description": "Acknowledge PagerDuty incident directly from Port",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {},
      "required": [],
      "order": []
    },
    "blueprintIdentifier": "pagerdutyIncident"
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://events.pagerduty.com/v2/enqueue",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "routing_key": "{{.secrets.PAGERDUTY_ROUTING_KEY}}",
      "event_action": "acknowledge",
      "dedup_key": "{{.entity.identifier}}"
    }
  },
  "requiredApproval": false
}

Click Save.

Create acknowledge PagerDuty incident automation

Create an automation to update Port when PagerDuty incidents are acknowledged:

Head to the automation page.
Click on the + Automation button.

Copy and paste the following JSON configuration:

Acknowledge PagerDuty incident automation (click to expand)

{
  "identifier": "pagerdutyIncident_sync_acknowledge_status",
  "title": "Sync PagerDuty Incident Status After Acknowledge",
  "description": "Update PagerDuty incident data in Port after acknowledgment",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "RUN_UPDATED",
      "actionIdentifier": "acknowledge_pagerduty_incident"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.after.status == \"SUCCESS\""
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "UPSERT_ENTITY",
    "blueprintIdentifier": "pagerdutyIncident",
    "mapping": {
      "identifier": "{{.event.diff.after.entity.identifier}}",
      "title": "{{ .event.diff.after.entity.title }}",
      "properties": {
        "status": "{{.event.diff.after.response.incidents.0.status}}",
        "url": "{{.event.diff.after.response.incidents.0.self}}",
        "urgency": "{{.event.diff.after.response.incidents.0.urgency}}",
        "responder": "{{.event.diff.after.response.incidents.0.assignments.0.assignee.summary}}",
        "escalation_policy": "{{.event.diff.after.response.incidents.0.escalation_policy.summary}}",
        "created_at": "{{.event.diff.after.response.incidents.0.created_at}}",
        "updated_at": "{{.event.diff.after.response.incidents.0.updated_at}}"
      },
      "relations": {
        "{{.event.diff.after.entity.relations.key}}": "{{.event.diff.after.entity.relations.value}}"
      }
    }
  },
  "publish": true
}

Click Save.

Resolve PagerDuty incidents

Resolve PagerDuty incidents once the underlying issue has been fixed.

Head to the self-service page.
Click on the + New Action button.
Click on the {...} Edit JSON button.

Copy and paste the following JSON configuration:

Resolve PagerDuty incident (click to expand)

{
  "identifier": "resolve_pagerduty_incident",
  "title": "Resolve PagerDuty incident",
  "icon": "pagerduty",
  "description": "Resolve a PagerDuty incident directly from Port",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {},
      "required": [],
      "order": []
    },
    "blueprintIdentifier": "pagerdutyIncident"
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://events.pagerduty.com/v2/enqueue",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "routing_key": "{{.secrets.PAGERDUTY_ROUTING_KEY}}",
      "event_action": "resolve",
      "dedup_key": "{{.entity.identifier}}"
    }
  },
  "requiredApproval": false
}

Click Save.

Create resolve PagerDuty incident automation

Create an automation to update Port when PagerDuty incidents are resolved:

Head to the automation page.
Click on the + Automation button.

Copy and paste the following JSON configuration:

Resolve PagerDuty incident automation (click to expand)

{
    "identifier": "pagerdutyIncident_sync_resolve_status",
    "title": "Sync PagerDuty Incident Status After Resolve",
    "description": "Update PagerDuty incident data in Port after resolution",
    "trigger": {
        "type": "automation",
        "event": {
            "type": "RUN_UPDATED",
            "actionIdentifier": "resolve_pagerduty_incident"
        },
        "condition": {
            "type": "JQ",
            "expressions": [
                ".diff.after.status == \"SUCCESS\""
            ],
            "combinator": "and"
        }
    },
    "invocationMethod": {
        "type": "UPSERT_ENTITY",
        "blueprintIdentifier": "pagerdutyIncident",
        "mapping": {
            "identifier": "{{.event.diff.after.entity.identifier}}",
            "title": "{{.event.diff.after.entity.title}}",
            "properties": {
                "status": "resolved",
                "updated_at": "{{.event.diff.after.endedAt}}"
            }
        }
    },
    "publish": true
}

Click Save.

Let's test it!

Head to the self-service page of your portal
Test triggering a PagerDuty incident:
- Click on Trigger PagerDuty incident
- Fill in the required information:
  - Summary: A description of the PagerDuty incident (e.g., "Database connection timeout").
  - Source: Where the incident originated (default: "Port").
  - Severity: Choose from critical, error, warning, or info.
  - Event Action: Set to "trigger".
- Click Execute
Test acknowledging a PagerDuty incident:
- Navigate to an existing PagerDuty incident in your catalog.
- Click on Acknowledge PagerDuty incident
- Click Execute
Test resolving an incident:
- Navigate to an acknowledged incident in your catalog.
- Click on Resolve PagerDuty incident
- Click Execute

Visualize metrics

With your incident management actions in place and data flowing, we can create a dedicated dashboard in Port to visualize all incidents by status, urgency, or service using customizable widgets.

Create a dashboard

Navigate to the Catalog page of your portal.
Click on the + New button in the left sidebar.
Select New dashboard.
Name the dashboard PagerDuty Incident Management.
Input Monitor and manage your PagerDuty incidents under Description.
Select the PagerDuty icon.
Click Create.

We now have a blank dashboard where we can start adding widgets to visualize insights from our PagerDuty incidents.

Add widgets

In the new dashboard, create the following widgets:

Incidents by status (click to expand)

Click + Widget and select Pie chart.
Title: Incidents by status (add the PagerDuty icon).
Choose the PagerDuty Incident blueprint.
Under Breakdown by property, select the Incident Status property
Click Save

Incidents by urgency (click to expand)

Click + Widget and select Pie chart.
Title: Incidents by urgency (add the PagerDuty icon)
Choose the PagerDuty Incident blueprint.
Under Breakdown by property, select the Incident Urgency property.
Click Save

Open incidents (click to expand)

Click + Widget and select Number Chart.
Title: Open incidents (add the Alert icon)
Select Count entities Chart type and choose PagerDuty Incident as the Blueprint.
Select count for the Function.

Add this JSON to the Additional filters editor to filter open incidents:

[
    {
        "combinator":"and",
        "rules":[
            {
                "property":"status",
                "operator":"in",
                "value":["triggered", "acknowledged"]
            }
        ]
    }
]

Select custom as the Unit and input incidents as the Custom unit.
Click Save

Resolved incidents (click to expand)

Click + Widget and select Number Chart.
Title: Resolved incidents (add the BadgeAlert icon)
Select Count entities Chart type and choose PagerDuty Incident as the Blueprint.
Select count for the Function.

Add this JSON to the Additional filters editor to filter resolved incidents:

[
    {
        "combinator":"and",
        "rules":[
            {
                "property":"status",
                "operator":"=",
                "value":"resolved"
            }
        ]
    }
]

Select custom as the Unit and input incidents as the Custom unit.
Click Save

Critical incidents (click to expand)

Click + Widget and select Number Chart.
Title: Critical incidents (add the Alert icon)
Select Count entities Chart type and choose PagerDuty Incident as the Blueprint.
Select count for the Function.

Add this JSON to the Additional filters editor to filter critical incidents from this month:

[
    {
        "combinator":"and",
        "rules":[
            {
                "property":"urgency",
                "operator":"=",
                "value":"high"
            }
        ]
    }
]

Select custom as the Unit and input incidents as the Custom unit.
Click Save

Average resolution time over time (click to expand)

Click + Widget and select Line Chart.
Title: Average Resolution Time Over Time, (add the LineChart icon)
Select Aggregate Property (All Entities) Chart type and choose PagerDuty Incident as the Blueprint.
Input Resolution Time (hours) as the Y axis Title and choose Time to Recovery as the Property.
Set average as the Function.
Input Months as the X axis Title and choose created_at as the Measure time by.
Set Time Interval to Month and Time Range to In the past 365 days.

Add this JSON to the Additional filters editor to only include resolved incidents:

    {
        "combinator":"and",
        "rules":[
            {
                "property":"status",
                "operator":"=",
                "value":"resolved"
            }
        ]
    }

Click Save

All incidents table (click to expand)

Click + Widget and select Table.
Title the widget All Incidents (add the pagerduty icon)
Choose the PagerDuty Incident blueprint.
Click Save to add the widget to the dashboard.
Click on the ... button in the top right corner of the table and select Customize table.
In the top right corner of the table, click on Manage Properties and add the following properties:
- Incident Status: The current status of the incident.
- Incident Urgency: The urgency level of the incident.
- PagerDuty Service: The name of the related PagerDuty service.
- Assignee: The person assigned to the incident.
- Created At: When the incident was created.
Click on the save icon in the top right corner of the widget to save the customized table.

Trigger a PagerDuty Incident: Complete guide for creating incidents
Acknowledge Incident In PagerDuty: Complete guide for acknowledging incidents
Resolve an Incident in PagerDuty: Complete guide for resolving incidents
Change On-Call User: Change who's on-call for a service
Escalate an incident: Escalate incidents when needed
Create PagerDuty service: Create new PagerDuty services

Common use cases​

Prerequisites​

Set up data model​

Create the PagerDuty incident blueprint

Set up self-service actions​

Add Port secrets​

Multiple services support

Trigger PagerDuty incidents​

Create PagerDuty incident trigger automation

Acknowledge PagerDuty incidents​

Create acknowledge PagerDuty incident automation

Resolve PagerDuty incidents​

Create resolve PagerDuty incident automation

Let's test it!​

Visualize metrics​

Create a dashboard​

Add widgets​

Related guides​

Common use cases

Prerequisites

Set up data model

Set up self-service actions

Add Port secrets

Trigger PagerDuty incidents

Acknowledge PagerDuty incidents

Resolve PagerDuty incidents

Let's test it!

Visualize metrics

Create a dashboard

Add widgets

Related guides