schema-discovery

スキーマの検出

概要

スキーマの検出は、効果的な ServiceNow 開発の基盤です。このスキルでは、テーブル構造の調査、フィールドタイプの理解、テーブル間のリレーションの検出、開発作業に向けた調査結果の記録方法を学びます。

• どのような問題を解決しますか？ 不慣れなテーブルを扱う際の推測をなくし、フィールドタイプの誤りを防ぎ、ServiceNow エンティティ間に隠れているリレーションを明らかにします
• このスキルは誰が使うべきですか？ クエリ、スクリプト、インテグレーションを作成する前に ServiceNow のデータ構造を理解する必要がある開発者、管理者、インテグレーター
• 期待される成果は何ですか？ テーブルスキーマ、フィールド設定、参照リレーション、適切なフィールドの使用方法を完全に理解できます

前提条件

• 必要な ServiceNow ロール：admin または personalize_dictionary（スキーマへの完全なアクセスに必要）
• sys_dictionary、sys_db_object、sys_documentation テーブルへの読み取りアクセス
• ServiceNow のテーブル階層とフィールドタイプに関する基本的な理解
• 関連スキル：不要（このスキルは基礎となるものです）

手順

ステップ 1：利用可能なテーブルを検出する

まず、ServiceNow インスタンスで利用可能なテーブルを調べます。テーブルは機能に基づいてカテゴリに分類されています。

MCP ツールを使用する場合：

Tool: SN-List-Available-Tables
Parameters:
  category: core_itsm

利用可能なカテゴリ：

• core_itsm - インシデント、問題、変更、リクエスト
• cmdb - 構成管理データベースのテーブル
• service_catalog - カタログアイテム、変数、リクエスト
• security - ユーザー、グループ、ロール、ACL
• system - システムプロパティ、スケジュール済みジョブ、更新セット
• custom - カスタムアプリケーションのテーブル（x_* プレフィックス）

REST API を使用する場合：

GET /api/now/table/sys_db_object?sysparm_query=super_class.name=task^ORsuper_class.name=cmdb_ci&sysparm_fields=name,label,super_class&sysparm_limit=50

判断ポイント：

• ITSM テーブルを探す場合 → カテゴリ core_itsm を使用します
• CMDB を調べる場合 → カテゴリ cmdb を使用します
• カスタムアプリに取り組む場合 → カテゴリ custom を使用するか、スコープのプレフィックスでクエリします

ステップ 2：テーブルスキーマを取得する

テーブルを特定したら、すべてのフィールド、タイプ、設定を含む完全なスキーマを取得します。

MCP ツールを使用する場合：

Tool: SN-Get-Table-Schema
Parameters:
  table_name: incident

REST API を使用する場合：

GET /api/now/table/sys_dictionary?sysparm_query=name=incident^internal_type!=collection&sysparm_fields=element,column_label,internal_type,max_length,mandatory,reference

想定されるレスポンスフィールド：

フィールド	説明
element	内部フィールド名
column_label	表示ラベル
internal_type	フィールドタイプ（string、reference、integer など）
max_length	最大文字数
mandatory	フィールドが必須かどうか
reference	参照フィールドの対象テーブル
default_value	デフォルト値（設定されている場合）
choice	フィールドが選択肢リストを使用するかどうか

ステップ 3：リレーションを含む詳細なスキーマ検出

複雑なインテグレーションでは、親テーブル、子テーブル、参照チェーンを含む完全なリレーションマップを検出します。

MCP ツールを使用する場合：

Tool: SN-Discover-Table-Schema
Parameters:
  table_name: incident
  include_relationships: true
  depth: 2

REST API を使用する場合：

# Get table hierarchy (parent/child)
GET /api/now/table/sys_db_object?sysparm_query=name=incident&sysparm_fields=name,super_class,label

# Get all reference fields
GET /api/now/table/sys_dictionary?sysparm_query=name=incident^internal_type=reference&sysparm_fields=element,reference

# Get tables that reference this table
GET /api/now/table/sys_dictionary?sysparm_query=reference=incident&sysparm_fields=name,element

検出するリレーションタイプ：

リレーション	説明	例
継承	親テーブルの階層	incident は task を拡張
参照	外部キーのリレーション	incident.assigned_to -> sys_user
Glide List	複数値の参照	incident.watch_list -> sys_user（リスト）
ドキュメント ID	動的なテーブル参照	sys_attachment.table_sys_id

ステップ 4：フィールドタイプを理解する

フィールドタイプによって、動作、保存特性、クエリ構文は異なります。

ServiceNow の一般的なフィールドタイプ：

タイプコード	タイプ名	説明	クエリ例
string	文字列	max_length までのテキスト	short_description=test
integer	整数	整数値	priority=1
boolean	真／偽	ブール値	active=true
reference	参照	別のテーブルへの外部キー	assigned_to.name=admin
glide_date	日付	日付のみ	due_date>2024-01-01
glide_date_time	日付／時刻	時刻を含む日付	sys_created_on>=javascript:gs.daysAgo(7)
choice	選択肢	事前定義された選択肢	state=1
journal	ジャーナル	追記専用テキスト	直接クエリできません
journal_input	ジャーナル入力	作業メモ／コメント	work_notesLIKEupdate
script	スクリプト	JavaScript コード	該当なし
conditions	条件	エンコードされたクエリ	該当なし

