Trigger Datadog incident (Workflows)

This guide shows how to trigger a Datadog incident directly from Port using a Port workflow.

A workflow chains nodes together, so a single flow can call the Datadog API to open the incident and then reflect it in your software catalog. This replaces the self-service action and GitHub Actions backend used in the Trigger Datadog incident guide, so there is no CI pipeline to maintain.

Common use cases

• Let on-call engineers declare a Datadog incident from Port without leaving the developer portal.
• Standardize incident creation with a consistent title, customer-impact flag, and notification handles.
• Capture each triggered incident as a datadogIncident entity so it appears in your catalog right away.

Prerequisites

1. Complete the onboarding process.
2. Access to your Datadog organization with permissions to create incidents.
3. A Datadog API token with the incident_write permission scope, and a Datadog application key.
4. (Optional) Port's Datadog integration installed, to keep incident data continuously up to date in your catalog.

Set up the data model

If you haven't installed the Datadog integration, you'll need to create a blueprint for Datadog incidents. We highly recommend you install the Datadog integration to have this set up automatically for you.

Create the Datadog 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:

   Datadog Incident Blueprint (Click to expand)

   {
     "identifier": "datadogIncident",
     "description": "This blueprint represents a Datadog incident in our software catalog",
     "title": "Datadog Incident",
     "icon": "Datadog",
     "schema": {
       "properties": {
         "customerImpactScope": {
           "title": "Customer Impact Scope",
           "description": "A summary of the impact customers experienced during the incident.",
           "type": "string"
         },
         "customerImpacted": {
           "title": "Customer Impacted",
           "description": "A flag indicating whether the incident caused customer impact.",
           "type": "boolean",
           "default": false
         },
         "customerImpactStart": {
           "title": "Customer Impact Start",
           "type": "string",
           "description": "Start time of incident affecting customer",
           "format": "date-time"
         },
         "customerImpactEnd": {
           "title": "Customer Impact End",
           "description": "End timestamp of incident affecting customers",
           "type": "string",
           "format": "date-time"
         },
         "created": {
           "title": "Created At",
           "description": "Timestamp of incident creation",
           "type": "string",
           "format": "date-time"
         },
         "updatedAt": {
           "title": "Updated At",
           "description": "Last time incident was updated",
           "type": "string",
           "format": "date-time"
         },
         "customerImpactDuration": {
           "title": "Customer Impact Duration",
           "description": "Duration of customer impact",
           "type": "number"
         },
         "timeToDetect": {
           "title": "Time To Detect",
           "description": "Number of seconds it took to detect incident",
           "type": "number"
         },
         "timeToRepair": {
           "title": "Time To Repair",
           "description": "Number of seconds it took to fix incident",
           "type": "number"
         },
         "severity": {
           "title": "Severity",
           "description": "Severity of incident",
           "type": "string"
         },
         "state": {
           "title": "State",
           "description": "State of the incident",
           "type": "string"
         },
         "createdBy": {
           "title": "Created By",
           "description": "Name of user that created this incident",
           "type": "string"
         }
       }
     },
     "calculationProperties": {},
     "relations": {}
   }

5. Click "Save" to create the blueprint.

Add secrets to Port

Existing secrets

If you have already installed Port's Datadog integration, these secrets should already exist in Port. To view your existing secrets:

1. In your Port application, click on your profile picture .
2. Choose Credentials, then click on the Secrets tab.

To add these secrets to your portal:

1. In your Port application, click on your profile picture .
2. Click on Credentials.
3. Click on the Secrets tab.
4. Click on + Secret and add the following secrets:
   • DD_API_KEY: your Datadog API key.
   • DD_APPLICATION_KEY: your Datadog application key.

Build the workflow

We will build a single workflow with three nodes:

• A self-service trigger that collects the incident details from the user.
• A webhook node that creates the incident through the Datadog API.
• An upsert entity node that records the incident in your catalog.

Follow the steps below to build the workflow:

1. Go to the Workflows page of your portal.

2. Click on the + Workflow button in the top-right corner.

3. Click on the Skip to editor button.

