Managing Dynatrace Automation Workflows as Code with dtctl and GitHub Copilot

Georgi_V — Wed, 05 Aug 2026 00:14:08 GMT

Managing Dynatrace Automation Workflows as Code with dtctl and GitHub Copilot

Infrastructure as Code for Dynatrace Workflows — a field guide from the trenches

Why Workflows as Code?

Dynatrace Automation Workflows are powerful — but clicking through the UI to build and maintain them doesn't scale. Once you have more than a handful of workflows, you want:

Version control — know who changed what and when
Reproducibility — deploy the same workflow reliably, every time
Code review — catch logic errors before they hit production
Copilot assistance — let AI help you author complex JavaScript tasks and DQL queries

This guide walks through the full cycle: using dtctl (the Dynatrace CLI) together with GitHub Copilot to author, deploy, and version-control Dynatrace Workflows as YAML files.

Prerequisites

dtctl installed and configured (~/.config/dtctl/config) with a valid context pointing to your Dynatrace environment
A Git repository to store your workflow YAML files
GitHub Copilot active in VS Code

Verify your context is working:

dtctl get workflows | head -5

The Workflow Cycle

Copilot generates YAML → dtctl apply → test in DT UI → git commit → PR

Simple. Let's walk through each step.

Step 1 — Export an Existing Workflow as a Reference

Before writing from scratch, export a working workflow to understand the schema:

# List all workflows
dtctl get workflows

# Export a specific workflow to YAML
dtctl get workflow <workflow-id> -o yaml

The exported YAML is the ground truth for the API schema. Use it as a starting point and ask Copilot to adapt it to your use case. Any workflows already living in your repo are equally good templates.

Step 2 — Author a New Workflow with Copilot

When prompting Copilot, be specific about three things:

Trigger type: davis-problem, davis-event, or schedule
Tasks: JavaScript logic, DQL queries, ServiceNow calls, email notifications
Conditions: when tasks should run or be skipped

Here are the three trigger types with correct YAML structures — including some non-obvious gotchas I hit along the way.

Davis Problem trigger

trigger:
  eventTrigger:
    filterQuery: >-
      event.kind == "DAVIS_PROBLEM" AND event.status == "ACTIVE"
      AND matchesValue(event.status_transition, {"CREATED", "UPDATED", "REOPENED"})
      AND matchesPhrase(affected_entity_names, "MY_HOST")
    isActive: true
    triggerConfiguration:
      type: davis-problem
      value:
        analysisReady: false
        categories:
          custom: true
        customFilter: 'matchesPhrase(affected_entity_names, "MY_HOST")'
        entityTags: {}
        entityTagsMatch: "all"
        onProblemClose: false
        problemOpenDuration: null
        severityThreshold: null
        triggerOn: null
        triggerOnUpdateFields: []
    uniqueExpression: '{{ event()["event.id"] }}-{{ "open" if event()["event.status"] == "ACTIVE" else "resolved" }}-{{ event()["dt.davis.last_reopen_timestamp"] }}'

Davis Event trigger (e.g. PGI_CRASHED_INFO)

trigger:
  eventTrigger:
    filterQuery: >-
      event.type == "PGI_CRASHED_INFO"
      AND matchesPhrase(event.description, "MyProcess")
      AND dt.entity.host == "HOST-XXXXXXXXXXXXXXXX"
    isActive: true
    triggerConfiguration:
      type: davis-event
      value:
        entityTags: {}
        entityTagsMatch: "all"
        customFilter: 'event.type == "PGI_CRASHED_INFO" AND matchesPhrase(event.description, "MyProcess")'
    uniqueExpression: '{{ event()["event.id"] }}-{{ event()["event.start"] }}'

Gotcha: For davis-event, the value object only accepts entityTags, entityTagsMatch, and customFilter. Fields like eventName, problemState, and eventTypes are not valid and will cause a 400 error. Copilot sometimes generates these — always validate with dtctl apply --debug.

Schedule (CRON) trigger

