ecc_queue Table — ServiceNow Reference

Table Reference/ecc_queue

The ecc_queue table manages message queues between the ServiceNow instance and MID Servers, supporting probes and sensors for ITOM/Discovery operations. Records are automatically created by the platform and have a rapid lifecycle—most queries should filter by timestamp or MID Server to avoid performance issues.

What This Table Is

The ecc_queue table serves as the message queue between your ServiceNow instance and MID Servers. Every probe sent to a MID Server creates an output queue record, and every response from sensors creates an input queue record. This bidirectional communication channel is the backbone of ITOM Discovery, Service Mapping, and Cloud Management operations.

Owned by the Platform module, this table supports the entire MID Server ecosystem. Records flow through states from ready to sent to processed within seconds or minutes. Unlike most ServiceNow tables, these records are transient—they exist only long enough to facilitate communication before being processed and potentially cleaned up.

This table extends sys_metadata and has no child tables. The queue field determines message direction: output for instance-to-MID messages (probes) and input for MID-to-instance responses (sensor results).

In large enterprises, this table processes thousands of records per hour during Discovery runs. The table is heavily indexed on agent and state fields to support MID Server polling, but unfiltered queries can still timeout due to record volume. Background cleanup jobs regularly purge processed records, so historical analysis requires careful timestamp filtering.

When You'll Script Against This Table

Most developers encounter this table during ITOM troubleshooting rather than regular application development. You'll script against ecc_queue in Business Rules on Discovery or Service Mapping tables, Script Includes for MID Server health monitoring, and Scheduled Jobs for queue maintenance. Custom probes and sensors also create records programmatically through the MID Server API.

The admin role provides full access, while itil users can read records. MID Server accounts have specialized ACLs for their designated records only. Global scoped applications can query freely, but scoped apps may need explicit table access grants.

Common scripting patterns:

Monitor probe failures by querying error states for specific MID Servers
Track Discovery progress by counting processed vs. total probe records
Build custom MID Server health dashboards using queue depth metrics
Debug probe payloads by examining XML content in failed records
Create custom probes through Script Includes that populate the output queue
Clean up stale records with maintenance jobs based on age and state
Generate MID Server utilization reports by analyzing message volume trends

Table Gotchas

⚠️

Records in this table have a very short lifecycle. Never assume a record will exist minutes after creation—background processes clean up processed records regularly.

⚠️

The payload field contains XML that can be massive (>1MB for some Discovery probes). Avoid SELECT * queries and don't iterate through payload content in loops.

The state field uses different values for input vs. output queues—ready means "waiting to be sent" for output but "received and ready to process" for input
Records with state=error persist longer than successful ones, which can skew historical analysis toward failures

⚠️

Queries without agent filtering hit multiple MID Servers' records and can timeout. Always filter by specific MID Server or use timestamp windows.

The sequence field increments per MID Server, not globally—don't use it for cross-MID ordering
MID Server polling updates the sys_updated_on timestamp even when no data changes, making it unreliable for change tracking

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

The ecc_agent table defines the MID Servers themselves and connects through the agent field. Every queue record belongs to exactly one MID Server, and understanding MID Server configuration often requires joining these tables to check capabilities, status, and IP ranges.

Discovery operations link through discovery_status for tracking overall progress and cmdb_ci for the configuration items being discovered. The cmdb_rel_ci table captures relationships identified through sensors, while sa_pattern defines the Discovery patterns that generate many of the probes flowing through this queue.

For troubleshooting, the ecc_agent_log table provides detailed MID Server activity logs that complement queue analysis. Developers building comprehensive Discovery monitoring often query across all these tables to correlate probe failures with MID Server health, pattern execution, and resulting CI updates.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Key Fields

