spoke-generation

Integration Hub スポークの生成

概要

このスキルでは、外部サービスに接続するための ServiceNow Integration Hub スポークの生成について説明します。

• 関連する統合アクションを整理するスポークコンテナーの作成
• REST、SOAP、スクリプトステップを使用したスポークアクションの構築
• 認証情報を安全に管理するための接続エイリアスの設定
• 適切なデータ型を使用したアクションの入力と出力の定義
• ServiceNow と外部形式間のデータ変換の実装
• 回復力のある統合を実現するためのエラー処理と再試行ロジックの追加
• インスタンス間のデプロイに向けたスポークのパッケージ化

使用する場面： 外部 API との再利用可能な統合を構築するとき、サードパーティサービス用のカスタムコネクターを作成するとき、またはデプロイ可能なスポークに統合ロジックをパッケージ化するとき。

前提条件

• ロール： integration_admin、flow_designer、または admin
• プラグイン： com.glide.hub.flow_designer（Flow Designer）、com.glide.hub.integration（Integration Hub）
• アクセス権： sys_spoke、sys_hub_action_type_definition、sys_connection_alias テーブル
• 知識： REST／SOAP API の基礎、JSON／XML データ形式、OAuth と基本認証
• 関連スキル： フローでスポークを使用する場合は genai/flow-generation

手順

ステップ 1：統合要件を分析する

統合のリクエストを解析し、以下を特定します。

• 外部サービス： 接続するシステムまたは API（Slack、Jira、Salesforce、カスタム REST）
• 操作： スポークでサポートするアクション（作成、読み取り、更新、削除、クエリ）
• 認証： 認証方法（OAuth 2.0、Basic Auth、API Key、相互 TLS）
• データ形式： リクエスト／レスポンスの形式（JSON、XML、フォームエンコード）
• エラー処理： 想定されるエラーコードと再試行動作

ステップ 2：既存のスポークを照会してパターンを確認する

MCP アプローチ：

Use SN-Query-Table on sys_spoke:
  - query: active=true
  - fields: sys_id,name,description,scope,logo,active
  - limit: 20

既存のスポークアクションを照会します。

Use SN-Query-Table on sys_hub_action_type_definition:
  - query: spoke=<spoke_sys_id>^active=true
  - fields: sys_id,name,description,action_type,inputs,outputs
  - limit: 20

REST アプローチ：

GET /api/now/table/sys_spoke
  ?sysparm_query=active=true
  &sysparm_fields=sys_id,name,description,scope,active
  &sysparm_limit=20

ステップ 3：スポークレコードを作成する

MCP アプローチ：

Use SN-Create-Record on sys_spoke:
  - name: "Acme CRM Spoke"
  - description: "Integration spoke for Acme CRM REST API - supports contacts, deals, and activities"
  - scope: "x_acme_crm"
  - logo: ""
  - active: true
  - version: "1.0.0"

REST アプローチ：

POST /api/now/table/sys_spoke
Body: {
  "name": "Acme CRM Spoke",
  "description": "Integration spoke for Acme CRM REST API - supports contacts, deals, and activities",
  "scope": "x_acme_crm",
  "active": true,
  "version": "1.0.0"
}

ステップ 4：接続エイリアスを作成する

接続エイリアスを使用すると、認証情報を安全に再利用可能な形で保存できます。

接続エイリアスの種類：

種類	値	用途
HTTP 接続	http_connection	REST／SOAP API の認証情報
JDBC 接続	jdbc_connection	データベース接続
LDAP 接続	ldap_connection	ディレクトリーサービス
カスタム	custom	標準以外の認証

MCP アプローチ：

Use SN-Create-Record on sys_connection_alias:
  - name: "Acme CRM API"
  - connection_type: "http_connection"
  - description: "Connection alias for Acme CRM REST API"
  - active: true
  - scope: "x_acme_crm"
  - spoke: "<spoke_sys_id>"

REST アプローチ：

