Create a FireHydrant Incident

Overview

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

You can implement this action in two ways:

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.
Synced webhooks: A simpler approach that directly interacts with FireHydrant's API through Port, ideal for quick implementation and minimal setup.

Prerequisites

Complete the onboarding process.
Access to your FireHydrant organization with permissions to manage incidents.
Optional - Install Port's FireHydrant integration.

Set up data model

If you haven't installed the FireHydrant integration, you will need to manually create a blueprint for FireHydrant incidents.
We highly recommend that you install the FireHydrant integration to have such resources automatically set up for you.

Create the FireHydrant incident blueprint

Go to your Builder page.
Click on + Blueprint.
Click on the {...} button in the top right corner, and choose "Edit JSON".

Add this JSON schema:

FireHydrant Incident Blueprint (Click to expand)

{
"identifier": "firehydrantIncident",
"description": "This blueprint represents a firehydrant incident",
"title": "FireHydrant Incident",
"icon": "FireHydrant",
"schema": {
    "properties": {
    "url": {
        "type": "string",
        "title": "Incident URL",
        "format": "url",
        "description": "the link to the incident"
    },
    "priority": {
        "title": "Priority",
        "type": "string",
        "enum": [
        "P1",
        "P2",
        "P3",
        "P4"
        ],
        "enumColors": {
        "P1": "red",
        "P2": "red",
        "P3": "orange",
        "P4": "orange"
        }
    },
    "severity": {
        "title": "Severity",
        "type": "string"
    },
    "tags": {
        "title": "Tags",
        "items": {
        "type": "string"
        },
        "type": "array"
    },
    "currentMilestone": {
        "type": "string",
        "title": "Current Milestone",
        "default": "started",
        "enum": [
        "started",
        "detected",
        "acknowledged",
        "investigating",
        "identified",
        "mitigated",
        "resolved",
        "postmortem_started",
        "postmortem_completed",
        "closed"
        ],
        "enumColors": {
        "started": "red",
        "detected": "red",
        "acknowledged": "orange",
        "investigating": "yellow",
        "identified": "yellow",
        "mitigated": "green",
        "resolved": "green",
        "postmortem_started": "purple",
        "postmortem_completed": "blue",
        "closed": "green"
        }
    },
    "functionalities": {
        "title": "Functionalities Impacted",
        "items": {
        "type": "string"
        },
        "type": "array"
    },
    "customerImpact": {
        "title": "Customers Impacted",
        "type": "string"
    },
    "createdBy": {
        "title": "Created By",
        "type": "string"
    },
    "createdAt": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
    },
    "description": {
        "title": "Description",
        "type": "string"
    }
    },
    "required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {}
}

Click "Save" to create the blueprint.

Implementation

Synced webhook
GitHub workflow

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

Add Port secrets

Existing secrets

If you have already installed Port's FireHydrant 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.

To add these 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:
- FIREHYDRANT_API_KEY: Your FireHydrant API key

Set up self-service action

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

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.

Create FireHydrant Incident (Webhook) (Click to expand)

{
"identifier": "create_firehydrant_incident_webhook",
"title": "Create FireHydrant Incident (Webhook)",
"icon": "FireHydrant",
"description": "Create a new FireHydrant incident",
"trigger": {
    "type": "self-service",
    "operation": "CREATE",
    "userInputs": {
    "properties": {
        "name": {
        "type": "string",
        "title": "Name",
        "description": "The name or title of the incident"
        },
        "priority": {
        "icon": "DefaultProperty",
        "title": "Priority",
        "type": "string",
        "enum": [
            "P1",
            "P2",
            "P3",
            "P4"
        ],
        "enumColors": {
            "P1": "red",
            "P2": "orange",
            "P3": "blue",
            "P4": "darkGray"
        }
        },
        "description": {
        "type": "string",
        "title": "Description",
        "description": "Detailed description about the incident"
        }
    },
    "required": [],
    "order": [
        "name",
        "description",
        "priority"
    ]
    }
},
"invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.firehydrant.io/v1/incidents",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
    "Authorization": "{{.secrets.FIREHYDRANT_API_KEY}}",
    "Content-Type": "application/json"
    },
    "body": {
    "name": "{{.inputs.name}}",
    "priority": "{{.inputs.priority}}",
    "description": "{{.inputs.description}}"
    }
},
"requiredApproval": false
}