trigger:
  schedule:
    filterParameters: {}
    inputs: {}
    isActive: true
    nextExecution: null
    rule: null
    timezone: America/Toronto
    trigger:
      type: cron
      cron: "5 20 * * 0"   # Sunday 20:05 local time

Gotcha: The cron expression goes in the nested trigger.cron field — not in rule. The rule field must be null or a valid UUID. Setting it to a cron string causes a 400 error.

A Complete Workflow Example

Here's a full, deployable workflow that ties everything together. It listens for a process crash event, suppresses the alert during a known maintenance window, then creates a ServiceNow incident via a shared workflow.

title: HealthCheck - MyService - Process Crash Alert - MYSERVER01
isDeployed: true
description: >
  Creates a ServiceNow incident when MyService.exe crashes on MYSERVER01.
  Suppresses alerting during the Sunday 20:00-20:05 scheduled maintenance window.
actor: <your-actor-id>
owner: <your-owner-id>
ownerType: USER
isPrivate: false
schemaVersion: 4
trigger:
  eventTrigger:
    filterQuery: >-
      event.type == "PGI_CRASHED_INFO"
      AND matchesPhrase(event.description, "MyService")
      AND dt.entity.host == "HOST-XXXXXXXXXXXXXXXX"
    isActive: true
    triggerConfiguration:
      type: davis-event
      value:
        entityTags: {}
        entityTagsMatch: "all"
        customFilter: 'event.type == "PGI_CRASHED_INFO" AND matchesPhrase(event.description, "MyService") AND dt.entity.host == "HOST-XXXXXXXXXXXXXXXX"'
    uniqueExpression: '{{ event()["event.id"] }}-{{ event()["event.start"] }}'
type: STANDARD
hourlyExecutionLimit: 1000
tasks:
  check_maintenance_window:
    action: dynatrace.automations:run-javascript
    description: >
      Returns inMaintenanceWindow=true if current time falls inside the Sunday
      20:00-20:05 scheduled restart window. Handles DST by checking both UTC offsets.
    input:
      script: |
        export default async function () {
          const now = new Date();
          const utcDay  = now.getUTCDay();
          const utcHour = now.getUTCHours();
          const utcMin  = now.getUTCMinutes();

          const inSummerWindow = utcDay === 1 && utcHour === 0 && utcMin < 5;
          const inWinterWindow = utcDay === 1 && utcHour === 1 && utcMin < 5;

          const inMaintenanceWindow = inSummerWindow || inWinterWindow;
          console.log(`UTC day=${utcDay} hour=${utcHour} min=${utcMin} | inMaintenanceWindow=${inMaintenanceWindow}`);
          return { inMaintenanceWindow };
        }
    name: check_maintenance_window
    position:
      x: 0
      "y": 1
    predecessors: []

  prepare_snow_payload:
    action: dynatrace.automations:run-javascript
    active: true
    conditions:
      custom: '{{ result("check_maintenance_window").inMaintenanceWindow == false }}'
      else: STOP
      states:
        check_maintenance_window: OK
    description: >
      Builds the ServiceNow incident payload. Only runs when the crash occurs
      outside the scheduled maintenance window.
    input:
      script: |
        import { execution } from '@dynatrace-sdk/automation-utils';

        export default async function ({ execution_id }) {
          const ex = await execution(execution_id);
          const ev = ex.params.event || {};

          const payload = {
            serviceNowPayload: {
              cmdb_ci_input:     "MYSERVER01",
              assignment_group:  "My Team Name",
              u_impacted_system: "My Application",
              caller_id:         "dynatrace",
              category:          "Software",
              subcategory:       "Application",
              contact_type:      "Alert",
              correlation_id:    `DT_${ev["event.id"] || ""}`,
              short_description: "MyService crashed on MYSERVER01",
              description: [
                `Dynatrace detected a process crash on MYSERVER01.`,
                `Process  : MyService.exe`,
                `Time     : ${ev["event.start"] || new Date().toISOString()}`,
                `Event ID : ${ev["event.id"] || ""}`,
                `The service may have restarted automatically.`
              ].join("\n"),
              priority:          "3",
              state:             "1",
              environment:       "Production",
              environment_type:  "PRD",
              options: { search_cmdb_ci_by_fqdn: "N" }
            },
            original_event: ev
          };

          return payload;
        }
    name: prepare_snow_payload
    position:
      x: 0
      "y": 2
    predecessors:
      - check_maintenance_window

  create_snow_incident:
    action: dynatrace.automations:run-workflow
    active: true
    conditions:
      states:
        prepare_snow_payload: OK
    description: Calls the shared ServiceNow Incident Creation Workflow.
    input:
      workflowId: <your-snow-workflow-id>
      workflowInput: '{{ result("prepare_snow_payload") }}'
    name: create_snow_incident
    position:
      x: 0
      "y": 3
    predecessors:
      - prepare_snow_payload