Column	Type	Label	Notes
agent	string	MID Server	The MID Server name handling this queue record. Critical for filtering—queries without this can timeout due to cross-MID volume.
state	choice	State	Queue processing state (ready, sent, processed, error). Values mean different things for input vs. output queues—'ready' means waiting-to-send for output but received-ready-to-process for input.
queue	choice	Queue	Message direction: 'output' for instance-to-MID probes, 'input' for MID-to-instance sensor responses. Fundamental for understanding message flow.
topic	string	Topic	Probe or sensor name being executed. Key for filtering specific Discovery operations or debugging particular probe types.
name	string	Name	Human-readable description of the queue operation. Often contains target IP addresses or CI names for Discovery probes.
payload	xml	Payload	XML content of the probe or sensor data. Can be massive (>1MB) so avoid including in SELECT * queries or loops.
sequence	integer	Sequence	Message sequence number per MID Server, not global. Don't use for cross-MID ordering—increments independently per agent.
processed	glide_date_time	Processed	Timestamp when the message was processed. Null for records still in queue, useful for calculating processing latency.
error_string	string	Error String	Error details when state=error. Critical for probe failure troubleshooting but only populated on failed records.
source	string	Source	Context that created the queue record (Discovery, Service Mapping, etc.). Helps identify which ITOM process generated the message.
agent_correlator	string	Agent Correlator	MID Server correlation ID linking related probe/sensor pairs. Used internally for message matching and response correlation.
ecc_queue	reference	Parent Queue	Self-reference to parent queue record. Used for probe/sensor correlation where responses reference their originating probes.
sys_domain	domain_id	Domain	Domain separation field. MID Servers respect domain boundaries, so queue records inherit domain from the Discovery process.
response_to	string	Response To	Links input queue records to their originating output probe. Essential for tracking probe/sensor message pairs.

Common Queries

Get all ready records for a specific MID Server

// Basic query every developer tries first
// Always filter by agent to avoid timeouts
var gr = new GlideRecord('ecc_queue');
gr.addQuery('agent', 'your-mid-server-name');
gr.addQuery('state', 'ready');
gr.query();

while (gr.next()) {
    gs.info('Queue: ' + gr.queue + ', Topic: ' + gr.topic);
    gs.info('Name: ' + gr.name);
    // Don't log payload - it's massive XML
}

Find error records for Discovery probes in the last hour

// Real troubleshooting scenario - recent probe failures
// Combines state filter with time window for performance
var gr = new GlideRecord('ecc_queue');
gr.addQuery('state', 'error');
gr.addQuery('queue', 'output'); // Probes going to MID
gr.addQuery('source', 'CONTAINS', 'Discovery');
gr.addQuery('sys_created_on', '>', new GlideDateTime().subtract(60 * 60 * 1000));
gr.orderByDesc('sys_created_on');
gr.query();

while (gr.next()) {
    gs.error('Failed probe: ' + gr.topic + ' on ' + gr.agent);
    gs.error('Error: ' + gr.error_string);
}

Track Discovery progress for a specific MID Server

// Business scenario - monitoring Discovery completion
// Uses processed timestamp to identify active vs completed
var gr = new GlideRecord('ecc_queue');
gr.addQuery('agent', 'PROD-MID-01');
gr.addQuery('source', 'CONTAINS', 'Discovery');
gr.addQuery('sys_created_on', '>', new GlideDateTime().subtract(24 * 60 * 60 * 1000));
gr.query();

var total = 0, processed = 0;
while (gr.next()) {
    total++;
    if (!gr.processed.nil()) processed++;
}
gs.info('Discovery progress: ' + processed + '/' + total + ' (' + 
        Math.round(processed/total * 100) + '%)');

Count queue records by MID Server and state

// Aggregate query for MID Server health dashboard
// Groups by agent and state for operational metrics
var ga = new GlideAggregate('ecc_queue');
ga.addQuery('sys_created_on', '>', new GlideDateTime().subtract(60 * 60 * 1000));
ga.groupBy('agent');
ga.groupBy('state');
ga.addAggregate('COUNT');
ga.query();

while (ga.next()) {
    var agent = ga.agent.toString();
    var state = ga.state.toString();
    var count = ga.getAggregate('COUNT');
    gs.info(agent + ' - ' + state + ': ' + count + ' records');
}

Wrong way vs right way to find recent probe failures

// WRONG: This will timeout in production
// var gr = new GlideRecord('ecc_queue');
// gr.addQuery('state', 'error');
// gr.query();

// RIGHT: Always include agent and time filters
var gr = new GlideRecord('ecc_queue');
gr.addQuery('agent', 'your-mid-server');
gr.addQuery('state', 'error');
gr.addQuery('sys_created_on', '>', new GlideDateTime().subtract(4 * 60 * 60 * 1000));
gr.orderByDesc('sys_created_on');
gr.setLimit(100); // Prevent runaway queries
gr.query();
// This prevents table scan across millions of historical records

Related Tables

cmdb_ci cmdb_rel_ci

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue