問題管理モジュールの開発設計書

問題管理の開発設計書を書くとき、白紙から始める必要はありません。OOTBには既に419件の定義があり、設計の大半は「どれをそのまま使い、どれを変えるか」の記述になります。この記事は、Australia の PDI の構成を前提とした開発設計書のサンプルです。目次構成と記述の粒度を、そのまま自社の設計書に流用できる形にしています。

本書に含む章

• 問題管理の開発設計書に必要な章立て

• 各章に何をどの粒度で書くか

• OOTB を採用するか変更するかの判断基準

• 設計書に残すべきパラメータの一覧

• 移送と検証の計画に書く内容

本記事で扱う内容

• 設計書の中心は新規開発の記述ではなく、標準機能の採否と変更点の記録

• problem_task が problem ではなく task を直接継承する構造を前提にした設計

• incident.problem_id のように、メタデータ上は実体のない項目をどう扱うか

設計書の章立て

ServiceNow のモジュール設計書は、次の構成とする。

章内容主な記述1本書の目的と適用範囲対象モジュール・対象環境・読者2前提条件バージョン・プラグイン・既存資産3システム構成テーブル構成と関連する定義の全体像4OOTB実装設計標準機能の採否を判断する順序5データ設計テーブル・項目・選択肢・既定値6画面設計フォーム・UIポリシー・クライアントスクリプト7権限設計ロール・ACL8処理設計ビジネスルール・実行順序9通知設計通知定義・宛先・イベント10SLA設計期限・スケジュール・計測条件11外部連携設計他モジュール・外部システムとの接続12移送設計更新セットの単位・移送対象外の作業13制約事項と留意点アップグレードの影響・既知の課題14検証計画単体・結合の確認項目15用語定義本書で使う用語

このうち3章と4章に、ServiceNow 特有の内容を置く。標準機能が大量に用意されているため、「何を作るか」より先に「何を使うか」を決める必要がある。

スクラッチ開発の設計書では、3章にシステム構成図、4章にアーキテクチャの選定理由を記載する。ServiceNow では、この2章を「標準機能の棚卸し」と「採否の判断基準」に置き換える。

5章以降の各設計章も、記述の中心を変更点に置く。標準のまま使う部分は「標準を採用する」と1行で記載し、変更する部分に紙面を割く。

第1章：本書の目的と適用範囲

本書は、ServiceNow の問題管理モジュールを自社向けに構築するための設計を定める。

対象読者は、設計を担当する技術者とレビューを行う責任者とする。運用の体制・役割・判断基準は、別途の運用設計書で定める。

適用範囲は problem テーブルと problem_task テーブル、およびこれらに紐づく設定とする。インシデント管理・変更管理そのものの設計は含まない。連携する部分のみ第11章に記載する。

第2章：前提条件

項目内容対象バージョンAustraliaベースとする状態OOTB（プラグイン追加・カスタマイズなし）アプリケーションスコープGlobal主テーブルproblem（task を継承）作業タスクproblem_task（problem ではなく task を直接継承）

有効なプラグイン

com.snc.problem / com.snc.problem_task / com.snc.best_practice.problem.jakarta /
com.snc.best_practice.problem.madrid / com.snc.best_practice.problem.madrid.knowledge /
com.snc.best_practice.problem.madrid.state_model / com.snc.problem.atf /
com.snc.pa.problem / com.snc.pa.problem.dashboards / com.glideapp.report.itsm.problem.overview

無効なプラグイン

com.snc.pa.problem.context_sensitive_analytics（コンテキスト連動の分析）/
com.snc.pa.spotlight.problem（Spotlightの異常検知）。いずれも Performance Analytics 系の追加機能である。

本環境で実体を持たない項目

incident.problem_id は sys_dictionary にも REST API のフィールド一覧にも存在しない。ACL 3件とビジネスルール1件に項目名の記述が残るのみで、機能する連携経路としては採用しない。連携方式は第11章で定める。

プラグインの構成が異なる環境では、項目の有無と各種定義の件数が変わる。本書を他環境へ流用する場合、第3章の件数を再計測する。

第3章：システム構成

3-1. 設計方針

1. problem・problem_task に紐づく定義を6つの層（データ・画面・権限・処理・期限と通知・設定値）で管理する

2. 各層の件数は「総数」と「そのうち何件を触るか」を必ず併記する

3. 変更の記録は ACL 146件（追加3・変更2・据置141） の形式で1行にまとめる

3-2. 設計図

保存の流れに沿って層が重なる。画面層が入力を制御し、権限層が書き込みを判定し、処理層が値の補正と連鎖を行い、期限と通知の層が後続を動かす。設定値の層は処理層と通知層の挙動を外から変える。

3-3. 設計項目