Three tasks, one conditional gate:

check_maintenance_window — always runs; returns a boolean
prepare_snow_payload — runs only when inMaintenanceWindow == false; stops the chain otherwise
create_snow_incident — delegates to the shared SNOW workflow, passing the prepared payload

Save this as HealthCheck-MyService-ProcessCrash-MYSERVER01.yaml and deploy with dtctl apply -f.

Step 3 — Deploy with dtctl apply

cd ~/projects/dynatrace-workflows

# Create a new workflow (auto-generates an ID)
dtctl apply -f MyWorkflow.yaml

# Stamp the generated ID back into the file for future updates
dtctl apply -f MyWorkflow.yaml --write-id

# Update an existing workflow (file must already contain the id field)
dtctl apply -f MyWorkflow.yaml

The output tells you whether the workflow was created or updated. Use --write-id on first deploy so the file becomes self-contained for all future updates.

Step 4 — Diagnose 400 Errors

When dtctl apply returns a 400, run with --debug to see the full API error body:

dtctl apply -f MyWorkflow.yaml --debug 2>&1 | grep -A 10 '"error"'

The response includes a details object that pinpoints the exact invalid field:

{
  "trigger": {
    "eventTrigger": {
      "triggerConfiguration": [
        "davis-event -> value -> eventName: Extra inputs are not permitted"
      ]
    }
  }
}

This tells you exactly which field to remove or fix. Much faster than guessing.

Step 5 — Test the Workflow

Workflows with event triggers can't be tested by injecting synthetic events via the Events API — PGI_CRASHED_INFO and similar types are OneAgent-generated. Use the manual run feature in the Dynatrace UI instead:

Go to Automations → Workflows → open your workflow
Click Run (top right)
Paste a mock event context JSON:

{
  "event.type": "PGI_CRASHED_INFO",
  "event.description": "Process MyService.exe has crashed",
  "event.start": "2026-01-01T13:00:00.000Z",
  "event.id": "test-event-001",
  "dt.entity.host": "HOST-XXXXXXXXXXXXXXXX"
}

Verify each task ran successfully and check that any downstream integrations (SNOW, email, etc.) fired correctly

Note: Manual test runs do not create Dynatrace problems or inject real events. They only execute the workflow tasks with the provided mock context.

Step 6 — Commit to Git

cd ~/projects/my-dynatrace-repo

git add dynatrace-workflows/
git commit -m "Add/update workflow: <description>"

# Use a feature branch — main typically requires PR + CI checks
git checkout -b feature/my-workflow-change
git push -u origin feature/my-workflow-change

Then open a PR. Treat workflow YAML the same as application code — review it, scan it, merge it.

Bonus: Calling a Shared Workflow (ServiceNow Integration Pattern)

A pattern that works well at scale is a shared integration workflow that handles ServiceNow incident creation, with individual alert workflows delegating to it. This avoids duplicating SNOW logic across dozens of workflows and gives you a single place to update the integration.

Preparing the ServiceNow payload (JavaScript task)

const ev = execution.params.event ?? {};

