ServiceNowでバックグラウンドスクリプトを使用して設計書を作る方法
このシリーズは3本構成です
1. ServiceNowでバックグラウンドスクリプトを使用して設計書を作る方法（本記事・無料）… 調査セットの使い方を画面つきで解説
2. ServiceNowの設計書をバックグラウンドスクリプトを使用して作ったレポートの例（¥100） … 出来上がった設計書の実物
3. ServiceNowの設計書ネタ収集スクリプト（¥300） … 調査セット2ファイルの全文
「incident の設計書を作ってほしい」と頼まれたとき、最初にやるのは材料集めです。テーブル定義を開いて項目を数え、フォームのスクリーンショットを撮り、ビジネスルールのタブで件数を控え、通知の一覧をExcelに写す。半日かけて集め終わる頃には、どこまで写したか分からなくなっています。
この記事では、その材料集めをバックグラウンドスクリプト1本に任せる方法を手順で説明します。Scripts - Background に貼って実行すると、対象に応じて26〜31章がまとめて出ます（incident なら26章）。テーブル定義・フォーム構成・通知・ビジネスルール・ACL・SLA・Flow。これらがパイプ区切りの表として並びます。あとは出力を生成AIに渡せば、設計書の原稿になります。
使うスクリプトは Design Doc Collector v1.0。読み取り専用で、更新処理は実装していません。PDI（Zurich）で3テーマ分を実際に流して確かめた手順を書きます。
この記事で分かること
材料集めから設計書の原稿までの4ステップ
1回の実行で何が取れるか（incident で26章・782行の実測）
テーブル・カタログアイテム・ポータルの3種類を1本で切り替えるやり方
集めた章を設計書のどの章に割り当てるか
ACL・Flowが内訳と有効フラグつきで出るので、書くべき数字がすぐ決まること
この記事の内容は ServiceNow の PDI（Personal Developer Instance）Zurich（ズーリッヒ）リリースで実機確認した個人メモです。件数はこの環境の実測値であり、皆さんの環境とは一致しません。本番環境での実行は、読み取り専用とはいえメタデータへの集計クエリが走るため、業務時間外を推奨します。
全体の手順
使うファイルは2つだけです。調査用ベーススクリプトとレポート作成プロンプト。この2つを手元に置き、生成AIとやり取りしながら進めます。
ベーススクリプトを直接編集する必要はありません。生成AIに添付して「何の設計書を作りたいか」を伝えると、要求に合わせた専用版を書いてくれます。ベーススクリプトは、AIに ServiceNow のメタデータ構造と出力形式を教えるための土台という位置づけです。
手順は4つです。
調査セットを手元に置く（2ファイル）
作りたい設計書を生成AIに伝える（ベーススクリプトを添付）
出来上がった調査スクリプトを実行する（Scripts - Background）
出力とレポート作成プロンプトから設計書を作る
手順1：調査セットを手元に置く
用意するのは次の2ファイルです。
01.調査用ベーススクリプト.txt は、ServiceNow のメタデータを集める読み取り専用スクリプトです。テーブル定義・フィールド・フォーム構成・通知・ビジネスルール・ACL・SLA・Flow など28章分の収集処理と、パイプ区切りで列を揃える出力形式を持っています。
02.レポート作成プロンプト.txt は、集めた出力を設計書の体裁に整えるための指示文です。章立て・図表のキャプション規則・数値の扱いを指定しています。
この2つをフォルダにまとめておけば、以降は同じ手順を繰り返すだけです。案件ごとにスクリプトを書き起こす必要はありません。
手順2：作りたい設計書を生成AIに伝える
ベーススクリプトを添付して、日本語で要求を書きます。
指定するのは対象だけで構いません。「incident テーブルの設計書」「ポータル sp の画面設計書」「カタログアイテム『Apple iPhone 13 pro』の設計書」といった伝え方で通ります。
数分待つと、専用版のスクリプトが返ってきます。
この回答が示すとおり、AIは対象に合わせて次を行います。
パラメータの設定 … TABLE_NAME = 'sc_cat_item'、CATALOG_ITEM_NAME = 'Apple iPhone 13 pro'、TARGET_MODE = 'catalog_item'
不足している処理の追加 … この例では、sys_id を手で調べなくて済むよう「アイテム名から自動特定する」処理が足されています。完全一致を優先し、無ければ部分一致で候補を探し、同名が複数あれば候補一覧を出して停止する、という作りです
ベースの制約を維持 … 読み取り専用であること、区切り表形式で出すこと、取得件数の上限を置くことは、そのまま引き継がれます
sys_id をコピーして貼る手間が消えるのは、実務では効きます。「Apple iPhone 13 pro の設計書」と言えば済むようになります。
手順3：出来上がった調査スクリプトを実行する
受け取ったコードを Scripts - Background（sys.scripts.do）の入力欄に全文貼り、Run script を押します。実行前にスコープが global になっていることを確認してください。
数秒で結果が返ります。右側が出力です。価格・納期・ポータル表示フラグ・ロール・所有者・掲載カタログといった設定値が、そのまま表として並びます。
エラーが出たら、その内容を生成AIに貼り付けてください。 修正版が返ってきます。ServiceNow はリリースや導入済みプラグインによってテーブル構成が変わるため、環境固有の調整が要る場面もあります。その往復で吸収できます。
出力を使うときは、行頭の *** Script: を一括置換で消してください。これは gs.print がプラットフォーム側で付ける接頭辞で、スクリプトからは外せません。
手順4：出力とプロンプトから設計書を作る
実行結果を貼り、レポート作成プロンプトを添付して指示します。
「調査結果をチェックしてください。レポート作成プロンプトに従ってレポートにしてください」。この一文で、表紙・目次・図表つきの設計書が返ってきます。
プロンプト側で指定しているのは次のあたりです。
章・節・項の構成（基本方針 → 概要 → 詳細 → 参照）
図表の番号付けと、表は上・図は下にキャプションを置く規則
ワークフローは必ず記載する
非IT の読者にも通じる説明を先に置き、そのあと技術的な詳細を書く
数値は引用可能なものに限定する
最後の1行が効きます。これを入れておかないと、生成AIは出力に無い数字を補完してきます。設計書としては致命的な性質なので、「渡した出力にある数字だけを使う」ことを明示しておきましょう。
出力が大きいときは、章ごとに分けて渡したほうが後半が薄くなりません。特にフォーム画面イメージはアスキーアートで行数を食うので、単独で渡すと読み落としが減ります。
実際に起こした設計書は、表紙・目次つきで全7章になりました。フォームの画面イメージ、状態遷移図、優先度マトリクス、SLA一覧まで含んでいます。出来上がった設計書そのものは、レポート例編（¥100）に全ページ掲載しています。
設定値と運用ルールを混ぜない
1つだけ注意があります。出力から機械的に決まらない部分は、生成AIに書かせないほうがよいという点です。
たとえば優先度の対応表は dl_u_priority から取れます。しかし「どういうときに影響度をHighと判断するか」は、設定値のどこにも書かれていません。組織が決めることだからです。状態ごとの担当や、滞留とみなす日数も同じです。
プロンプトに「設定値から決まらない運用ルールは【要決定】と明示せよ」と足しておくと、埋めるべき箇所がはっきりします。設定の写しである部分と、これから決める部分を分けておくと、レビューで揉めません。
3種類の設計書を1つのセットで作る
現場で頼まれる設計書は1種類ではありません。ベーススクリプトは3つの調査モードを持っているため、伝える要求を変えるだけで対象が切り替わります。
業務テーブル（incident、change_request、problem など）では、テーブル定義からフォーム構成・通知・ビジネスルール・ACL・SLA・Flow までが揃います。
カタログアイテムでは、上記に加えて申請画面の項目と申請後の流れが出ます。変数の型と必須の別、カタログUIポリシーによる出し分け、フルフィルメントの担い手が Classic Workflow か Flow か。この4点が揃うと、申請から完了までの説明が書けます。
Service Portal では、ページとウィジェットの対応が取れます。画面は sp_portal → sp_page → sp_container → sp_row → sp_column → sp_instance → sp_widget という6段の入れ子で構成されます。ただし設計書に要るのは「どのページにどのウィジェットが載るか」だけなので、ページ単位で畳んで1行にまとめてあります。
どのモードでも出力形式は同じパイプ区切りの表です。レポート作成プロンプトも共通なので、渡し方を1度覚えれば対象が変わっても手順は変わりません。
1回の実行で取れるもの
出力はパイプ区切りの表形式テキストです。章ごとに ########## の見出しが入ります。
incident を対象にした実測は782行・3.3秒でした。カタログアイテムが509行・1.9秒、ポータルが281行・1.3秒です。業務データの全件走査をせず、メタデータだけを見ているため速く終わります。
冒頭にはカスタム判定サマリーが出ます。設計書を書くとき最初に知りたいのは「この環境は素のままか、それとも作り込まれているか」だからです。テーブル名とフィールド名の接頭辞（u_ / x_）で標準かカスタムかを判定しています。今回の PDI では incident のカスタムフィールドは0件でした。作り込みがある環境なら、ここに並ぶ項目が設計書の重点になります。
出力を設計書の章に割り当てる
集めた章を、設計書のどの章に使うかは決まっています。対応を覚えておくと、2本目以降が速くなります。
第1章（対象範囲）には0章と1章を使います。カスタム判定と継承チェーンです。テーブルの親子関係は図に起こします。改修の影響範囲を決める前提になるためです。
データモデルの章には2章と3章。フィールド定義とChoice定義です。「定義元」列で自テーブル由来と継承分を分けると、項目定義表の構成がそのまま決まります。
画面設計の章には4章。フォームのアスキーアートを表に置き換えるだけで済みます。あわせて7-1章（UIポリシー）、7-2章（クライアントスクリプト）、4C章（データポリシー）を見ると、画面上の制御が揃います。
業務プロセスの章には3章と10-1章。Choice定義から状態を拾い、ワークフロー定義の有無で自動遷移かどうかを判断します。
自動処理の章には5章・6章・10-2章。通知・ビジネスルール・Flow です。
アクセス制御の章には8章を使います。
数字は内訳つきで出る
設計書に書く数字は、そのまま転記できる形で出力されます。ここがこのスクリプトの実用性を決めている部分です。
ACLは適用パターン別に分かれる
アクセス制御は、テーブル単位・フィールド単位・全社共通の既定という3層で効きます。出力ではこれをパターン別に分けて出します。
incident の実測では、このテーブル固有が24件と84件、親テーブルから継承する分が3件と30件、全テーブル共通の既定が29件と600件でした。
設計書に「インシデント管理のアクセス制御」として書くべきは、固有分と継承分を合わせた141件です。残る629件は全テーブルに効く共通設定なので、別の章で一度だけ扱えば足ります。内訳が出ることで、この切り分けが機械的にできます。
Flowは有効フラグつきで出る
incident をトリガーとする Flow は14件見つかり、そのうち有効なのは1件でした。残り13件は JIRA連携・Teams通知・Zoom会議作成といった、初期状態で無効のまま同梱されているテンプレートです。
「Flowが14件ある」と「14件の自動処理が動いている」は別の話です。有効フラグが列として出るので、設計書には稼働しているものだけを書けます。
紐付けは確度を分けて出る
Flow とテーブルの対応は、トリガー定義から確定した情報として出力されます。名前が似ているだけの Flow は「参考」として別の表に分けてあります。
同じ考え方で、スクリプトインクルード・スケジュールジョブ・REST連携は文字列一致による検索であることを出力に明記しています。確定情報と手掛かりが混ざらないので、設計書に転記するとき「ここは個別確認が要る」と判断できます。
実行前に確認すること
読み取り専用とはいえ、他人が書いたスクリプトを本番に貼るのは怖いものです。次の順で確認してください。
更新系のメソッドが無いこと。update( insert( deleteRecord( deleteMultiple( setValue( を検索して0件であることを目視する
スコープ。global で実行する。スコープドアプリのテーブルは、クロススコープアクセスの設定によっては読めない
実行時間帯。メタデータへの集計クエリが走るため、業務時間外を選ぶ
対象の指定。TABLE_NAME を間違えると、意図しないテーブルを丸ごと調べることになる
まずは PDI か開発環境で1回流し、出力の形を見てから本番に持っていくのが安全です。
出力が期待と違うときは、症状で見る場所が決まります。ある章が丸ごと「テーブルが存在しません」になるなら、その機能を導入していないか、global から読めないかのどちらかです。件数が明らかに多すぎるときは、フィルタが効いていない可能性を疑います。ServiceNow は存在しないフィールド名で addQuery() すると、警告を出しつつその条件を無視して処理を続けるためです。絞り込んだつもりが上限件数まで丸ごと出ます。
なぜレポートではなくバックグラウンドスクリプトなのか
「レポートやダッシュボードでよくないか」という疑問は当然です。使い分けを整理しておきます。
レポートは決まった指標を継続監視する道具です。対してこの方法は、設計書という一度きりの成果物のために、散らばった設定を1回で拾うものです。目的が違います。設計書を書くたびにレポート定義を20個作るのは割に合いません。
移植性も理由の1つです。バックグラウンドスクリプトなら、顧客環境でも検証環境でも、貼り付けるだけで同じ調査ができます。Update Set の移送も、プラグインの有効化も要りません。環境に何も残さないのは、調査道具として大事な性質です。
裏を返すと、継続的な監視には向きません。四半期ごとに設計書を最新化したいなら、都度実行して差分を見る使い方になります。
この方法の限界
取れないものも、はっきりさせておきます。
画面の見た目そのものは取れません。分かるのはフォームのセクション構成と項目の並びまでで、実際のレンダリング結果までは届きません。Service Portal や UI Builder ではこの差がさらに開きます。ウィジェットの配置は取れても、表示された画面がどう見えるかはメタデータからは再現できないためです。スクリーンショットの代わりにはならない、と割り切ってください。
紐付けが曖昧な章があることもお伝えしておきます。スクリプトインクルード・スケジュールジョブ・REST連携の3つは、テーブル名の文字列一致で拾っています。ServiceNow のデータ構造上、「このスクリプトインクルードは incident 用」という明示的な関連が存在しないためです。incident で59件のスクリプトインクルードが引っかかりましたが、この全部が本当に関連するとは限りません。設計書に転記するときは個別確認が要ります。
ビジネスルールの中身も対象外です。76件あることと、それぞれの名前・実行タイミング・条件は取れます。しかし各ルールが何をしているかまでは追いません。改修時に該当分だけ個別に読む、という前提です。
取れるものと取れないものを分けておくと、設計書の「本書で扱わない範囲」の章がそのまま書けます。
用語
この記事に出てくる ServiceNow 用語を整理しておきます。
バックグラウンドスクリプト（Background Script）：管理者がサーバサイドの JavaScript をその場で実行する画面。sys.scripts.do でアクセスする
GlideRecord：レコードを検索・読み書きするための標準API。今回は読み取りにのみ使用
GlideAggregate：件数や合計を集計するためのAPI。全件を取り出さずに件数だけ数えられる
ACL（Access Control List）：誰がどのテーブル・フィールドに何をできるかを定める規則。table と table.field の2階層に加え、* によるワイルドカード指定がある
UIポリシー：条件に応じて画面上の項目を表示・非表示・必須・読み取り専用に切り替える設定。コードを書かずに設定できる
データポリシー：UIポリシーと似ているが、サーバ側で動くため画面経由でも連携経由でも同じ規則が効く
Data Lookup（データ参照定義）：入力値の組み合わせから別の値を自動決定する仕組み。影響度と緊急度から優先度を決めるのが代表例
glide_var：値を専用テーブル（sys_variable_value）に外出しして保持するフィールド型。Flow のトリガー入力値がこれにあたる
glide_duration：期間を表す型。内部的にはエポック起点の日時で保持されるため、getValue() ではなく getDisplayValue() で読む
3部作の構成
本記事（無料）：材料集めから設計書までの4ステップと、出力の読みどころ
出力編（¥100）：3テーマの実出力と、そこから起こしたWord風設計書12ページ
全文編（¥300）：スクリプト全文1,724行＋レポート作成プロンプト
自分の環境で確認するときのURL
スクリプトを作るうえで実際に参照した公式ドキュメントです。
検証範囲とおことわり
確認した範囲：本スクリプト（v1.0）を PDI（Zurich / 2026-08-01）の Scripts - Background で3テーマ（incident / カタログアイテム / Service Portal）実行し、いずれもエラー0で完走。本文の件数・行数・実行時間は全てこの実行の出力から転記しています
フォーム定義とFlow紐付けの仕様（view にリテラル文字列が入る点、sys_variable_value に紐付けが入る点）は、この環境のレコードを直接確認して特定したものです
確認していない範囲（断定しません）：本番規模の環境での実行時間、ドメイン分離環境での挙動、他リリースでの同一性。特にメタデータのテーブル構造はリリースで変わり得ます
スクリプトインクルード・スケジュールジョブ・REST連携の抽出は文字列一致によるヒューリスティックです。出力にも確度の別を明記していますが、設計書へ転記する際は個別確認が要ります
設計書づくりで時間を食うのは、書く作業ではなく集める作業です。集めるところを機械に任せると、考える時間が戻ってきます。