層総数本設計での扱いデータ（フィールド）118（problem 102＋problem_task 16）追加なし。選択肢と既定値の一部を変更画面（UIポリシー・スクリプト・UIアクション・データポリシー）84標準を採用。追加は第6章の基準に従う権限（ACL）146標準を採用。追加はフィールド単位処理（ビジネスルール）38（problem 25＋problem_task 13・有効のみ）標準を採用。追加は専用のorder帯期限と通知（SLA・通知）12SLA定義0件のため自社基準で新規定義。通知は条件調整設定値（プロパティ）19複製・連携対象項目の一部を変更

3-4. 詳細設計

件数は工数の見積もりに直結する。ACL 3件の変更と30件の変更では、設計・実装・検証のいずれも規模が一桁違う。標準に手を入れる範囲も、この数字で共有できる。

標準機能をどこまで使うかという方針は、この表の件数と「本設計での扱い」欄で確定する。

計測はテーブルごとに行う。データ層は sys_dictionary、権限層は sys_security_acl、処理層は sys_script を対象とし、本書の付録に記載したURLで再計測できる。プラグイン構成が異なる環境へ本書を流用する場合、この計測を最初にやり直す。

実測値による裏付け

本環境のデモデータは problem が24件、problem_task が1件にとどまる。それでも6層の定義件数（118／84／146／38／12／19）は変わらない。定義とレコードは別の実測対象であり、本設計書が扱うのは前者である。検証環境のレコード件数が少なくても、この表の数字をそのまま工数の見積もりに使ってよい。

• 参考：ServiceNowのフィールド設定はどこに保存される？ sys_dictionaryを実機で読む … データ層の確認方法

• 参考：辞書オーバーライド：継承フィールドを子だけ上書き … problem 12件・problem_task 8件の上書きの仕組み

第4章：OOTB実装設計

4-1. 設計方針

1. 標準機能で満たせる要件は、標準機能をそのまま採用する

2. 実現方法は「標準のまま → 設定変更 → 標準の拡張点 → 独自実装」の順に検討し、上の段階で満たせないことを確認してから次へ降りる

3. 採否の判断は要件・採用した方法・不採用案・理由の4項目で記録する

4-2. 設計図

下の段階へ進むほど保守の負担が増える。独自実装はアップグレード時の再検証が必要になるため、最後の選択肢とする。

4-3. 設計項目

段階実現手段保守の負担1. 標準のままOOTB の機能・定義なし2. 設定変更プロパティ・選択肢・UIポリシー小。設定値の記録のみ3. 標準の拡張点ビジネスルール・スクリプトの追加中。アップグレード時に動作確認4. 独自実装独自テーブル・独自画面大。アップグレード時に再検証

4-4. 詳細設計

採否の判断は次の形式で記録する。表1行で1つの判断を表し、参照資料として使える構成にする。

要件採用した方法不採用案理由Known Error を記録として残したい標準の known_error / primary_known_error_article / 専用KB（段階1）独自テーブルでの管理恒久対策前の暫定運用を示す仕組みが一式そろっているため原因究明の作業を分割したいproblem_task の使用（段階1）独自テーブルの追加task直下の標準テーブルとして problem_task が既に用意されているため優先度を自動で決めたい標準の dl_problem_priority（段階1）クライアントスクリプトImpact×Urgency の9通りマトリクスが既に用意されているためカテゴリ別に担当グループを自動振分したい割り当てルールの有効化（段階2）ビジネスルールの新規作成CI種別・Business Serviceでの振分がすでに定義されているため

判断の記録は、アップグレード時の判断材料としても使う。新しいバージョンで置き換え候補の標準機能が追加された場合、この記録の「不採用案」欄と照合する。

• 参考：Business RuleやScript Includeを一括棚卸しする読み取り専用スクリプト … 標準・追加分の切り分けに使える棚卸し手法

この記事の有料部で得られるもの

ここまでで、設計書の章立てと基本方針の書き方が分かります。有料部では、5章から15章までの記述サンプルを載せます。

• 第5章 データ設計：パラメータ15項目の設計表（OOTB値・採否・変更内容）

• 第6章 画面設計：実現方法の選択基準と、避けるべき実装

• 第7章 権限設計：ロール階層とACLの追加位置・admin_overridesの方針

• 第8章 処理設計：orderの割り当て規則と命名規則

• 第9章 通知設計：event_name不整合2件の設計判断

• 第10章 SLA設計：OOB定義0件からの新規設計指針

• 第11章 外部連携設計：incident.problem_idの実体不在をどう扱うか

• 第12章 移送設計：更新セットの対象と対象外

• 第13章 制約事項：アップグレードで再検証が必要な箇所

• 第14章 検証計画：層別の確認項目14件

分量は本文の後半およそ4,700字です。自社の要件を埋めれば、そのまま開発設計書として使える記述にしています。

💰 ここから先は有料エリア