Skip to main content

Check out Port for yourself 

Trigger FireHydrant Incident

Overview​

This guide will help you implement a self-service action in Port that allows you to trigger FireHydrant incidents directly from Port. This functionality streamlines incident management by enabling users to trigger 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 FireHydrant's API through Port, ideal for quick implementation and minimal setup.

Prerequisites​

Set up data model​

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

Create the FireHydrant incident blueprint

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose "Edit JSON".

  4. 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": {}
    }

  5. Click "Save" to create the blueprint.

Create the FireHydrant service blueprint

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose "Edit JSON".

  4. Add this JSON schema:

    FireHydrant Service Blueprint (Click to expand)
    {
      "identifier": "firehydrantService",
      "description": "This blueprint represents a FireHydrant service in our software catalog",
      "title": "FireHydrant Service",
      "icon": "FireHydrant",
      "schema": {
        "properties": {
          "name": {
            "title": "Name",
            "description": "The name of the service in FireHydrant",
            "type": "string"
          },
          "description": {
            "title": "Description",
            "description": "Description of the service",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "description": "Current status of the service",
            "type": "string"
          }
        }
      },
      "calculationProperties": {},
      "relations": {}
    }

  5. Click "Save" to create the blueprint.

Update the service blueprint

You'll need to add a relation to your service blueprint to link it with FireHydrant services:

  1. Go to your Builder page.

  2. Find your service blueprint and click on it.

  3. Click on the {...} button in the top right corner, and choose "Edit JSON".

  4. Add the following relation to the relations object:

    {
      "relations": {
        "fh_service": {
          "title": "FireHydrant Service",
          "target": "firehydrantService",
          "required": false,
          "many": false
        }
      }
    }

  5. Click "Save" to update the blueprint.

Get FireHydrant Condition IDs​

Before implementing the action, you'll need to get the condition IDs that are specific to your FireHydrant organization. You can retrieve these IDs using the FireHydrant API:

curl -X GET "https://api.firehydrant.io/v1/severity_matrix/conditions" \
     -H "Authorization: YOUR_FIREHYDRANT_API_KEY" \
     -H "accept: application/json"

The response will include all available conditions with their IDs. For example:

{
  "data": [
    {
      "id": "b1fc9184-b3f3-4af1-a111-68abcad9bf34",
      "name": "Unavailable",
      "position": 0
    },
    {
      "id": "465a5b4c-6f95-4707-a777-ab4bb8def27d",
      "name": "Degraded",
      "position": 1
    },
    {
      "id": "c2bc11e8-7fcc-428d-9007-26f00700834a",
      "name": "Bug",
      "position": 2
    },
    {
      "id": "9a2a8dbb-6b4e-4189-aca1-e2bb73b9c50b",
      "name": "Operational",
      "position": 3
    }
  ]
}

You'll need these condition IDs for both implementation methods below. Make sure to replace the example IDs with the ones from your API response.

Implementation​

You can trigger 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:

  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:

    • FIREHYDRANT_API_KEY: Your FireHydrant API key

Set up self-service action

We will create a self-service action to handle triggering FireHydrant 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.

    Trigger FireHydrant Incident (Webhook) (Click to expand)
    {
      "identifier": "trigger_an_incident",
      "title": "Trigger an incident",
      "icon": "FireHydrant",
      "description": "Trigger an incident to a FireHydrant service",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {
            "name": {
              "icon": "DefaultProperty",
              "type": "string",
              "title": "Incident name"
            },
            "condition": {
              "icon": "DefaultProperty",
              "title": "Service status",
              "type": "string",
              "enum": [
                "Unavailable",
                "Degraded",
                "Bug",
                "Operational"
              ],
              "enumColors": {
                "Unavailable": "lightGray",
                "Degraded": "lightGray",
                "Bug": "lightGray",
                "Operational": "lightGray"
              }
            },
            "incident_description": {
              "type": "string",
              "title": "Incident description"
            }
          },
          "required": [
            "name",
            "condition"
          ],
          "order": [
            "name",
            "condition",
            "incident_description"
          ]
        },
        "blueprintIdentifier": "service"
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://api.firehydrant.io/v1/incidents",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "RUN_ID": "{{ .run.id }}",
          "Authorization": "{{ .secrets.FIREHYDRANT_API_KEY }}",
          "content-type": "application/json",
          "accept": "application/json"
        },
        "body": {
          "impacts": [
            {
              "type": "service",
              "id": "{{ .entity.relations.fh_service }}",
              "condition_id": "{{ if .inputs.condition == \"Unavailable\" then \"b1fc9184-b3f3-4af1-a111-68abcad9bf34\" elif .inputs.condition == \"Degraded\" then \"465a5b4c-6f95-4707-a777-ab4bb8def27d\" elif .inputs.condition == \"Bug\" then \"c2bc11e8-7fcc-428d-9007-26f00700834a\" elif .inputs.condition == \"Operational\" then \"9a2a8dbb-6b4e-4189-aca1-e2bb73b9c50b\" else null end }}"
            }
          ],
          "name": "{{ .inputs.name }}",
          "description": "{{ .inputs.incident_description }}"
        }
      },
      "requiredApproval": false
    }

  5. Click Save.

Now you should see the Trigger an incident 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 FireHydrant service in Port automation (Click to expand)
    {
      "identifier": "firehydrantIncident_sync_after_trigger",
      "title": "Sync FireHydrant Incident After Trigger",
      "description": "Update FireHydrant incident data in Port after triggering",
      "trigger": {
        "type": "automation",
        "event": {
          "type": "RUN_UPDATED",
          "actionIdentifier": "trigger_an_incident"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.after.status == \"SUCCESS\""
          ],
          "combinator": "and"
        }
      },
      "invocationMethod": {
        "type": "UPSERT_ENTITY",
        "blueprintIdentifier": "firehydrantService",
        "mapping": {
          "identifier": "{{.event.diff.after.response.id}}",
          "title": "{{.event.diff.after.response.name}}",
          "properties": {
            "name": "{{.event.diff.after.response.name}}",
            "description": "{{.event.diff.after.response.description}}",
            "status": "{{.event.diff.after.response.status}}"
          }
        }
      },
      "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 FireHydrant.

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 Trigger FireHydrant Incident.
    • For webhook: Click on Trigger an incident.

  3. Select the service you want to trigger an incident for (make sure it has a FireHydrant service relation)

  4. Fill in the incident details:

    • Name of the incident
    • Service status (Unavailable, Degraded, Bug, or Operational)
    • Incident description (optional)

  5. Click on Execute.

  6. Done! Wait for the incident to be created in FireHydrant.