Skip to content

Broken Reference Detection

Broken Reference Detection identifies configuration items that reference objects which no longer exist in your Zendesk instance. These "broken references" are one of the most common Zendesk configuration problems -- they accumulate silently as objects are deleted or renamed over time.

What Are Broken References?

A broken reference occurs when a configuration item (like a trigger or macro) references another object (like a custom field, group, or ticket form) that has been deleted or is no longer available.

Example:

A trigger checks the value of custom field "Product Type" (ID: 67890) in its conditions. If that field is later deleted in Zendesk, the trigger still references it -- but the reference is now broken. The trigger may silently skip the condition or behave unexpectedly.

Common causes:

  • Deleting a custom field that triggers or macros still reference
  • Removing a group that macros are restricted to
  • Archiving a brand that views filter on
  • Deleting a ticket form that automations check for

Health Checks

Broken reference detection runs as part of the Health Check engine. There are 6 checks, one for each source configuration type:

Check ID Source Type Severity What It Scans
REF-001 Triggers Critical Fields, groups, brands, tags, forms, and schedules referenced in trigger conditions and actions
REF-002 Automations Critical Fields, groups, brands, tags, and schedules referenced in automation conditions and actions
REF-003 Macros Warning Fields, groups, and tags referenced in macro actions and restrictions
REF-004 Views Warning Fields, groups, and brands referenced in view conditions and columns
REF-005 SLA Policies Warning Groups and brands referenced in SLA policy filters
REF-006 Ticket Forms Warning Fields associated with ticket forms

Severity levels

Critical checks (REF-001, REF-002) flag triggers and automations because broken references in these types can silently affect live ticket processing. Warning checks (REF-003 to REF-006) flag issues that affect agent productivity or reporting but don't directly disrupt ticket routing.

How Detection Works

The scanner uses Configly's dependency data and snapshot history to detect broken references:

  1. Dependency lookup -- For each source type (e.g., triggers), the scanner retrieves all extracted dependencies from the latest snapshot
  2. Target resolution -- For each dependency, it looks up the target object (e.g., a custom field) in the corresponding snapshot data
  3. Missing target detection -- If a target object can't be found in the snapshot, it's flagged as a broken reference
  4. Consolidation -- Multiple broken references from the same source object are consolidated into a single finding showing all missing targets

The scanner is registry-driven -- it uses the type registry to automatically determine which types to scan and how to resolve targets. Non-registry targets (such as individual users, tags, and locales) are gracefully skipped.

Viewing Results

Broken reference findings appear in the Health Check dashboard alongside all other checks:

  1. Run a Health Check from the connection dashboard
  2. Look at the Data Hygiene category -- broken reference checks are grouped here
  3. Each finding shows:
    • The source object (e.g., "Trigger: Auto-assign to billing")
    • The missing target(s) (e.g., "Custom field ID 67890, Group ID 123")
    • Severity level
    • Remediation steps

Findings also appear in PDF reports and the AI-powered executive summary, which provides context-aware recommendations for resolving broken references.

Tips for Remediation

Quick fixes

  • Update the source object in Zendesk to remove or replace the broken reference
  • Re-create the missing object if it was deleted by mistake
  • Disable the source object if it's no longer needed (inactive triggers, unused macros)

Prevention

  • Check dependencies before deleting -- Use Dependency Mapping to see what references an object before removing it
  • Run regular health checks -- Enable scheduled daily checks to catch new broken references early
  • Use What-If simulation -- Test changes with What-If Mode before applying them in Zendesk

Prioritisation

Focus on Critical findings first (REF-001 and REF-002) since these affect live triggers and automations that process tickets in real time. Warning-level findings (REF-003 to REF-006) can be addressed during routine maintenance.

Next Steps