ステップ 5：フィールドのドキュメントを取得する

不明なフィールドについては、使用例やベストプラクティスを含む詳細なドキュメントを取得します。

MCP ツールを使用する場合：

Tool: SN-Explain-Field
Parameters:
  table_name: incident
  field_name: impact

REST API を使用する場合：

# Get field definition
GET /api/now/table/sys_dictionary?sysparm_query=name=incident^element=impact&sysparm_fields=element,column_label,internal_type,comments,hint

# Get field documentation
GET /api/now/table/sys_documentation?sysparm_query=name=incident^element=impact&sysparm_fields=text,short_description

ドキュメントに含まれる内容：

• フィールドの目的と業務上の意味
• 有効な値（選択肢フィールドの場合）
• 関連フィールドと依存関係
• 一般的なユースケース
• API の動作に関する注記

ステップ 6：選択肢の値を調べる

選択肢フィールド（ドロップダウン）について、有効な値とその意味をすべて確認します。

MCP ツールを使用する場合：

Tool: SN-Query-Table
Parameters:
  table_name: sys_choice
  query: name=incident^element=state
  fields: value,label,sequence

REST API を使用する場合：

GET /api/now/table/sys_choice?sysparm_query=name=incident^element=state&sysparm_fields=value,label,sequence&sysparm_orderby=sequence

一般的な選択肢テーブル：

テーブル	用途
sys_choice	標準フィールドの選択肢
question_choice	カタログ変数の選択肢
sys_choice_set	再利用可能な選択肢セット

ステップ 7：調査結果を記録する

開発作業用のスキーマ参照ドキュメントを作成します。

スキーマドキュメントのテンプレート：

## Table: incident

### Hierarchy
- Parent: task
- Children: None

### Key Fields
| Field | Type | Required | Reference | Notes |
|-------|------|----------|-----------|-------|
| number | string | auto | - | Auto-generated |
| short_description | string | yes | - | Max 160 chars |
| assigned_to | reference | no | sys_user | Can be empty |
| state | integer | yes | - | Choice: 1-8 |

### State Values
| Value | Label |
|-------|-------|
| 1 | New |
| 2 | In Progress |
| 3 | On Hold |
| 6 | Resolved |
| 7 | Closed |
| 8 | Canceled |

### Key Relationships
- assignment_group -> sys_user_group
- caller_id -> sys_user
- cmdb_ci -> cmdb_ci
- problem_id -> problem

ツールの使用方法

MCP ツール（Claude Code/Desktop）

ツール	目的	使用する場面
SN-List-Available-Tables	カテゴリ別にテーブルを一覧表示する	調査の開始時
SN-Get-Table-Schema	フィールド定義を取得する	テーブル構造の理解
SN-Discover-Table-Schema	詳細なリレーションシップを調べる	複雑な連携
SN-Explain-Field	フィールドのドキュメントを取得する	不明なフィールド
SN-Query-Table	sys_choice、sys_dictionary をクエリする	カスタムスキーマクエリ

REST API（ChatGPT／その他）

エンドポイント	メソッド	目的
/api/now/table/sys_db_object	GET	テーブルの一覧表示
/api/now/table/sys_dictionary	GET	フィールド定義の取得
/api/now/table/sys_choice	GET	選択肢の値の取得
/api/now/table/sys_documentation	GET	フィールドのドキュメントの取得
/api/now/table/sys_glide_object	GET	フィールドタイプ定義の取得

ネイティブツール（Claude Code）

ツール	目的
Bash	REST API 用の curl コマンドを実行する
Read	キャッシュされたスキーマファイルを読み取る

ベストプラクティス

• スキーマ情報をキャッシュする： スキーマはほとんど変更されないため、API 呼び出しを減らせるよう結果をローカルにキャッシュします
• 親テーブルから始める： incident の前に task、cmdb_ci_computer の前に cmdb_ci を理解します
• sys_dictionary と sys_db_object の両方を確認する： Dictionary にはフィールドがあり、db_object にはテーブルのメタデータがあります
• 参照チェーンを記録する： incident -> assignment_group -> sys_user_group はドットウォーキングに役立ちます
• まず開発環境で確認する： カスタマイズによってインスタンス間でスキーマが異なる場合があります
• エンコードされたクエリビルダーを使う： コードに組み込む前に ServiceNow UI でクエリをテストします

トラブルシューティング

よくある問題 1：スキーマにフィールドがない

症状： 期待したフィールドがスキーマの結果に表示されない 原因： フィールドが子テーブルではなく親テーブルにある可能性があります 解決策： 親テーブルにクエリするか、SN-Discover-Table-Schema を depth パラメーターとともに使用します

Tool: SN-Discover-Table-Schema
Parameters:
  table_name: incident
  include_parent_fields: true

よくある問題 2：sys_dictionary の権限が拒否される

