連携トラブルはまずここ：ECC Queue（ecc_queue）

2026年6月28日 10:05

ServiceNow で Discovery（探索）を回したり、外部システムと連携したりすると、その裏ではメッセージのやり取りが発生しています。「サーバを調べてこい」という指示。「調べた結果はこれです」という応答。こうした1往復1往復を、ServiceNow は1件ずつレコードに残しています。その置き場が ECC Queue、テーブル名で言うと ecc_queue です。ECC は External Communication Channel（外部通信チャネル）の略です。ServiceNow と MID Server / 外部システムの間を流れるメッセージのキュー（待ち行列）を指します。

この記事は、Discovery や Integration、MID Server 連携を触り始めて「連携がうまくいかないとき、まずどこを見ればいいのか」を知りたい管理者・開発者を想定しています。PDI（Zurich / OOTB）で ecc_queue を実際に開き、1行＝1メッセージであること、queue フィールドで向き（input / output）が決まることを確かめました。あわせて state でメッセージの一生（ready → processing → processed / error）を追えること、PDI 実機での件数分布も見ています。

この記事で分かること

ECC Queue は ecc_queue の1行＝1メッセージで、ServiceNow と MID Server / 外部システムの間のやり取りを記録するキューであること
queue フィールドで向きが決まること（output＝ServiceNow→外部、input＝外部→ServiceNow）
メッセージの種類は topic、宛先は agent、本文は payload（最大約1MB）に入ること
state（ready / processing / processed / error）でメッセージの処理状態を追えること
PDI 実機の約1,400件すべてが output / processed / HeartbeatProbe だったこと
その理由が MID Server 未登録（ecc_agent が 0 件）にあること

この記事の内容は ServiceNow の PDI（Personal Developer Instance）Zurich（ズーリッヒ）リリースの OOTB（初期設定）で確認した個人メモです。本番環境やカスタマイズ済み環境では、フィールド・選択肢・キューの中身が異なる場合があります。

ECC Queue（ecc_queue）とは

ECC Queue とは、ServiceNow が MID Server や外部システムとやり取りするメッセージを、1件＝1レコードで残す待ち行列 です。たとえば Discovery で「この IP のサーバを調べてこい」という指示（プローブ）を出すと、その指示が ecc_queue に1行積まれ、MID Server がそれを取りに来ます。調査結果が返ってくると、今度は応答が ecc_queue にもう1行積まれます。

下の実画面は、PDI の ecc_queue を topic（メッセージの種類）でグループ化したものです。

このように、ECC Queue は連携の「通り道」であると同時に、連携がどこまで進んだかを後から追える証跡にもなります。だから連携トラブルの切り分けは、まず ecc_queue を開くところから始まります。PDI（Zurich / OOTB）の ecc_queue には、すでに約1,400件のメッセージが入っていました。

1行＝1メッセージ。queue が「向き」を決める

ECC Queue では queue フィールドがメッセージの向きを決めます。

output（出力）… ServiceNow → 外部。Discovery のプローブや外部への指示など、ServiceNow が「送る」メッセージ。
input（入力）… 外部 → ServiceNow。MID Server や外部システムが返してきた応答を、ServiceNow が「受け取る」メッセージ。

MID Server は、自分宛の output メッセージを定期的に取りに来て処理し、その結果を input として積み返します。この output と input が交互に積まれることで、1つの作業の往復が ecc_queue 上に並びます。往復のひも付けには response_to（応答元メッセージへの参照）が使われます。

1件のメッセージが持つ主なフィールドは次の通りです。

中でも連携の中身を決めるのは、宛先を表す agent、種類を表す topic、本文を表す payload の3つです。payload は最大で約1MB（1,048,576 文字）まで入る大きな文字列フィールドで、ここに実際の指示や結果が XML などの形で格納されます。フィールド一覧は次のURLで確認できます（先頭の <YourInstance> は自分のインスタンスに置き換えてください）。

https://<YourInstance>/sys_dictionary_list.do?sysparm_query=name=ecc_queue^elementISNOTEMPTY

外部を呼び出す入口としては送信側 REST 連携（REST Message）もよく使われます。REST Message はインスタンスから直接 HTTP を投げます。ECC Queue が担うのは MID Server を介した非同期のやり取りで、そこに役割の違いがあります。

state でメッセージの一生を追う

