Trigger Datadog incident (Workflows)

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

Open in ClaudeOpen in CodexOpen in Cursor

Open plan mode if your tool supports it; otherwise present the plan below filled in and wait for my approval. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/trigger-datadog-incident-with-port-workflows

Read the raw markdown version at https://docs.port.io/guides/all/trigger-datadog-incident-with-port-workflows.md - it contains every tab and code block without page markup.

Goal: get the guide's core flow working end-to-end in my org; adapting it to fit my existing setup takes priority over matching the guide 1:1.

Plan:
1. Confirm MCP is connected, in the right org, with sufficient permissions.
2. If the guide offers alternative implementation paths (tabs), pick the one matching my installed integrations and tools, confirm it with me, and implement only that path.
3. Diff the guide's data model (blueprints, properties, relations, workflows, actions, agents, automations, integrations, webhook data sources, secrets) against mine.
4. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
5. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out. If the guide has a "Set up via API" section, use it for anything MCP can't do before treating a step as UI-only.
6. Stop on any blocker and give me options. Approving this plan authorizes the writes it lists; pause only for writes beyond what's listed.

Build:
- Extend blueprint schema additively when upserting; don't remove or overwrite existing properties, and treat type conflicts as a blocker, not an auto-fix.
- Never print secret values into the chat or logs; ask me to set them in Port, or write them via the secrets API without echoing them back.
- List any mock data in the plan, minimal and labeled mock; once approved, seed it without re-asking, and tell me what you seeded.
- For anything the guide writes downstream (e.g. a webhook target), use a real entity, not a mock.
- For pages/widgets, use the real page identifier from the app URL, not a guessed slug.
- When you hit a UI step confirmed (not assumed) unsupported via MCP and not covered by the guide's API sections, pause, give exact clicks, then resume via MCP.
- Validate and give links after each meaningful step (only a tool-returned URL, no guessed paths); don't proceed if the last run wasn't a success.

Done:
- Run the guide's "Let's test it" steps where possible (e.g. execute a workflow test run) and confirm the expected output exists in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

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. Open the Credentials modal.
2. Click on the Secrets tab.

To add these secrets to your portal:

1. Open the Credentials modal.
2. Click on the Secrets tab.
3. 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.