update-set-workflow

ServiceNow の更新セットワークフロー

ServiceNow の開発では、変更を追跡するために更新セットが必須です。更新セットがないと、変更は追跡されず、他のインスタンスにデプロイできません。

このルールはツールレイヤーでも適用されています。セッションで更新セットがアクティブでない場合、設定の書き込みはブロックされます。このブロックが発生したら、変更を名前付き更新セットに記録するかユーザーに確認してから、snow_ensure_active_update_set({ name }) を一度呼び出して再試行してください。ユーザーが追跡を明示的に拒否した場合に限り、__skipUpdateSet: true を指定して呼び出しを一度再実行してください。この選択はセッションの残りの期間、記憶されます。

開発を始める前に必ず行うこと

変更を加える前に、必ず更新セットを作成するか、アクティブな状態にしてください。

// Step 1: Check current Update Set
var current = await snow_update_set_query({ action: "current" })

// Step 2: If no Update Set or using Default, create one
if (!current || current.name === "Default") {
  await snow_update_set_manage({
    action: "create",
    name: "Feature: [Descriptive Name]",
    description: "What and why this change is being made",
  })
}

// Step 3: Now safe to make changes
// All changes will be tracked!

// Step 4: When done, complete the Update Set
await snow_update_set_manage({
  action: "complete",
  update_set_id: current.sys_id,
})

更新セットの命名規則

種類	形式	例
機能	Feature: [Name]	Feature: Incident Auto-Assignment
バグ修正	Fix: [Issue]	Fix: Approval Email Not Sending
機能強化	Enhancement: [Name]	Enhancement: Dashboard Performance
緊急修正	Hotfix: [Issue]	Hotfix: Critical Login Bug

更新セットのライフサイクル

1. 進行中 - アクティブで、変更を受け付けている状態
2. 完了 - エクスポート／昇格の準備ができた状態
3. 無視 - 変更が昇格されない状態（実験に使用）

追跡対象

更新セットでは、次の変更が自動的に取り込まれます。

• テーブルと列
• ビジネスルール
• スクリプトインクルード
• クライアントスクリプト
• UI ポリシーとアクション
• ワークフローと Flow Designer のフロー
• Service Portal のウィジェットとページ
• ACL とセキュリティルール
• システムプロパティ
• スケジュール済みジョブ
• その他多数…

追跡対象外

• データレコード（データにはインポートセットを使用）
• レコードの添付ファイル
• ユーザーセッション情報
• 一部のシステムテーブル（sys_user など）

更新セット用 MCP ツール

// Create new Update Set
snow_update_set_manage({
  action: "create",
  name: "Feature: My Feature",
  description: "Description of changes",
})

// Switch to existing Update Set
snow_update_set_manage({
  action: "switch",
  update_set_id: "sys_id_here",
})

// Get current Update Set
snow_update_set_query({ action: "current" })

// Complete Update Set
snow_update_set_manage({
  action: "complete",
  update_set_id: "sys_id_here",
})

// Export Update Set as XML
snow_update_set_manage({
  action: "export",
  update_set_id: "sys_id_here",
})

ベストプラクティス

1. 更新セットごとに機能は1つ - 関連のない変更を混在させないでください
2. わかりやすい名前を付ける - 更新セットの内容が明確に伝わる名前にしてください
3. 作業が終わったら完了にする - 更新セットを無期限に開いたままにしないでください
4. 完了前にテストする - すべての変更が正しく動作することを確認してください
5. Default は使用しない - 必ず名前付き更新セットを作成してください

OAuth コンテキストと更新セットの追跡

Serac は OAuth サービスアカウント認証を使用します。 すべての API 呼び出しは、UI のユーザーではなく OAuth サービスアカウントとして実行されます。更新セットは変更を加えるユーザーにとって「現在の」状態である必要があります。API による変更の場合、サービスアカウントにとって現在の更新セットが対象となります。

2つのコンテキスト

┌─────────────────────────────────────────────────────────────┐
│ YOUR UI SESSION (when you log in to ServiceNow UI)         │
│ User: john.doe                                              │
│ Current Update Set: [Whatever you selected in the UI]      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ SERAC OAUTH SESSION (API calls)                             │
│ User: oauth.service.account                                 │
│ Current Update Set: [Set via Update Set tools]             │
│ ← All Serac changes are tracked here                        │
└─────────────────────────────────────────────────────────────┘

auto_switch — 追跡に必須

• auto_switch=true（デフォルト） — 更新セットがサービスアカウントの現在の更新セットに設定され、すべての変更が追跡されます ✅
• auto_switch=false — 変更は追跡されません。クエリ／分析にのみ使用し、開発には絶対に使用しないでください。

要点

• ✅ 更新セットは作成されます — ServiceNow に存在します
• ✅ auto_switch=true の場合、変更は追跡されます — すべての Serac アーティファクトが更新セットに自動的に追加されます
• ❌ servicenow_username パラメーターを指定しない限り、UI セッションには表示されません（指定すると、その UI ユーザーにとっても現在の更新セットになります）
• ✅ デプロイは引き続き可能です — 更新セットは通常どおりエクスポート／インポートできます
• ⚠️ 開発タスクで auto_switch を無効にしないでください

servicenow_username を使用する場合

任意です。更新セットを UI セッションでも現在のものとして表示したい場合は、ServiceNow のユーザー名を渡してください。Serac と並行して ServiceNow UI で作業し、両方で同じ更新セットが選択されていることを確認したい場合に便利です。追跡には影響しません。追跡は auto_switch によって制御されます。