Create an incident.io Incident

Overview

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

Prerequisites

Complete the onboarding process.
Access to your incident.io organization with permissions to manage incidents.

Set up data model

You will need to manually create a blueprint for the incident.io incidents.

Create an incident.io 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:

Incident.io Incident Blueprint (Click to expand)

{
"identifier": "incidentIOIncident",
"description": "This blueprint represents an incident.io incident",
"title": "Incident.io Incident",
"icon": "Alert",
"schema": {
    "properties": {
    "url": {
        "type": "string",
        "title": "Incident URL",
        "format": "url"
    },
    "severity": {
        "title": "Severity",
        "type": "string"
    },
    "createdBy": {
        "title": "Created By",
        "type": "string"
    },
    "createdAt": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
    },
    "description": {
        "title": "Description",
        "type": "string"
    },
    "visibility": {
        "type": "string",
        "title": "Visibility",
        "enum": [
        "public",
        "private"
        ],
        "enumColors": {
        "public": "darkGray",
        "private": "darkGray"
        }
    },
    "status": {
        "type": "string",
        "title": "Status",
        "enum": [
        "Investigating",
        "Fixing",
        "Monitoring",
        "Closed",
        "Resolved",
        "Merged"
        ],
        "enumColors": {
        "Investigating": "red",
        "Fixing": "yellow",
        "Monitoring": "purple",
        "Closed": "darkGray",
        "Resolved": "green",
        "Merged": "green"
        }
    }
    },
    "required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {}
}

Click "Save" to create the blueprint.

Implementation

You can create incident.io incidents by leveraging Port's synced webhooks and secrets to directly interact with incident.io's API.

Add Port secrets

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:
- INCIDENT_IO_API_KEY: Your incident.io API key.

Set up self-service action

Let's define a self-service action that is used to create an incident.io incident:

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 incident.io Incident (Webhook) (Click to expand)

{
"identifier": "create_incident_io_incident_webhook",
"title": "Create incident.io Incident (Webhook)",
"icon": "Alert",
"description": "Create a new incident.io incident",
"trigger": {
    "type": "self-service",
    "operation": "CREATE",
    "userInputs": {
    "properties": {
        "name": {
        "type": "string",
        "title": "Name",
        "description": "The name or title of the incident"
        },
        "severity": {
        "icon": "DefaultProperty",
        "title": "Severity",
        "type": "string",
        "enum": [
            "Minor",
            "Major",
            "Critical"
        ],
        "enumColors": {
            "Minor": "blue",
            "Major": "orange",
            "Critical": "red"
        }
        },
        "description": {
        "type": "string",
        "title": "Description",
        "description": "Detailed description about the incident"
        },
        "visibility": {
        "type": "string",
        "title": "Visibility",
        "enum": [
            "public",
            "private"
        ],
        "enumColors": {
            "public": "turquoise",
            "private": "red"
        }
        }
    },
    "required": ["name", "severity", "visibility"],
    "order": [
        "name",
        "description",
        "severity",
        "visibility"
    ]
    }
},
"invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.incident.io/v2/incidents",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
    "Authorization": "Bearer {{.secrets.INCIDENT_IO_API_KEY}}",
    "Content-Type": "application/json"
    },
    "body": {
    "name": "{{.inputs.name}}",
    "severity_id": "{{ if .inputs.severity == \"Minor\" then \"01J53A3A1FNEEQKFGSDKETN6DJ\" elif .inputs.severity == \"Major\" then \"01J53A3A1F2RCGSQQQNA6NJ5CY\" elif .inputs.severity == \"Critical\" then \"01J53A3A1FGWNRNK1TMK9CWJJW\" else \"01J53A3A1FNEEQKFGSDKETN6DJ\" end }}",
    "summary": "{{.inputs.description}}",
    "visibility": "{{.inputs.visibility}}",
    "idempotency_key": "{{ now | tostring | @base64 }}"
    }
},
"requiredApproval": false
}

Extending Incident Severity Levels

By default, incident.io provides three severity levels: Minor, Major, and Critical. However, your organization may have additional severity levels. To include them, use the List Severity API to fetch all available severity levels. Then, update the severity_id values in the request body to match the correct IDs from the API response.

Click Save.

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

Create an automation to update your catalog

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 incident.io incident in Port automation (Click to expand)

{
"identifier": "incident_io_incident_sync_status",
"title": "Sync incident.io Incident Status",
"description": "Update incident.io incident data in Port after creation",
"trigger": {
    "type": "automation",
    "event": {
    "type": "RUN_UPDATED",
    "actionIdentifier": "create_incident_io_incident_webhook"
    },
    "condition": {
    "type": "JQ",
    "expressions": [
        ".diff.after.status == \"SUCCESS\""
    ],
    "combinator": "and"
    }
},
"invocationMethod": {
    "type": "UPSERT_ENTITY",
    "blueprintIdentifier": "incidentIOIncident",
    "mapping": {
    "identifier": "{{.event.diff.after.response.incident.id}}",
    "title": "{{.event.diff.after.response.incident.name}}",
    "properties": {
        "url": "{{.event.diff.after.response.incident.permalink}}",
        "status": "{{.event.diff.after.response.incident.incident_status.name}}",
        "severity": "{{.event.diff.after.response.incident.severity.name}}",
        "visibility": "{{.event.diff.after.response.incident.visibility}}",
        "description": "{{.event.diff.after.response.incident.summary}}",
        "createdBy": "{{.event.diff.after.response.incident.creator.api_key.name}}",
        "createdAt": "{{.event.diff.after.response.incident.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 incident.io.

Let's test it!

Head to the self-service page of your portal.
Choose the Create incident.io Incident (Webhook) action:
Enter the required information:
- Incident name.
- Description of the incident.
- Severity level.
- Visibility.
Click on Execute.
Done! Wait for the incident to be created in incident.io.

Overview​

Prerequisites​

Set up data model​

Create an incident.io incident blueprint​

Implementation​

Add Port secrets​

Set up self-service action​

Create an automation to update your catalog​

Let's test it!​