POST /api/now/table/sys_connection_alias
Body: {
  "name": "Acme CRM API",
  "connection_type": "http_connection",
  "description": "Connection alias for Acme CRM REST API",
  "active": true,
  "scope": "x_acme_crm",
  "spoke": "<spoke_sys_id>"
}

認証情報の設定（Basic Auth）：

Use SN-Create-Record on sys_alias_credential:
  - connection_alias: "<connection_alias_sys_id>"
  - type: "basic_auth"
  - user_name: "${connection.username}"
  - password: "${connection.password}"
  - active: true

認証情報の設定（OAuth 2.0）：

Use SN-Create-Record on sys_alias_credential:
  - connection_alias: "<connection_alias_sys_id>"
  - type: "oauth2"
  - oauth_profile: "<oauth_profile_sys_id>"
  - active: true

ステップ 5：スポークアクションを作成する

各アクションは、スポークが実行できる操作を表します。

MCP アプローチ：

Use SN-Create-Record on sys_hub_action_type_definition:
  - name: "Create Contact"
  - description: "Creates a new contact in Acme CRM"
  - spoke: "<spoke_sys_id>"
  - action_type: "custom"
  - category: "x_acme_crm"
  - access: "public"
  - active: true
  - annotation: "Creates a contact record in external CRM system"

Use SN-Create-Record on sys_hub_action_type_definition:
  - name: "Get Contact"
  - description: "Retrieves a contact by ID from Acme CRM"
  - spoke: "<spoke_sys_id>"
  - action_type: "custom"
  - category: "x_acme_crm"
  - access: "public"
  - active: true

Use SN-Create-Record on sys_hub_action_type_definition:
  - name: "Search Contacts"
  - description: "Searches contacts in Acme CRM by criteria"
  - spoke: "<spoke_sys_id>"
  - action_type: "custom"
  - category: "x_acme_crm"
  - access: "public"
  - active: true

REST アプローチ：

POST /api/now/table/sys_hub_action_type_definition
Body: {
  "name": "Create Contact",
  "description": "Creates a new contact in Acme CRM",
  "spoke": "<spoke_sys_id>",
  "action_type": "custom",
  "category": "x_acme_crm",
  "access": "public",
  "active": true
}

ステップ 6：アクションの入力を定義する

MCP アプローチ：

Use SN-Create-Record on sys_hub_action_input:
  - action_type: "<create_contact_action_sys_id>"
  - name: "first_name"
  - label: "First Name"
  - type: "string"
  - mandatory: true
  - order: 100

Use SN-Create-Record on sys_hub_action_input:
  - action_type: "<create_contact_action_sys_id>"
  - name: "last_name"
  - label: "Last Name"
  - type: "string"
  - mandatory: true
  - order: 200

Use SN-Create-Record on sys_hub_action_input:
  - action_type: "<create_contact_action_sys_id>"
  - name: "email"
  - label: "Email Address"
  - type: "string"
  - mandatory: true
  - order: 300

Use SN-Create-Record on sys_hub_action_input:
  - action_type: "<create_contact_action_sys_id>"
  - name: "company_id"
  - label: "Company ID"
  - type: "string"
  - mandatory: false
  - order: 400

REST アプローチ：

POST /api/now/table/sys_hub_action_input
Body: {
  "action_type": "<create_contact_action_sys_id>",
  "name": "email",
  "label": "Email Address",
  "type": "string",
  "mandatory": true,
  "order": 300
}

ステップ 7：アクションに REST ステップを追加する

REST ステップでは、外部サービスへの実際の HTTP 呼び出しを定義します。

MCP アプローチ：

Use SN-Create-Record on sys_hub_rest_step:
  - action_type: "<create_contact_action_sys_id>"
  - name: "Call Create Contact API"
  - order: 100
  - connection_alias: "<connection_alias_sys_id>"
  - http_method: "POST"
  - resource_path: "/api/v2/contacts"
  - content_type: "application/json"
  - request_body: '{
      "first_name": "${inputs.first_name}",
      "last_name": "${inputs.last_name}",
      "email": "${inputs.email}",
      "company_id": "${inputs.company_id}"
    }'
  - headers: '[{"name":"Accept","value":"application/json"}]'