Click Save.

Now you should see the Create FireHydrant 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:

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

Copy and paste the following JSON configuration into the editor.

Update FireHydrant incident in Port automation (Click to expand)

    {
    "identifier": "firehydrant_incident_sync_status",
    "title": "Sync FireHydrant Incident Status",
    "description": "Update FireHydrant incident data in Port after creation",
    "trigger": {
        "type": "automation",
        "event": {
        "type": "RUN_UPDATED",
        "actionIdentifier": "create_firehydrant_incident_webhook"
        },
        "condition": {
        "type": "JQ",
        "expressions": [
            ".diff.after.status == \"SUCCESS\""
        ],
        "combinator": "and"
        }
    },
    "invocationMethod": {
        "type": "UPSERT_ENTITY",
        "blueprintIdentifier": "firehydrantIncident",
        "mapping": {
        "identifier": "{{.event.diff.after.response.id}}",
        "title": "{{.event.diff.after.response.name}}",
        "properties": {
            "url": "{{.event.diff.after.response.incident_url}}",
            "priority": "{{.event.diff.after.response.priority}}",
            "severity": "{{.event.diff.after.response.severity}}",
            "tags": "{{.event.diff.after.response.tag_list}}",
            "currentMilestone": "{{.event.diff.after.response.current_milestone}}",
            "description": "{{.event.diff.after.response.description}}",
            "customerImpact": "{{.event.diff.after.response.customers_impacted}}",
            "createdBy": "{{.event.diff.after.response.created_by.name}}",
            "createdAt": "{{.event.diff.after.response.created_at}}"
        },
        "relations": {}
        }
    },
    "publish": true
    }

Click Save.

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

To implement this use-case using a GitHub workflow, follow these steps:

Add GitHub secrets

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

FIREHYDRANT_API_KEY - Your FireHydrant API key. Follow the FireHydrant documentation to generate your key.
PORT_CLIENT_ID - Your port client id How to get the credentials.
PORT_CLIENT_SECRET - Your port client secret How to get the credentials.

Add GitHub workflow

