サービスカタログの開発設計書

サービスカタログの実装には、意図をもって組まれた構造がいくつもあります。2つの履行エンジン（WorkflowとFlow Designer）は、同じsc_req_item上でorder番号によって排他的に起動する構造です。権限判定は86%をロール指定に寄せ、User Criteria728件で可視性を補う構造も持ちます。この記事は、Australia の PDI で実測したOOTB実装を、この実装が採った設計として書き起こした開発設計書のサンプルです。目次構成と記述の粒度を、そのまま自社の設計書に流用できる形にしています。

本書に含む章

• サービスカタログの開発設計書に必要な章立て

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

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

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

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

本記事で扱う内容

• 設計書の中心は新規開発の記述ではなく、標準機能の採否と、採用した構造の記録

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

• Workflow と Flow Designer が同じsc_req_item上でorder番号により排他的に起動する構造を、設計としてどう記述するか

全体像

各章の詳細設計に入る前に、サービスカタログを構成する要素どうしの関係を1枚にまとめます。

中心にあるのはsc_request→sc_req_item→sc_taskという申請データです。カタログ定義（sc_cat_item・変数item_option_new・変数セットitem_option_new_set）は別系統の設定オブジェクトで、sc_req_itemに対して「アイテムの選択」と「回答の保存」という2つの経路で接続します。画面層・権限層・処理層・通知とSLA・設定値の5層は、この申請データを取り囲んで動きます。

承認（sysapproval_approver）だけは、この6層のどれにも収まりません。第3章で詳しく扱いますが、実行時に動く標準Flowには承認用のアクションが含まれておらず、権限層のロール定義（sn_request_approver_read）は「承認レコードを持っているかどうか」だけで可否を判定します。したがって本書では、承認を独立した共通機構として図の右側に切り出して描いています。

設計書の章立て

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 のサービスカタログを自社向けに構築するための設計を定める。

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

適用範囲は sc_request・sc_req_item・sc_task の3テーブル、およびカタログ側の sc_cat_item・item_option_new に紐づく設定とする。標準変更カタログとApp Engine Studioとの連携は、第11章で扱う範囲に限定する。

第2章：前提条件

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

有効なプラグイン

com.glideapp.servicecatalog / com.glideapp.servicecatalog.flow_designer /
com.glideapp.servicecatalog.execution_plan / com.glideapp.servicecatalog.catalog_builder /
com.glideapp.servicecatalog.portal / com.glideapp.servicecatalog.request_management.delegated_request_experience /
com.snc.change_management.standard_change_catalog / com.snc.pa.request

無効なプラグイン

com.snc.universal_request とその周辺6件（.awa / .ml / .nlu / .reporting / .va / .pa）、
com.snc.pa.request2、com.glide.ui.ng.cc。Universal Request一式は7件とも無効である。

本環境で実体を持つが機能していない項目

task.universal_request は sys_dictionary にもREST APIのフィールド一覧にも存在し、メタデータ上は正規のフィールドとして扱われる。関連するプラグイン7件がすべて無効のため、値は常に空欄で推移する。第11章では、この項目を前提にした連携方式は採用しない。

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

第3章：システム構成

3-1. 設計方針

1. sc_request・sc_req_item・sc_task およびカタログ側の定義を6つの層（データ・画面・権限・処理・通知とSLA・設定値）で管理する

2. 各層の件数は「総数」と「アクティブ」を区別して併記する。総数だけでは実働している件数を見誤る

3. 承認（sysapproval_approver）は特定の層の内訳件数に含めず、データ層・権限層をまたぐ独立した共通機構として扱う

4. 変更の記録は ACL106件（3テーブル対象・追加は本設計で規定） の形式で1行にまとめる

3-2. 設計図

最上段のカタログ定義が、開発でつくる対象になる。アイテム・変数・変数セットの定義が、注文時に各層へ流れ込む。回答はデータ層へ保存され、変数の表示・必須は画面層が制御し、見せる相手は権限層のUser Criteriaが決め、履行エンジンと履行計画の指定は処理層で実行される。画面層は本体テーブルではなく変数側に処理が集中し、権限層はACLとUser Criteriaという性格の異なる2つの機構で構成される。処理層の履行エンジンはFlow・旧Workflow・履行計画の3系統があり、本環境の旧Workflowは参照60件に対して定義0件で動作しない。通知とSLAの層はApp Intakeとの共用を含む。設定値の層は処理層と通知層の挙動を外から変える。承認だけはこの一直線の流れに乗らず、承認ルールとフローが生成したレコードの有無で権限層の判定を左右する横断機構になっている。

3-3. 設計項目

層総数本設計での扱いデータ30（sc_request9・sc_req_item16・sc_task5）追加なし。既定値の一部を変更画面261（カタログUIポリシー103・アクティブ101／カタログClient Script141・アクティブ138／UIアクション17）標準を採用。本体のUIポリシーは対象外権限834（ACL106・業務3テーブル対象＋User Criteria728・カタログ項目対象）標準を採用。追加はフィールド単位とカタログ項目単位に分ける処理43（sc_request10・sc_req_item20・sc_task13）標準を採用。追加は専用のorder帯通知とSLA31（通知31・SLA定義0）App Intake系16件は対象外。SLAは自社基準で新規定義設定200（Request専用の名前空間は0）挙動を変える項目のみ変更カタログ定義sc_cat_item 204（有効152）・変数676・変数セット22（割当49）開発の主対象。共通入力は変数セットに集約履行エンジンFlow59・Workflow55・両方5・未設定85（アイテム204件）＋履行計画70件Flowを標準とする。Workflow参照は定義0件のため使用しない承認（横断機構）sysapproval_approver（レコード有無で判定）REQ宛ては承認ルール有効4件、RITM宛てはRITM用フローが生成（実測）。既存アイテムのworkflow/flowを個別確認