REST アプローチ：

POST /api/now/table/sys_hub_rest_step
Body: {
  "action_type": "<create_contact_action_sys_id>",
  "name": "Call Create Contact API",
  "order": 100,
  "connection_alias": "<connection_alias_sys_id>",
  "http_method": "POST",
  "resource_path": "/api/v2/contacts",
  "content_type": "application/json",
  "request_body": "{\"first_name\":\"${inputs.first_name}\",\"last_name\":\"${inputs.last_name}\",\"email\":\"${inputs.email}\"}"
}

GET リクエストの例：

Use SN-Create-Record on sys_hub_rest_step:
  - action_type: "<get_contact_action_sys_id>"
  - name: "Call Get Contact API"
  - order: 100
  - connection_alias: "<connection_alias_sys_id>"
  - http_method: "GET"
  - resource_path: "/api/v2/contacts/${inputs.contact_id}"
  - content_type: "application/json"
  - headers: '[{"name":"Accept","value":"application/json"}]'

ステップ 8：アクションの出力を定義する

MCP アプローチ：

Use SN-Create-Record on sys_hub_action_output:
  - action_type: "<create_contact_action_sys_id>"
  - name: "contact_id"
  - label: "Contact ID"
  - type: "string"
  - order: 100

Use SN-Create-Record on sys_hub_action_output:
  - action_type: "<create_contact_action_sys_id>"
  - name: "status_code"
  - label: "HTTP Status Code"
  - type: "integer"
  - order: 200

Use SN-Create-Record on sys_hub_action_output:
  - action_type: "<create_contact_action_sys_id>"
  - name: "response_body"
  - label: "Response Body"
  - type: "string"
  - order: 300

ステップ 9：スクリプトステップでエラー処理を追加する

MCP アプローチ：

Use SN-Create-Record on sys_hub_script_step:
  - action_type: "<create_contact_action_sys_id>"
  - name: "Handle Response"
  - order: 200
  - script: |
      (function execute(inputs, outputs) {
        var statusCode = inputs.rest_step_status_code;
        var responseBody = inputs.rest_step_response_body;

        if (statusCode == 201) {
          var response = JSON.parse(responseBody);
          outputs.contact_id = response.id;
          outputs.status_code = statusCode;
        } else if (statusCode == 409) {
          throw new Error('Contact already exists: ' + responseBody);
        } else if (statusCode == 429) {
          throw new Error('Rate limit exceeded. Retry after cooldown.');
        } else {
          throw new Error('API error ' + statusCode + ': ' + responseBody);
        }
      })(inputs, outputs);

ステップ 10：スポークをテストして公開する

MCP アプローチ：

Use SN-Update-Record on sys_spoke:
  - sys_id: "<spoke_sys_id>"
  - active: true

すべてのアクションが適切に設定されていることを確認します。

Use SN-Query-Table on sys_hub_action_type_definition:
  - query: spoke=<spoke_sys_id>
  - fields: sys_id,name,active,action_type
  - limit: 50

接続エイリアスが利用可能であることを確認します。

Use SN-Query-Table on sys_connection_alias:
  - query: spoke=<spoke_sys_id>
  - fields: sys_id,name,connection_type,active

ツールの使用

ツール	目的	使用する場面
SN-Query-Table	既存のスポークとアクションを検索する	パターンの発見と検証
SN-Create-Record	スポーク、アクション、入力、出力、ステップを作成する	スポークコンポーネントの構築
SN-Update-Record	スポーク設定の変更、スポークの有効化	編集と公開
SN-Get-Table-Schema	スポークテーブルのフィールドを確認する	利用可能な設定の把握

ベストプラクティス

