ナレッジ管理モジュールの開発設計書

ナレッジ管理の開発設計書は、OOTBに既にある802件の定義を出発点として使えます。設計の大半は「どれをそのまま使い、どれを変えるか」の記述になります。この記事は、Australia の PDI の構成を前提とした開発設計書のサンプルです。目次構成と記述の粒度を、そのまま自社の設計書に流用できる形にしています。

本書に含む章

• ナレッジ管理の開発設計書に必要な章立て

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

• User Criteriaを正本とする権限設計の書き方

• SLA定義を構造的に持てない機能の代替設計

• 移送計画に残すべき順序とパラメータ

本記事で扱う内容

• 設計書の中心は、標準機能の採否と変更点の記録に置く

• kb_knowledgeがtaskを継承せず、それ自身が5つの記事型のスーパークラスになる構造を前提にした設計

• IT以外4KBのworkflow欄のように、メタデータ上は壊れている参照をどう扱うか

設計書の章立て

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章以降の各設計章も、中心はOOTB実装をどう設計として採用したかの記述です。標準のまま使う部分も「なぜその構造で足りるのか」を1文で残し、変更する部分にはその判断の経緯を書きます。追加開発を行うときの決まり（order帯・命名規則・追加時の判断基準）は、各章末に「拡張時の決まり」としてまとめ、実装の設計そのものと混在させません。

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

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

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

適用範囲は kb_knowledge と、そのサブクラス5種（FAQ／How To／KCS Article／Known Error article／What Is）、kb_knowledge_base・kb_category・kb_version・kb_feedback など周辺の設定テーブルとする。Incident・Problem管理そのものの設計は含まない。連携する部分のみ第11章に記載する。

第2章：前提条件

項目内容対象バージョンAustraliaベースとする状態OOTB（プラグイン追加・カスタマイズなし）アプリケーションスコープGlobal 中心（一部 sn_km_center／sn_kb_social_qa／sn_km_mr が併存）主テーブルkb_knowledge（super_class 空欄・独立ベーステーブル）サブクラスkb_template_faq／how_to／kcs_article／known_error_article／what_is の5種（kb_knowledge を継承）

kb_knowledge は Incident・Problem のような task 継承ではなく、それ自身が5つの記事型のスーパークラスになっている。この構造を前提に、5章以降の設計を進める。

有効なプラグイン（13件）

com.glideapp.knowledge（コア） / com.glideapp.knowledge_artifacts / com.snc.knowledge_serviceportal /
com.snc.knowledge_advanced / com.snc.knowledge_advanced.installer / com.snc.knowledge.guided_setup /
com.glideapp.knowledge2.wiki / com.sn_knowledge_overview / com.glideapp.report.knowledge.overview /
com.snc.best_practice.problem.madrid.knowledge / com.sn_component_workspace_knowledge /
com.devsnc_sn_knowledge_content / com.snc.knowledge3.graphql

無効なプラグイン（11件）

com.devsnc_sn_knowledge_blocks_connected / com.glideapp.knowledge.i18n2 / com.snc.knowledge_blocks /
com.snc.knowledge_document / com.snc.knowledge.ms_word / com.snc.knowledge.external_integration /
com.snc.knowledge_kcs_capabilities / com.snc.kb_product_entitlements / com.snc.pa.knowledge_v2 /
com.snc.knowledge_ml / com.snc.incident.knowledge

本環境で壊れている参照

IT以外4KB（Governance, Risk, and Compliance／KCS Knowledge Base／Knowledge／Known Error）は、旧 workflow／retire_workflow 項目を持つ。この2項目は wf_workflow テーブルへの参照 sys_id を保持するが、該当レコードは存在しない。連携方式は第11章で定める。

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

第3章：システム構成

3-1. 設計方針

1. 本実装は、kb_knowledgeと周辺設定を6層（データ・画面・権限・処理・期限と通知・設定値）に分けて構成する。上位の層（画面）が下位の層（権限・処理）を呼び出し、処理層が期限と通知の層を駆動する一方向の依存関係を持たせる

2. 権限の可否判定はACL単体で完結させず、User Criteria（第7章で扱う）を正本として置く構造とする

3. 各層の件数は「総数」と「そのうち何件を触るか」を併記し、変更点は「ACL 3件追加」のように1行で追跡できる形にする

3-2. 設計図

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

3-3. 設計項目

