虫めがねアイコンはどこで作られているか（sys_ui_macro）

2026年6月28日 15:33

ServiceNow のフォームを開くと、「画面の部品」がいたるところにあります。参照項目の横にある虫めがねアイコン、関連リストの上にある小さなウィジェット、サービスカタログの表示パーツなどです。これらの多くは UI マクロ（sys_ui_macro） という1つのテーブルに溜まっていて、中身は Jelly（XML）で書かれた再利用可能な部品です。

この記事は、ServiceNow の画面操作には慣れたが、こうした部品がどこにどんな形で定義されているのかを確認したい管理者・開発者を想定しています。PDI（Zurich / OOTB）で sys_ui_macro を実際に開き、1件＝1つの UI 部品であることを確かめます。本体である xml（Jelly ソース）と分類の category、そしてマクロがフォームやフォーマッタからどう呼ばれて画面に描画されるのかも追います。最後に独立画面を作る UI Pageとの違いを見ます。

この記事で分かること

UI マクロが sys_ui_macro（Macro）の1件＝1つの再利用 UI 部品として溜まること
マクロの本体が xml フィールドの Jelly（XML）テンプレートであること
PDI 実機の 707件と、その category 別内訳（general が約9割）
代表的なマクロ ui_reference（参照セレクタ）と layout_2_across（レイアウト枠）の中身
マクロが <g:macro名/>・フォーマッタ・カタログ変数から呼ばれて画面の一部を描くこと
UI マクロ（部品）と UI Page（独立画面）の役割の違い

この記事の内容は ServiceNow の PDI（Personal Developer Instance）Zurich（ズーリッヒ）リリースの OOTB（初期設定）で確認した個人メモです。本番環境やカスタマイズ済み環境では、マクロの件数・category の分布が異なります。

UI マクロ（sys_ui_macro）とは

UI マクロとは、ServiceNow の画面に埋め込んで使う 再利用可能な UI 部品 を、1件＝1レコードで定義したものです。参照項目のセレクタ、フォーマッタが描く表示パーツ、ホームページのレイアウト枠などが、それぞれ1つのマクロとして sys_ui_macro に登録されています。アプリナビで「System UI > UI Macros」を開くと見えるのが、この sys_ui_macro です。

下の画面は、PDI（Zurich / OOTB）の sys_ui_macro を category でグループ化したものです。general・catalog・layout といった分類ごとに部品がまとまっています。

PDI（Zurich / OOTB）の sys_ui_macro には、707件のマクロが登録されていました。そのうち有効なものが 703件、無効（active=false）が 4件です。ほとんどが ServiceNow が標準で用意した OOTB の部品で、個人情報は含まれないシステム定義のメタデータです。

sys_ui_macro はどんなテーブルか

sys_ui_macro の継承元を確認すると、業務テーブルではありませんでした。今回の PDI（Zurich / OOTB）で見ると、sys_ui_macro の super_class（継承元）は sys_metadata です。ラベルでいう Application File（アプリケーションファイル）にあたります。つまり incident のような業務データではなく、設定・部品を保持する構成（メタデータ）レコードとして管理されています。Update Set に乗って環境間を移動するのも、このためです。

1つのマクロが持つフィールドはシンプルで、固有フィールドは8つだけでした。

中心になるのは name（呼び出しキー）と xml（Jelly 本体） の2つです。name はマクロを呼び出すときのキーになり、xml にそのマクロが描く中身を Jelly で書きます。フィールド定義は次のURLで確認できます（先頭の <YourInstance> は自分のインスタンスに置き換えてください）。

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

xml フィールド：Jelly で書く本体

マクロの本体は xml フィールドに入る Jelly（ジェリー） というテンプレート言語（XML）です。新規にマクロを作ると、xml には次のような空の雛形が入っています。

<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide">

</j:jelly>

ルート要素は <j:jelly> で、2つの名前空間が既定で宣言されています。xmlns:j="jelly:core" は Jelly の制御タグ（条件分岐・繰り返しなど）を担当します。xmlns:g="glide" は ServiceNow 独自の Glide 拡張タグで、他のマクロ呼び出しや項目描画に使います。この <j:jelly> の中に HTML や Glide タグを書くと、それが部品の中身になります。

呼び出されると、この Jelly はサーバ側で評価されます。${jvar_name} のような変数が実際の値に置き換わり、HTML の断片が生成されて画面に描かれます。

実際のレイアウト系マクロ layout_2_across（2カラム枠）の中身を開いてみます。HTML の table タグと ${jvar_name} のような Jelly 変数が、そのまま書かれているのが分かります。

category：マクロの分類

category は、そのマクロがどの用途のものかを表す分類です。PDI で category 別に集計すると、分布がはっきりしました。

general が638件と全体の約9割を占め、残りは catalog（46件）・layout（18件）・cms（4件）・list（1件）でした。general は ui_reference のような汎用の UI 部品です。layout はホームページやダッシュボードの「2カラム」「3カラム」といったレイアウト枠（layout_2_across など）です。catalog はサービスカタログ画面の表示部品です。一覧を名前順で開くと、これらの命名規則（layout_ や sc_ のプレフィックス）が見えてきます。