1. 外部サービスごとに1つのスポークを作成する -- 複数の API を1つのスポークに混在させないでください
2. すべての認証情報に接続エイリアスを使用する -- スクリプトや REST ステップにシークレットをハードコードしないでください
3. 包括的な入力／出力を定義する -- 明確なラベルと適切なデータ型を設定してください
4. 必ずエラー処理を追加する -- HTTP ステータスコードを解析し、わかりやすいエラーメッセージを提示してください
5. 一時的な障害（429、503）に対する再試行ロジックを実装する -- スクリプトステップを使用してください
6. 大規模な結果セットに対応するため、検索／一覧表示アクションにはページネーションを使用する
7. API の進化に対応できるよう、resource_path で API パスにバージョンを指定する
8. デバッグ用に、適切な詳細レベルでインテグレーションの呼び出しをログに記録する
9. 本番の外部サービスに接続する前に、モックデータでテストする
10. スポークの説明にレート制限とスロットリングの動作を記載する

トラブルシューティング

問題	原因	解決方法
接続テストに失敗する	接続エイリアスの認証情報または URL が無効	接続エイリアスの設定を確認し、接続をテストしてください
401 Unauthorized	OAuth トークンの有効期限切れ、または認証情報が無効	OAuth トークンを更新するか、認証情報レコードを更新してください
403 Forbidden	API キーに必要な権限がない	インテグレーションユーザーに対する外部サービスの権限を確認してください
REST ステップがタイムアウトする	外部サービスの応答が遅い、または接続できない	REST ステップのタイムアウト時間を延長するか、ネットワーク接続を確認してください
応答の解析エラー	API から予期しない形式の応答が返された	スクリプトステップに try/catch を使った防御的な JSON 解析を追加してください
Flow Designer にアクションが表示されない	アクションのアクセス権がプライベートに設定されている、またはスポークが非アクティブ	アクセス権を「public」に設定し、スポークがアクティブであることを確認してください
入力データが切り詰められる	文字列フィールドの長さ制限	大きなペイロードには複数行テキスト型を使用してください

例

例 1：Slack 通知スポーク

Slack メッセージを送信するスポークを生成します：

• アクション 1： メッセージを送信 -- channel、text、attachments を指定して /api/chat.postMessage に POST
• アクション 2： チャンネルを作成 -- name、is_private を指定して /api/conversations.create に POST
• アクション 3： ファイルをアップロード -- channels、file content を指定して /api/files.upload に POST
• 接続： Slack Bot Token を使用した OAuth 2.0
• エラー処理： レート制限（429）、チャンネルが見つからない場合（channel_not_found）を処理

例 2：Jira インテグレーションスポーク

Jira Cloud の操作を行うスポークを生成します：

• アクション 1： 課題を作成 -- project、summary、description、issuetype を指定して /rest/api/3/issue に POST
• アクション 2： 課題を取得 -- /rest/api/3/issue/{issueKey} に GET し、status、assignee、priority を返す
• アクション 3： コメントを追加 -- body を指定して /rest/api/3/issue/{issueKey}/comment に POST
• アクション 4： 課題をトランジション -- /rest/api/3/issue/{issueKey}/transitions に POST
• 接続： API トークンを使用した Basic Auth。ベース URL はインスタンスごとに設定可能

例 3：カスタム REST API スポーク

カスタムの内部マイクロサービス用スポークを生成します：

• アクション 1： 注文を送信 -- line items、customer、shipping address を指定して /api/v1/orders に POST
• アクション 2： 注文状況を確認 -- /api/v1/orders/{orderId} に GET し、status、tracking number を返す
• アクション 3： 注文をキャンセル -- reason を指定して /api/v1/orders/{orderId} に DELETE
• 接続： カスタムヘッダーを使用した API キー認証
• データ変換： ServiceNow カタログ変数を API リクエスト形式にマッピング

関連スキル

• genai/flow-generation - スポークアクションを使用する Flow Designer フロー
• genai/playbook-generation - スポークアクションをアクティビティとして呼び出すプレイブック
• catalog/approval-workflows - 外部通知をトリガーする場合がある承認フロー
• admin/instance-management - 接続エイリアスと認証情報の設定