Create the file .github/workflows/create-firehydrant-incident.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 (Click to expand)

  name: Create FireHydrant Incident

  on:
  workflow_dispatch:
      inputs:
      name:
          description: The name or title of the incident
          required: true
          type: string
      priority:
          description: New priority level for the incident (e.g., P1)
          required: true
          type: string
      description:
          description: The detailed description of the incident
          required: false
          type: string
      port_context:
          required: true
          description: includes blueprint, run ID, and entity identifier from Port.

  jobs:
  trigger-incident:
      runs-on: ubuntu-latest
      steps:
      - name: Inform execution of request to trigger incident
          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(inputs.port_context).run_id}}
          logMessage: "About to trigger an incident in FireHydrant..."

      - name: Trigger Incident in FireHydrant
          id: trigger_incident
          uses: fjogeleit/http-request-action@v1
          with:
          url: 'https://api.firehydrant.io/v1/incidents'
          method: 'POST'
          customHeaders: '{"Content-Type": "application/json", "Authorization": "${{ secrets.FIREHYDRANT_API_KEY }}"}'
          data: >-
              {
                  "name": "${{ github.event.inputs.name }}",
                  "description": "${{ github.event.inputs.description }}",
                  "priority": "${{ github.event.inputs.priority }}"
              }

      - name: Inform Port of FireHydrant failure request
          if: failure()
          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(inputs.port_context).run_id}}
          logMessage: "Request to trigger FireHydrant incident failed ..."

      - name: Inform Port of successful FireHydrant incident creation
          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(inputs.port_context).run_id}}
          logMessage: "Incident successfully created in FireHydrant. Upserting the response entity in Port..."

      - name: Upsert FireHydrant entity to Port 
          id: upsert_entity
          uses: port-labs/port-github-action@v1
          with:
          identifier: "${{ fromJson(steps.trigger_incident.outputs.response).id }}"
          title: "${{ fromJson(steps.trigger_incident.outputs.response).name }}"
          blueprint: "firehydrantIncident"
          properties: |-
              {
              "url": "${{ fromJson(steps.trigger_incident.outputs.response).incident_url }}",
              "priority": "${{ fromJson(steps.trigger_incident.outputs.response).priority }}",
              "severity": "${{ fromJson(steps.trigger_incident.outputs.response).severity }}",
              "tags": "${{ fromJson(steps.trigger_incident.outputs.response).tag_list}}",
              "currentMilestone": "${{ fromJson(steps.trigger_incident.outputs.response).current_milestone }}",
              "description": "${{ fromJson(steps.trigger_incident.outputs.response).description}}",
              "customerImpact": "${{ fromJson(steps.trigger_incident.outputs.response).customers_impacted }}",
              "createdBy": "${{ fromJson(steps.trigger_incident.outputs.response).created_by.name }}",
              "createdAt": "${{ fromJson(steps.trigger_incident.outputs.response).created_at }}"
              }
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: UPSERT
          runId: ${{fromJson(inputs.port_context).run_id}}

      - name: Inform Entity upsert failure
          if: steps.upsert_entity.outcome == 'failure'
          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(inputs.port_context).run_id}}
          logMessage: "Failed to report the created incident back to Port ..."

      - name: Inform completion of FireHydrant incident creation
          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(inputs.port_context).run_id}}
          logMessage: "Incident creation process was successful ✅"

Set up self-service action

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

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.

Escalate FireHydrant Incident (Click to expand)

Modification Required

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

  {
  "identifier": "create_firehydrant_incident",
  "title": "Create FireHydrant Incident",
  "icon": "FireHydrant",
  "description": "Create a new FireHydrant incident",
  "trigger": {
      "type": "self-service",
      "operation": "CREATE",
      "userInputs": {
      "properties": {
          "name": {
          "type": "string",
          "title": "Name",
          "description": "The name or title of the incident"
          },
          "description": {
          "type": "string",
          "title": "Description",
          "description": "Detailed description of the incident"
          },
          "priority": {
          "type": "string",
          "title": "Priority",
          "enum": [
              "P1",
              "P2",
              "P3",
              "P4"
          ],
          "enumColors": {
              "P1": "red",
              "P2": "orange",
              "P3": "blue",
              "P4": "lightGray"
          }
          }
      },
      "required": [],
      "order": [
          "name",
          "description"
      ]
      }
  },
  "invocationMethod": {
      "type": "GITHUB",
      "org": "<GITHUB_ORG>",
      "repo": "<GITHUB_REPO>",
      "workflow": "create-firehydrant-incident.yaml",
      "workflowInputs": {
      "{{ spreadValue() }}": "{{ .inputs }}",
      "port_context": {
          "run_id": "{{ .run.id }}"
      }
      },
      "reportWorkflowStatus": true
  },
  "requiredApproval": false
  }

Click Save.

Now you should see the Create FireHydrant Incident action in the self-service page. 🎉

Let's test it!

Head to the self-service page of your portal.
Choose either the GitHub workflow or webhook implementation:
- For GitHub workflow: Click on Create FireHydrant Incident.
- For webhook: Click on Create FireHydrant Incident (Webhook).
Enter the required information:
- Incident name.
- Description of the incident.
- Priority level (from P1 to P4).
Click on Execute.
Done! Wait for the incident to be created in FireHydrant.

Overview​

Prerequisites​

Set up data model​

Create the FireHydrant incident blueprint

Implementation​

Add Port secrets

Set up self-service action

Create an automation to upsert entity in port

Add GitHub secrets

Add GitHub workflow

Set up self-service action

Let's test it!​

Overview

Prerequisites

Set up data model

Implementation

Let's test it!