代表マクロ ui_reference：参照セレクタ部品

汎用マクロの代表が ui_reference です。これは「指定したテーブルのレコードを選ぶセレクタ（参照入力欄）」を生成する部品で、UI Page や独自フォームで参照入力を作りたいときに再利用されます。description には属性（name / table / value / query など）の使い方が丁寧に書かれており、次のように呼び出します。

<g:ui_reference name="vendor" id="vendor"
                table="core_company" field="name" query="vendor=true"/>

このように <g:[マクロ名] 属性.../> と書くだけで、ui_reference マクロの Jelly が展開されます。core_company テーブルを引く参照セレクタが画面に描かれます。下の画面は、その ui_reference レコードをフォームで開いたものです。

同じ系統には、複数選択版の ui_reference_multi や、値があるときだけ装飾を出す reference_decoration があります。いずれも「参照系の UI 部品」として再利用されています。

マクロはどこから呼ばれるか

マクロは単独では URL で開けません。必ず何かの画面の中に展開されて描画されます。PDI で確認できた主な呼び出し経路は3つです。

g 名前空間タグ … フォームや UI Page の Jelly 内に <g:macro名/> と書きます。<g:macro_invoke macro="名前"/> でも同じくマクロが展開されます。
フォーマッタ（sys_ui_formatter） … フォーム上の「フォーマッタ」項目はマクロを描画します。PDI には sys_ui_formatter が 115件ありました。各レコードの formatter 列は UI マクロ名を指し、menu_path_formatter.xml のように .xml が付きます。
カタログ変数の Macro 型 … サービスカタログの変数タイプ「Macro」「Macro with Label」は、カタログ画面に UI マクロを差し込みます。

これらに共通するのは「画面の一部分を描画する再利用部品」という性質です。UI マクロはあくまでサーバ側で HTML を組み立てる Jelly のテンプレートです。クライアント側で動く共通 JavaScript を置くのは別の仕組みです。UI Script（sys_ui_script）とは役割が異なります。どのフォームに何が並ぶかは、フォーム構成（sys_ui_form 系）が決めます。項目もフォーマッタも同じ仕組みで並び、マクロはその中の1パーツとして効いてきます。

UI マクロと UI Page（sys_ui_page）の違い

UI マクロとよく混同されるのが UI Page（sys_ui_page）です。どちらも Jelly で書く UI ですが、部品か画面かという決定的な違いがあります。

sys_ui_macro（UI マクロ） … 画面に埋め込む再利用部品。<g:macro名/> で他の画面の中に展開され、単独では URL で開けません。
sys_ui_page（UI Page） … /<name>.do で直接開ける独立した1画面。処理スクリプトやクライアントスクリプトも持てます。

整理すると次のようになります。

ざっくり言えば、マクロは「部品」、ページは「画面」 です。ダイアログや独自のランディング画面そのものを作るなら UI Page、その画面の中で何度も使う参照セレクタやレイアウト枠を作るなら UI マクロ、と使い分けます。

なお、無効化されているマクロも確認できました。PDI では email_reply や group_select など 4件が active=false で、過去に使われた・代替に置き換わった部品が無効として残っています。

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

最後に、今回見た画面を自分のインスタンスで開くためのURLをまとめます（<YourInstance> は置き換えてください）。

# マクロを分類でグループ化
https://<YourInstance>/sys_ui_macro_list.do?sysparm_query=GROUPBYcategory

# 名前順で一覧
https://<YourInstance>/sys_ui_macro_list.do?sysparm_query=ORDERBYname

# 無効なマクロだけ絞る
https://<YourInstance>/sys_ui_macro_list.do?sysparm_query=active=false

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

まとめ

UI マクロは sys_ui_macro（Macro）の1件＝1つの再利用 UI 部品として溜まる。PDI では 707件（有効703 / 無効4）。
継承元は sys_metadata（Application File） で、業務データではなく構成（メタデータ）レコード。
マクロの本体は xml フィールドの Jelly（XML）。<j:jelly> の中に Glide タグや HTML を書き、サーバで評価されて HTML 断片になる。
category は分類で、PDI では general 638 / catalog 46 / layout 18 / cms 4 / list 1。general が約9割。
代表は参照セレクタの ui_reference、レイアウト枠の layout_2_across。<g:macro名/>・フォーマッタ・カタログ変数から呼ばれる。
UI マクロは「部品」、UI Page は「画面」。役割が違う。

UI マクロが分かると、画面まわりの仕組みが「画面を作る → 部品を埋める → 項目を並べる」という流れでつながって見えてきます。画面そのものを作るのがUI Page（独自画面）です。そこに差し込む共通 JS はUI Script（クライアント側の共通JS）にまとまります。項目の並びはフォーム構成（sys_ui_form 系）が決めます。

ServiceNow 画面・フォーム完全ガイド：どこを直せば見た目が変わるのか — UIマクロは画面に埋め込む部品そのものです。画面のどこを直せば見た目が変わるのかを俯瞰したいときはこちらの完全ガイドが起点になります。