const payload = {
  serviceNowPayload: {
    cmdb_ci_input:     "MY-HOSTNAME",
    assignment_group:  "My Team Name",
    u_impacted_system: "My Application",
    caller_id:         "dynatrace",
    category:          "Software",
    subcategory:       "Application",
    contact_type:      "Alert",
    correlation_id:    `DT_${ev["event.id"]}`,
    short_description: "Alert: process crash detected on MY-HOSTNAME",
    description:       `Event ID: ${ev["event.id"]}\nHost: ${ev["dt.entity.host"]}`,
    priority:          "2",
    state:             "1",
    environment:       "Production",
    environment_type:  "PRD",
    options: {
      search_cmdb_ci_by_fqdn: "N"
    }
  },
  original_event: ev
};

return payload;

Calling the shared SNOW workflow from YAML

create_snow_incident:
  action: dynatrace.automations:run-workflow
  input:
    workflowId: <your-snow-workflow-id>
    workflowInput: '{{ result("prepare_snow_payload") }}'

Common Gotchas at a Glance

Issue Cause Fix

400 on davis-event trigger	Invalid fields in value (e.g. eventName, problemState)	Only use entityTags, entityTagsMatch, customFilter
400 on schedule trigger	Cron string in rule field	Put cron in trigger.cron, set rule: null
Push rejected to main	Branch protection / CI required	Use feature branch + PR
PGI_CRASHED_INFO not triggering	INFO-level event, not a Davis Problem	Use davis-event trigger type, not davis-problem
contains() not allowed in filterQuery	filterQuery uses a DQL matcher subset, not full DQL	Use matchesPhrase() instead

Quick Reference: Useful dtctl Commands

# List all workflows
dtctl get workflows

# Export a workflow to YAML
dtctl get workflow <id> -o yaml > my-workflow.yaml

# Deploy / update
dtctl apply -f my-workflow.yaml

# Deploy and stamp ID into file
dtctl apply -f my-workflow.yaml --write-id

# Debug a failed deploy
dtctl apply -f my-workflow.yaml --debug 2>&1 | grep -A 20 '"error"'

# View execution history
dtctl get workflow-executions --workflow <id>

# Get task result from a specific execution
dtctl get wfe-task-result <execution-id> <task-name>

Wrapping Up

The dtctl + Copilot combination makes managing Dynatrace Workflows as code genuinely practical. Copilot handles the boilerplate YAML and JavaScript task logic; dtctl apply --debug gives you precise, field-level error feedback when the API rejects something; and Git gives you the full audit trail.

The main things to remember:

Export a working workflow first — it's the best schema reference you have
Use --write-id on first deploy — keeps the file self-contained for future updates
davis-event trigger value is more restrictive than it looks — let --debug be your guide
Manual run in the UI is your best testing tool for event-triggered workflows

Happy automating. If you've hit other gotchas or have workflow patterns worth sharing, drop them in the comments.

topic Managing Dynatrace Automation Workflows as Code with dtctl and GitHub Copilot in Dynatrace tips

Managing Dynatrace Automation Workflows as Code with dtctl and GitHub Copilot

Managing Dynatrace Automation Workflows as Code with dtctl and GitHub Copilot

Why Workflows as Code?

Prerequisites

The Workflow Cycle

Step 1 — Export an Existing Workflow as a Reference

Step 2 — Author a New Workflow with Copilot

Davis Problem trigger

Davis Event trigger (e.g. PGI_CRASHED_INFO)

Schedule (CRON) trigger

A Complete Workflow Example

Step 3 — Deploy with dtctl apply

Step 4 — Diagnose 400 Errors

Step 5 — Test the Workflow

Step 6 — Commit to Git

Bonus: Calling a Shared Workflow (ServiceNow Integration Pattern)

Preparing the ServiceNow payload (JavaScript task)

Calling the shared SNOW workflow from YAML

Common Gotchas at a Glance

Quick Reference: Useful dtctl Commands

Wrapping Up