3-4. 詳細設計

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

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

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

実測値による裏付け

本環境のデモデータは sc_request が3件、sc_req_item が7件、sc_task が2件にとどまる。それでも6層の定義件数（30・261・834・43・31・200）は変わらない。定義とレコードは別の実測対象であり、本設計書が扱うのは前者である。検証環境のレコード件数が少なくても、この表の数字をそのまま工数の見積もりに使ってよい。

承認は処理層が生成する横断機構

実行時の観測で、承認レコードの生成元を特定した。REQ宛ての承認は承認ルール（sysrule_approvals）が作る。sc_requestには「Catalog Request Approval > $1000」など有効4件が定義され、$1,100のノートPC注文では注文の4秒後にREQ宛て承認レコードが生成された。RITM宛ての承認は、RITM用フロー「Service Catalog item request」の起動5秒後に生成された。同フローの直下アクションはログ出力1件とタスク生成4件で、承認アクションが直下に無いため、生成の内部経路（サブフロー等）は本番導入前の検証事項とする。旧Workflowエンジンは本環境では定義が0件（wf_workflow・wf_activity・wf_contextすべて0件）で、承認の生成に関与しない。承認の可否判定は、ロール sn_request_approver_read の公式説明が示すとおり、レコードそのものの有無で行われる。

（訳: リクエスト管理アプリケーションおよび関連機能への読み取りアクセス。ユーザーがそのリクエストレコードに対する承認レコードを持つ場合のみアクセスを許可する）

引用元: /sys_user_role_list.do?sysparm_query=name=sn_request_approver_read

したがって本設計では、承認を6層のいずれか1つには割り当てず、sysapproval_approver という独立した共通機構として扱う。権限判定はこのテーブルのレコード有無に依存させ、処理層（2つの履行エンジン）への組み込みは行わない。自社でカタログ項目ごとに承認経路を追加・変更する場合は、対象アイテムのworkflow・flow_designer_flowの中身を個別に確認してから着手する（第13章 制約事項参照）。

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

• 参考：Employee Centerのコンテンツはどう出し分けられる？ User Criteriaを実機で確認 権限層のもう一つの機構

• 参考：承認は2段構え：1段目だけでは履行が始まらない（RITM/Catalog Task） 承認の実務構造

第4章：OOTB実装設計

4-1. 設計方針

1. 要件の実現手段を「標準のまま／設定変更／標準の拡張点／独自実装」の4段階に分類し、採用した段階を4-4の表に記録する構造とする

2. 4-4で確定した4件の判断のうち、独自実装（段階4）を選んだ要件は0件である。すべて標準のカタログ機構とFlow Designerの範囲で実現する

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

4-2. 設計図

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

4-3. 設計項目

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

4-4. 詳細設計

本設計では、4件の要件についてOOTB機能の採否を次のとおり判断した。表1行が1つの判断に対応する。

要件採用した方法不採用案理由定型の物品・アクセスをカタログから申請させたい標準のCatalog Item + Variables（段階1）独自の申請フォームカタログ204件・変数676件という定義済みの器がすでにあるため承認後にタスクを自動で作りたいdelivery_planとCatalogTaskGenerator（段階1）ビジネスルールの新規作成標準の履行タスク生成機構が用意されているため新規カタログ項目の履行を自動化したいFlow Designerで新規フローを作成（段階2〜3）旧Workflowの新規作成Flow Designerが新しい実装方式として案内されており、既存の新規流入59件がすでにFlow側に寄っているため標準変更をカタログから起票させたいstd_change_record_producerの活用（段階1）独自のRecord Producer6件のテンプレートがchange_requestへ直接接続する構成ですでに動くため

4件とも段階1〜3の範囲で実現し、独自実装（段階4）は採用していない。判断の記録は、アップグレード時の判断材料としても使う。新しいバージョンで置き換え候補の標準機能が追加された場合、この記録の「不採用案」欄と照合する。

• 参考：サービスカタログのテーブル・フィールド構成 テーブル構成の基礎

• 参考：Record Producerが直接RITMでなくフォーム経由でsc_req_itemを作る流れ 拡張点を検討する前に見る基本形

拡張時の決まり

新しい要件を追加するときは、実現方法を「標準のまま → 設定変更 → 標準の拡張点 → 独自実装」の順に検討し、上の段階で要件を満たせないことを確認してから次の段階へ降りる。独自実装はアップグレード時の再検証が必要になるため、最後の選択肢とする。

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

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

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

• 第6章 画面設計：ui_typeがPortalに効かない実例と避けるべき実装

• 第7章 権限設計：ACLとUser Criteriaという2レイヤーの役割分担

• 第8章 処理設計：2つの履行エンジンの実行順とカスケードBR群

• 第9章 通知設計：トリガー→条件→宛先の3要素とApp Intake系16件を対象外にする設計判断

• 第10章 SLA設計：OOB定義0件からRITM単位で定義する指針

• 第11章 外部連携設計：標準変更カタログ・App Intake・Universal Requestの扱い

• 第12章 移送設計：カタログ・変数・画面制御・フローの移送順

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

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

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

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