症状： sys_dictionary のクエリ時に 403 エラーが発生する 原因： personalize_dictionary または admin ロールがありません 解決策： 適切なロールを申請するか、テーブル固有のエンドポイントを使用してください

# Alternative: Use table API with schema
GET /api/now/table/incident?sysparm_limit=1&sysparm_display_value=all
# Response headers include field metadata

よくある問題 3：参照フィールドに値ではなく sys_id が表示される

症状： 参照フィールドから表示値ではなく sys_id が返される 原因： sysparm_display_value パラメーターを使用していません 解決策： クエリに display_value パラメーターを追加してください

Tool: SN-Query-Table
Parameters:
  table_name: incident
  display_value: all

よくある問題 4：選択肢の値が見つからない

症状： 選択肢フィールドに対する sys_choice の結果が空になる 原因： フィールドが選択肢セットを使用しているか、別の方法で定義されています 解決策： sys_choice_set を確認するか、依存値を指定してクエリしてください

Tool: SN-Query-Table
Parameters:
  table_name: sys_choice
  query: name=incident^element=subcategory^dependent_value=network

例

例 1：CMDB コンピューターのスキーマを調べる

# Step 1: List CMDB tables
Tool: SN-List-Available-Tables
Parameters:
  category: cmdb

# Result: Lists cmdb_ci, cmdb_ci_computer, cmdb_ci_server, etc.

# Step 2: Get cmdb_ci_computer schema
Tool: SN-Get-Table-Schema
Parameters:
  table_name: cmdb_ci_computer

# Result:
Fields:
- cpu_core_count (integer)
- cpu_count (integer)
- cpu_speed (float)
- disk_space (float)
- ram (integer)
- os (string)
- os_version (string)
- serial_number (string)
- [inherited from cmdb_ci: name, ip_address, manufacturer, etc.]

# Step 3: Understand OS field
Tool: SN-Explain-Field
Parameters:
  table_name: cmdb_ci_computer
  field_name: os

# Result:
- Type: String
- Label: Operating System
- Description: Operating system name
- Common values: Windows, Linux, macOS
- Related field: os_version

例 2：インシデントの参照関係をマッピングする

# Discover all relationships from incident table
Tool: SN-Discover-Table-Schema
Parameters:
  table_name: incident
  include_relationships: true
  depth: 2

# Result:
Table: incident
Extends: task

Reference Fields:
- assigned_to -> sys_user
  - sys_user.manager -> sys_user (depth 2)
  - sys_user.department -> cmn_department (depth 2)
- assignment_group -> sys_user_group
  - sys_user_group.manager -> sys_user (depth 2)
  - sys_user_group.parent -> sys_user_group (depth 2)
- caller_id -> sys_user
- cmdb_ci -> cmdb_ci
  - cmdb_ci.location -> cmn_location (depth 2)
  - cmdb_ci.support_group -> sys_user_group (depth 2)
- problem_id -> problem
- rfc -> change_request

Reverse References (tables referencing incident):
- incident_sla.task -> incident
- incident_alert.incident -> incident
- sc_task.incident -> incident

例 3：カタログ変数のスキーマを調べる

# Step 1: Get catalog variable types
Tool: SN-Query-Table
Parameters:
  table_name: sys_choice
  query: name=item_option_new^element=type
  fields: value,label

# Result:
- 1: Yes/No
- 2: Multi Line Text
- 3: Multiple Choice
- 4: Numeric Scale
- 5: Select Box
- 6: Single Line Text
- 7: CheckBox
- 8: Reference
- 9: Date
- 10: Date/Time
- etc.

# Step 2: Understand variable definition structure
Tool: SN-Get-Table-Schema
Parameters:
  table_name: item_option_new

# Result:
- name (string): Variable name
- question_text (string): Label shown to user
- type (integer): Variable type from above
- reference (string): For type 8, target table
- cat_item (reference): Parent catalog item
- order (integer): Display sequence
- mandatory (boolean): Required field

例 4：カスタムアプリケーションのテーブルを調べる

# List custom tables in specific scope
Tool: SN-Query-Table
Parameters:
  table_name: sys_db_object
  query: nameSTARTSWITHx_myapp_
  fields: name,label,super_class

# Result:
- x_myapp_request (label: My App Request, extends: task)
- x_myapp_config (label: Configuration, extends: none)
- x_myapp_log (label: Activity Log, extends: none)

# Get schema for custom table
Tool: SN-Get-Table-Schema
Parameters:
  table_name: x_myapp_request

# Discover custom table relationships
Tool: SN-Discover-Table-Schema
Parameters:
  table_name: x_myapp_request
  include_relationships: true

関連スキル

• admin/update-set-management - 開発中の更新セットの管理
• admin/batch-operations - スキーマの知識を活用した複数レコードの作成
• development/business-rules - 検出したフィールドを使用するスクリプトの作成
• development/scripted-rest-apis - スキーマに基づくインテグレーションの構築

参考資料

• ServiceNow のテーブル管理
• ディクショナリエントリ
• フィールドタイプのリファレンス
• テーブル階層と継承