もう1つの軸が state（処理状態） です。メッセージは積まれてから処理されるまで、いくつかの状態を通ります。

ready … キューに投入された直後。処理待ち。
processing … 処理中。
processed … 処理済み（正常完了）。
error … エラー。理由は error_string に入る。

queue（向き）と state（状態）の選択肢は次の通りです。

連携が止まっているとき、この2軸で絞り込むと原因に近づけます。たとえば output が ready のまま溜まっているなら、MID Server が取りに来ていない（落ちている）疑いがあります。error が並ぶなら、処理そのものが失敗しています。PDI で queue 別・state 別にグループ化すると、いまどの状態のメッセージがどれだけあるかが一目で分かります。

PDI 実機：約1,400件すべてが「MID Server 探し」だった

PDI の ecc_queue を分布で見ると、約1,400件すべてが queue=output / state=processed / topic=HeartbeatProbe でした。宛先の agent はすべて mid.server.\*（全 MID 宛のワイルドカード）で、payload は空です。流れていたメッセージは1種類だけでした。

なぜこうなるのか。理由は MID Server が1台も登録されていないことにあります。MID Server の登録簿である ecc_agent テーブルは 0 件でした。

ServiceNow は「MID Server はいませんか？」という生存確認（HeartbeatProbe）を5分ごとに output キューへ積みます。宛先は全 MID（mid.server.\*）です。ところが応答すべき MID Server がいないため、input（応答）は0件のままです。送った側は処理を終えるので state は processed になります。結果として「output / processed / HeartbeatProbe」だけが延々と積み上がっていました。

この分布を表にすると、いまの PDI の ECC Queue の姿がはっきりします。

裏を返せば、MID Server を1台登録してオンラインにすれば、この HeartbeatProbe には応答が返ります。input 側にもレコードが現れます。さらに Discovery を回せば、SSHCommand や JDBCProbe といった別の topic のメッセージが output / input を往復しはじめます。ただし、それらの topic がどんな payload で流れるか、件数がどうなるかは検証範囲外です。MID Server を立てていない今回の PDI では発生しません。今回確認できたのは、「MID Server がいない素の状態の ECC Queue」の姿です。

実機で確認するときに見るべきURL

今回見た画面を自分のインスタンスで開くためのURLは次の通りです（<YourInstance> は置き換えてください）。

# ECC Queue を topic でグループ化
https://<YourInstance>/ecc_queue_list.do?sysparm_query=GROUPBYtopic

# ECC Queue を queue（向き）でグループ化
https://<YourInstance>/ecc_queue_list.do?sysparm_query=GROUPBYqueue

# ECC Queue を state（状態）でグループ化
https://<YourInstance>/ecc_queue_list.do?sysparm_query=GROUPBYstate

# ecc_queue のフィールド定義
https://<YourInstance>/sys_dictionary_list.do?sysparm_query=name=ecc_queue^elementISNOTEMPTY

# MID Server の登録簿
https://<YourInstance>/ecc_agent_list.do

ECC Queue の考え方は ServiceNow 公式の ECC Queue（Zurich）でも説明されています。

まとめ

ECC Queue は ecc_queue の1行＝1メッセージ。ServiceNow と MID Server / 外部システムの間を流れるメッセージのキュー。
queue フィールドが向きを決める。output＝ServiceNow→外部、input＝外部→ServiceNow。往復は response_to でひも付く。
メッセージの種類は topic、宛先は agent、本文は payload（最大約1MB）。状態は state（ready → processing → processed / error）で追える。
PDI 実機では 約1,400件すべてが output / processed / HeartbeatProbe。理由は MID Server 未登録（ecc_agent 0 件）で、生存確認だけが5分ごとに積まれ続けていたから。
連携トラブルの切り分けは、まず ecc_queue を queue × state で絞るのが基本。

ECC Queue が分かると、ServiceNow の外部連携が2系統で成り立っていることが見えてきます。「直接 HTTP を投げる経路」と「MID Server を介してキューでやり取りする経路」です。連携の入口は3つあります。REST 連携（Scripted REST API）は外部からデータを受け取る仕組みです。送信側 REST 連携（REST Message）は外部を呼び出す仕組みです。OAuth 設定（oauth_entity）は連携の認証を支える仕組みです。合わせて読むと、ServiceNow の連携の全体像がひとつにつながります。