Change the on-call In PagerDuty

Overview

This self service guide provides a comprehensive walkthrough on how to change the on-call in Pagerduty from Port using Port's self service actions.

Prerequisites

1. Port's GitHub app needs to be installed.

2. In your GitHub repository, go to Settings > Secrets and add the following secrets:

   • PAGERDUTY_API_KEY - PagerDuty API token generated by the user.
   • PORT_CLIENT_ID - Your port client id How to get the credentials.
   • PORT_CLIENT_SECRET - Your port client secret How to get the credentials.

3. Optional - Install Port's PagerDuty integration learn more

4. In Case you decided not to install the PagerDuty integration, you will need to create a blueprint for PagerDuty incidents in Port.

PagerDuty Schedule Blueprint (Click to expand)

{
  "identifier": "pagerdutySchedule",
  "description": "This blueprint represents a PagerDuty schedule in our software catalog",
  "title": "PagerDuty Schedule",
  "icon": "pagerduty",
  "schema": {
    "properties": {
      "url": {
        "title": "Schedule URL",
        "type": "string",
        "format": "url"
      },
      "timezone": {
        "title": "Timezone",
        "type": "string"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "users": {
        "title": "Users",
        "type": "array"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

GitHub Workflow

Create the file .github/workflows/change-on-call-user.yaml in the .github/workflows folder of your repository.

tip

We recommend creating a dedicated repository for the workflows that are used by Port actions.

GitHub Workflow Script

change-on-call-user.yaml

name: Change Who is On Call In PagerDuty
on:
  workflow_dispatch:
    inputs:
      start_time:
        description: The start time for the override, in ISO 8601 format (e.g., 2023-01-01T01:00:00Z)
        required: true
        type: string
      end_time:
        description: The end time for the override, in ISO 8601 format (e.g., 2023-01-01T01:00:00Z).
        required: true
        type: string
      new_on_call_user:
        description: The email of the user who will be taking over the on-call duty
        required: true
        type: string
      port_payload:
        required: true
        description: >-
          Port's payload, including details for who triggered the action and
          general context (blueprint, run id, etc...)

jobs:
  change-on-call-user:
    runs-on: ubuntu-latest
    steps:
      
      - name: Inform searching of user in user list
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Searching for user in organization user list... ⛴️"

      - name: Search for user id among user list
        id: search_for_user_id
        uses: fjogeleit/http-request-action@v1
        with:
          url: "https://api.pagerduty.com/users?query=${{ github.event.inputs.new_on_call_user }}"
          method: "GET"
          customHeaders: '{"Content-Type": "application/json", "Authorization": "Token token=${{ secrets.PAGERDUTY_API_KEY }}"}'

      - name: Retrieve user list from search
        id: user_id_from_search
        if: steps.search_for_user_id.outcome == 'success'
        run: |
          user_id=$(echo '${{ steps.search_for_user_id.outputs.response }}' | jq -r '.users | if length > 0 then .[0].id else "empty" end')
          echo "user_id=${user_id}" >> $GITHUB_OUTPUT

      - name: Inform user existence
        if: steps.user_id_from_search.outputs.user_id != 'empty'
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_payload).context.runId }}
          logMessage: |
            User found 🥹, Changing On-Call to ${{ inputs.new_on_call_user }}... ⛴️
      
      - name: Inform user inexistence
        if: steps.user_list_from_search.outputs.selected_user_id == 'empty'
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_payload).context.runId }}
          logMessage: |
            User not found 😭 Skipping assignment... ⛴️
  
      - name: Change Who is On-Call in PagerDuty
        if: steps.user_id_from_search.outputs.user_id != 'empty'
        id: change_on_call_user
        uses: fjogeleit/http-request-action@v1
        with:
          url: "https://api.pagerduty.com/schedules/${{fromJson(github.event.inputs.port_payload).context.entity}}/overrides"
          method: 'POST'
          customHeaders: '{"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token token=${{ secrets.PAGERDUTY_API_KEY }}"}'
          data: >-
            {
              "overrides": [
                {
                  "start": "${{ github.event.inputs.start_time }}",
                  "end": "${{ github.event.inputs.end_time }}",
                  "user": {
                    "id": "${{ steps.user_id_from_search.outputs.user_id }}",
                    "type": "user_reference" 
                  },
                  "time_zone": "UTC"
                }
              ]
            }

      - name: Log Before Requesting for Updated Schedule
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Getting updated schedule from pagerduty ..."

      - name: Request For Changed Schedule
        id: new_schedule
        uses: fjogeleit/http-request-action@v1
        with:
          url: 'https://api.pagerduty.com/schedules/${{fromJson(github.event.inputs.port_payload).context.entity}}'
          method: 'GET'
          customHeaders: '{"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token token=${{ secrets.PAGERDUTY_API_KEY }}"}'

      - name: Extract Users From New Schedule
        id: extract_users
        run: |
          USERS_JSON=$(echo '${{ steps.new_schedule.outputs.response }}' | jq -c '[.schedule.users[].summary]')
          echo "user_summaries=$USERS_JSON" >> $GITHUB_ENV
        shell: bash
  
      - name: Log Before Upserting Schedule to Port
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Ingesting updated schedule to port..."
          
      - name: UPSERT Entity
        uses: port-labs/port-github-action@v1
        with:
          identifier: "${{ fromJson(steps.new_schedule.outputs.response).schedule.id }}"
          title: "${{ fromJson(steps.new_schedule.outputs.response).schedule.name }}"
          blueprint: ${{fromJson(github.event.inputs.port_payload).context.blueprint}}
          properties: |-
            {
              "url": "${{ fromJson(steps.new_schedule.outputs.response).schedule.html_url }}",
              "timezone": "${{ fromJson(steps.new_schedule.outputs.response).schedule.time_zone }}",
              "description": "${{ fromJson(steps.new_schedule.outputs.response).schedule.description}}",
              "users": ${{ env.user_summaries }}
            }
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: UPSERT
          runId: ${{ fromJson(inputs.port_payload).context.runId }}

      - name: Log After Upserting Entity
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Entity upserting was successful ✅"

Port Configuration

Create a new self service action using the following JSON configuration.

Change On-Call User In PagerDuty (click to expand)

Modification Required

Make sure to replace <GITHUB_ORG> and <GITHUB_REPO> with your GitHub organization and repository names respectively.

{
  "identifier": "pagerdutyIncident_change_on_call_user",
  "title": "Change On-Call User",
  "icon": "pagerduty",
  "description": "Change who is on call in pagerduty",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "start_time": {
          "type": "string",
          "title": "Start Time",
          "description": "The start time for the override, in ISO 8601 format (e.g., 2023-01-01T01:00:00Z)",
          "icon": "pagerduty",
          "format": "date-time"
        },
        "end_time": {
          "title": "End Time",
          "description": "The end time for the override, in ISO 8601 format (e.g., 2023-01-01T01:00:00Z).",
          "icon": "pagerduty",
          "type": "string",
          "format": "date-time"
        },
        "new_on_call_user": {
          "icon": "User",
          "description": "The ID of the user who will be taking over the on-call duty",
          "title": "On Call User Id",
          "type": "string",
          "format": "user"
        }
      },
      "required": [
        "start_time",
        "end_time",
        "new_on_call_user"
      ],
      "order": [
        "start_time",
        "end_time",
        "new_on_call_user"
      ]
    },
    "blueprintIdentifier": "pagerdutyIncident"
  },
  "invocationMethod": {
    "type": "GITHUB",
    "org": "<GITHUB_ORG>",
    "repo": "<GITHUB_REPO>",
    "workflow": "change-incident-owner.yaml",
    "workflowInputs": {
      "{{if (.inputs | has(\"ref\")) then \"ref\" else null end}}": "{{.inputs.\"ref\"}}",
      "{{if (.inputs | has(\"start_time\")) then \"start_time\" else null end}}": "{{.inputs.\"start_time\"}}",
      "{{if (.inputs | has(\"end_time\")) then \"end_time\" else null end}}": "{{.inputs.\"end_time\"}}",
      "{{if (.inputs | has(\"new_on_call_user\")) then \"new_on_call_user\" else null end}}": "{{.inputs.\"new_on_call_user\"}}",
      "port_payload": {
        "action": "{{ .action.identifier[(\"pagerdutyIncident_\" | length):] }}",
        "resourceType": "run",
        "status": "TRIGGERED",
        "trigger": "{{ .trigger | {by, origin, at} }}",
        "context": {
          "entity": "{{.entity.identifier}}",
          "blueprint": "{{.action.blueprint}}",
          "runId": "{{.run.id}}"
        },
        "payload": {
          "entity": "{{ (if .entity == {} then null else .entity end) }}",
          "action": {
            "invocationMethod": {
              "type": "GITHUB",
              "org": "<GITHUB_ORG>",
              "repo": "<GITHUB_REPO>",
              "workflow": "change-incident-owner.yaml",
              "omitUserInputs": false,
              "omitPayload": false,
              "reportWorkflowStatus": true
            },
            "trigger": "{{.trigger.operation}}"
          },
          "properties": {
            "{{if (.inputs | has(\"start_time\")) then \"start_time\" else null end}}": "{{.inputs.\"start_time\"}}",
            "{{if (.inputs | has(\"end_time\")) then \"end_time\" else null end}}": "{{.inputs.\"end_time\"}}",
            "{{if (.inputs | has(\"new_on_call_user\")) then \"new_on_call_user\" else null end}}": "{{.inputs.\"new_on_call_user\"}}"
          },
          "censoredProperties": "{{.action.encryptedProperties}}"
        }
      }
    },
    "reportWorkflowStatus": true
  },
  "requiredApproval": false,
  "publish": true
}

Now you should see the Change On-Call User action in the self-service page. 🎉

Let's test it!

1. Head to the Self Service hub
2. Click on the Change On-Call User action
3. Choose the jira ticket you want to change the status and assignee for (In case you didn't install the PagerDuty integration, it means you don't have any PagerDuty incidents in Port yet, so you will need to create one manually in Port to test this action)
4. Select the new incident
5. Enter the required details for Start Date, End Date and On-Call User in their respective fields.
6. Click on Execute
7. Done! wait for the incident's status to be changed in PagerDuty

Congrats 🎉 You've changed the PagerDuty on-call user in Port.

More Self Service PagerDuty Actions Examples

• Acknowledge Incident
• Change PagerDuty incident owner
• Create PagerDuty incident
• Create PagerDuty service
• Escalate an incident
• Resolve an incident
• Trigger PagerDuty incident