層総数本設計での扱いデータ（フィールド）73（kb_knowledge固有60＋5サブクラス追加13）追加なし。既存の未使用項目で対応画面（UIポリシー・スクリプト・UIアクション・データポリシー）58標準を採用。Workspace/Classicの差異を踏まえて追加を判断権限（ACL・ロール・User Criteria）583（ACL565＋ロール8＋User Criteria10）User Criteriaを正本とする（第7章）処理（ビジネスルール・Flow）69（BR60＋Flow9）標準を採用。追加は専用のorder帯期限と通知（SLA・通知）4（SLA定義は構造上0。通知のみ）SLAは代替設計、通知は条件調整設定値（プロパティ）15複製・連携対象項目の一部を変更

3-4. 詳細設計

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

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

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

実測値による裏付け

本環境のデモデータは kb_knowledge が53件にとどまる。それでも6層の定義件数（73／58／583／69／4／15）は変わらない。定義とレコードは別の実測対象であり、本設計書が扱うのは前者である。検証環境のレコード件数が少なくても、この表の数字をそのまま工数の見積もりに使ってよい。

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

• 参考：Knowledge だけ task 系でない（kb_knowledge） … 独立ベーステーブルという前提の詳細

第4章：OOTB実装設計

4-1. 設計方針

1. 本実装は、Known Error連携・版数管理・可視性の絞り込み・承認/即時公開の切り替えという主要4要件を、すべて段階1（標準のまま）または段階2（設定変更）で満たす構成とする。段階4（独自実装）は1件も採用しない

2. 採否は要件・採用した方法・不採用案・理由の4項目で記録し、標準のまま使うという判断も明示的な決定として残す

4-2. 設計図

下の段階へ進むほど保守の負担が増える。独自実装はアップグレード時の再検証が必要になるため、本実装では採用していない。

4-3. 設計項目

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

4段階のうち、本実装が実際に使うのは段階1・2の2つだけである。

4-4. 詳細設計

主要4要件は、いずれも標準機能の組み合わせで満たしている。要件ごとの採用方式と、検討したが採らなかった案を記録する。

要件採用した方法不採用案理由恒久対策前の暫定情報を記事化したい標準の primary_known_error_article ＋ kb_template_known_error_article ＋専用KB（段階1）独自テーブルでの管理原因・説明・回避策の3項目とProblem連携が既に一式そろっているため記事の版数を管理したい標準の kb_version ＋Versioning系ビジネスルール（段階1）独自の履歴テーブルPublish遷移で自動採番される仕組みが既に用意されているためKB単位で読める人・書ける人を絞りたい標準のUser Criteria（段階2）ACLの個別追加4つの中間テーブルでKB管理者自身が調整できる仕組みが既にあるため公開・退役に承認を挟むKBと即時公開のKBを分けたい標準のFlow Designer 9フロー（段階2）独自Workflowの新設旧wf_workflowは0件で、標準がFlow Designerへ完全移行済みのため

承認方式を決める基準

本環境では、IT KBだけ承認あり（Approval）で、残り4KBは即時公開（Instant）である。したがって本設計では、公開範囲が広いKBかコンプライアンス関与KBに承認あり、社内限定KBに即時公開を割り当てる。

割り当ては、kb_knowledge_baseのkb_publish_flow・kb_retire_flowへFlowを直接指定する。承認者はowner1名でなくグループが担う。以下は推奨例であり、組織名等は導入先の体制で確定する。

KB区分承認方式承認者の設計例全社公開・主力KB（IT相当）ApprovalKBオーナー部門の管理者グループ社内限定・少人数運用KBInstant承認者なし（owner1名が事後確認）コンプライアンス関与KBApproval法務・コンプライアンス部門の代表者グループ

拡張時の決まり

新しい要件が生じたときは、「標準のまま → 設定変更 → 標準の拡張点 → 独自実装」の順に検討し、上の段階で満たせないことを確認してから次の段階へ降りる。判断は要件・採用した方法・不採用案・理由の4項目で記録し、アップグレード時は新版で追加された標準機能とこの記録の「不採用案」欄を照合する。

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

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

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

• 第5章 データ設計：kb_knowledge固有60項目とサブクラス13項目の設計表、版数管理の記入例

• 第6章 画面設計：Default view とWorkspace viewのフィールド差異、実現方法の選択基準

• 第7章 権限設計：User Criteriaを正本とする設計と、ACLの位置づけ

• 第8章 処理設計：order分布83%集中の扱いと、二重の保険になっているデータポリシー

• 第9章 通知設計：4件の宛先方式と条件調整の指針

• 第10章 SLA設計：SLA定義0件からの代替設計（valid_to・承認期限）

• 第11章 外部連携設計：csm_field_map5項目マッピングと、壊れた参照の扱い

• 第12章 移送設計：KBとUser Criteriaの移送順序

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

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

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

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