4. Copy and paste the workflow JSON below into the editor to replace the example workflow:

   Trigger Datadog incident workflow JSON (Click to expand)

   Set your Datadog API URL

   Replace <YOUR_DD_API_URL> in the create_incident node with your Datadog API URL. By default this is https://api.datadoghq.com. If you are on the Datadog EU site, use https://api.datadoghq.eu. If you have your region information, use https://api.<region>.datadoghq.com or https://api.<region>.datadoghq.eu.

   {
     "identifier": "trigger_datadog_incident",
     "title": "Trigger Datadog Incident",
     "icon": "Datadog",
     "description": "Trigger a Datadog incident and sync it to the catalog",
     "nodes": [
       {
         "identifier": "trigger",
         "title": "Trigger Datadog Incident",
         "icon": "Datadog",
         "description": "Collect incident details from the user",
         "config": {
           "type": "SELF_SERVE_TRIGGER",
           "userInputs": {
             "properties": {
               "title": {
                 "title": "Title",
                 "description": "The title of the incident, summarizing what happened.",
                 "type": "string"
               },
               "customerImpacted": {
                 "title": "Customer Impacted",
                 "description": "Indicates whether the incident caused customer impact.",
                 "type": "boolean",
                 "default": false
               },
               "customerImpactScope": {
                 "title": "Customer Impact Scope",
                 "description": "Summary of the impact experienced by customers. Required when customers are impacted.",
                 "type": "string"
               },
               "notificationHandleName": {
                 "title": "Notification Handle Name",
                 "description": "The name of the notification handle.",
                 "type": "string"
               },
               "notificationHandleEmail": {
                 "title": "Notification Handle Email",
                 "description": "The email address used for the notification.",
                 "type": "string",
                 "pattern": "^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
               }
             },
             "required": [
               "title",
               "customerImpacted",
               "notificationHandleName",
               "notificationHandleEmail"
             ],
             "order": [
               "title",
               "customerImpacted",
               "customerImpactScope",
               "notificationHandleName",
               "notificationHandleEmail"
             ]
           },
           "published": true
         },
         "variables": {}
       },
       {
         "identifier": "create_incident",
         "title": "Create Datadog Incident",
         "icon": "Datadog",
         "description": "Create the incident through the Datadog API",
         "config": {
           "type": "WEBHOOK",
           "url": "<YOUR_DD_API_URL>/api/v2/incidents",
           "agent": false,
           "synchronized": true,
           "method": "POST",
           "headers": {
             "Content-Type": "application/json",
             "DD-API-KEY": "{{ .secrets[\"DD_API_KEY\"] }}",
             "DD-APPLICATION-KEY": "{{ .secrets[\"DD_APPLICATION_KEY\"] }}"
           },
           "body": {
             "data": {
               "type": "incidents",
               "attributes": {
                 "title": "{{ .outputs.trigger.title }}",
                 "customer_impacted": "{{ .outputs.trigger.customerImpacted }}",
                 "customer_impact_scope": "{{ .outputs.trigger.customerImpactScope }}",
                 "notification_handles": [
                   {
                     "display_name": "{{ .outputs.trigger.notificationHandleName }}",
                     "handle": "{{ .outputs.trigger.notificationHandleEmail }}"
                   }
                 ]
               }
             }
           },
           "onFailure": "terminate"
         },
         "variables": {}
       },
       {
         "identifier": "report_incident",
         "title": "Report Incident to Port",
         "icon": "Datadog",
         "description": "Create or update the incident entity in the catalog",
         "config": {
           "type": "UPSERT_ENTITY",
           "blueprintIdentifier": "datadogIncident",
           "mapping": {
             "identifier": "{{ .outputs.create_incident.response.data.id }}",
             "title": "{{ .outputs.create_incident.response.data.attributes.title }}",
             "properties": {
               "customerImpactScope": "{{ .outputs.create_incident.response.data.attributes.customer_impact_scope }}",
               "severity": "{{ .outputs.create_incident.response.data.attributes.severity }}",
               "state": "{{ .outputs.create_incident.response.data.attributes.state }}",
               "createdBy": "{{ .outputs.create_incident.response.data.attributes.created_by.data.attributes.name }}",
               "created": "{{ .outputs.create_incident.response.data.attributes.created }}"
             }
           },
           "onFailure": "continue"
         },
         "variables": {}
       }
     ],
     "connections": [
       {
         "sourceIdentifier": "trigger",
         "targetIdentifier": "create_incident"
       },
       {
         "sourceIdentifier": "create_incident",
         "targetIdentifier": "report_incident"
       }
     ]
   }

5. Click Save to save the workflow.

Keep incident data fresh

The report_incident node writes the incident's core fields to your catalog immediately. Fields that Datadog populates later, such as impact duration, time to detect, and time to repair, are best kept up to date by installing Port's Datadog integration, which continuously syncs incident data.

Let's test it

1. Head to the Self-service page of your portal.
2. Find the Trigger Datadog Incident workflow and click on it.
3. Fill in the incident details:
   • Title of the incident.
   • Whether customers are impacted.
   • Customer impact scope (when customers are impacted).
   • Notification handle name and email.
4. Click on Execute.
5. Follow the run in the Workflow runs tab and wait for it to complete.
6. Verify that:
   • A new incident appears on your Datadog incidents page.
   • A datadogIncident entity is created in your catalog with the matching title and details.