他のアプリケーションのためのWebhookのトリガー

ALM Octaneは、webhookによる他のアプリケーションとの統合をサポートしています。Trigger Webhookアクションを使用してルールを作成することにより、Webhookを設定します。このトピックでは、Webhookを設定するためのエンドツーエンドの手順を説明します。

概要

WebHookメカニズムは、高度なワークフローユースシナリオに対応しており、他のアプリケーションとの統合が可能になります。

Webhookのトリガールールでは、エンティティの作成、削除、更新など、ALM Octaneでイベントが発生した場合に、JSON形式のペイロードを含むHTTP/S要求をエンドポイントURLに送信します。

このエンドポイントURLで、アプリケーションは要求を受け取って情報を処理します。

プロキシの設定

必要に応じて、サイト管理者に依頼して、外部への要求がブロックされないように組織のプロキシを設定します。

プロキシを設定するには、proxy.confファイルを変更して、ALM Octaneサーバーを再起動します。詳細については、サイト設定の変更を参照してください。

トップに戻る

Webhookのトリガールールのカスタマイズ

管理者は、設定パラメーターを使用して、ALM OctaneでのエンドポイントURLへのアクセス方法をカスタマイズできます。

次の設定をカスタマイズできます。

  • ALM Octaneで外部に要求を送信するのに、HTTPまたはHTTPSのどちらを使用するか (WEBHOOK_ALLOW_HTTP)。

    HTTPを使用する場合、要求の送信には標準ポート80のみを使用します。

  • HTTP/S要求がタイムアウトするタイミング (WEBHOOK_REQUEST_TIMEOUT)。

詳細については、設定パラメーターを参照してください。

トップに戻る

資格情報のセットアップ

必要に応じて、管理者に依頼して、要求の認証に使用する資格情報を定義します。

Webhookのトリガールールは基本認証をサポートしています。Webhookのトリガールールで資格情報を設定した場合、Webhook要求に基本認証ヘッダーが含められます。

詳細については、資格情報のセットアップを参照してください。

トップに戻る

必要に応じて、WebSocket (オンプレミス) を使用して通信します

ALM OctaneサーバーがエンドポイントURLにアクセスできない場合は、この通信を有効にするようにWebSocketを設定します。

WebSocketを使用すると、サーバーとクライアントは、接続が確立された後、明示的な要求なしにいつでも相互にメッセージを送信できます。

WebSocketを使用して通信するには:

  1. WebSocketクライアントを使用して、ALM OctaneとエンドポイントURLの間にトンネルを開くWebSocketを作成します。詳細については、https://www.websocket.org/を参照してください。

  2. APIアクセスキーを使用してALM Octaneにログインする機能をWebSocketに提供します。

    1. CI/CD統合のロールを持つAPIキーを生成します。詳細については、APIアクセスのセットアップをご覧ください。

    2. このAPIキーを、WebSocket接続を使用するワークスペースに割り当てます。

    この目的のために専用のAPIキーを使用することをお勧めします。

  3. WebSocket構成に次の詳細を入力します。

    ws://<ALM Octane host>:<ALM Octane port>/messaging/shared_spaces/<shared_space>/workspaces

  4. Webhookのトリガールールアクションを作成するときは、WebSocket通信方法を選択します。

WebSocketは、指定された共有スペースでCI/CD統合のロールを持つワークスペースの変更をリッスンし、作成したWebhookアクションをトリガーします。

トップに戻る

Webhook要求ペイロード形式について

Webhookのトリガーアクションを含むルールを処理する場合、ALM OctaneはエンドポイントURLに対してHTTP/S POST要求を実行します。このPOSTには、JSON要求ペイロードが含められます。

ヒント: alm-octane-webhooks-listenerツールを使用して、Webサービスをシミュレートし、リクエストペイロードの構造を確認します。詳しくは、ALM Octane webhookのリッスンとこのビデオをリッスン参照してださい。 

Webhookのトリガーアクションをトリガーしたイベントに応じて、異なるペイロードが送信されます。

イベント 要求ペイロード
エンティティの作成 標準設定では、Webhookのトリガーアクションに、IDやタイプなどの基本的なフィールドのみが含められます。
エンティティの削除 標準設定では、Webhookのトリガーアクションに、IDやタイプなどの基本的なフィールドのみが含められます。
エンティティの更新 標準設定では、Webhookのトリガーアクションに、IDやタイプなどの基本的なフィールドに加えて、変更の「前後」の内容のセットが含められます。

Webhookのトリガールールを作成する際に、[フィールド] を指定して、要求ペイロードに含める追加フィールドを選択できます。

UDFはフィールドでサポートされています。

ペイロード形式の例

ペイロードのパーツ

更新イベントのペイロードは、次のパーツで構成されています。 

パーツ 説明
ヘッダー情報

すべてのWebhookのトリガールールで送信され、以下で構成されます。

  • server_url
  • event_type
  • username
  • sharedspace_id
  • workspace_id
基本情報

すべてのWebhookのトリガールールで送信されるフィールド。これらのフィールドには、以下が含まれます。

  • id
  • type
追加情報 Webhookのトリガールールをセットアップする際に、[フィールド] を使用して要求ペイロードに追加できる追加フィールド。
変更点

event_typeがupdateの場合、要求ペイロードにはchangesフィールドが含められます。

changesフィールドには、更新前後の値を含む、変更点のセットが含まれます。
フィールドタイプ スニペット例
プリミティブ

id、type、last_modifiedなどの基本的なシステムフィールド。

"changes": {
  "last_modified": {
    "oldValue": "2017-12-26T15:51:22Z",
    "newValue": "2017-12-26T15:49:22Z"
  }
}
ユーザー

ユーザー情報。

"detected_by": {
  "id": 1991,
  "type": "workspace_user",
  "email": "MyEmail@MyCompany.com"
}

"changes": {
  "detected_by": {
    "oldValue": null,
    "newValue": {
      "id": 1002,
      "type": "workspace_user",
      "email": "YourEmail@YourCompany.com"
    }
  }
}
リストノード

タイプとIDからなるオブジェクト (フェーズなど)。

"phase": {
  "type": "phase",
  "id": "phase.defect.new"
}

"changes": {
  "phase": {
    "oldValue": {
      "type": "phase",
      "id": "phase.test_manual.new"
    },
    "newValue": {
      "type": "phase",
      "id": "phase.test_manual.planned"
    }
  }
}
複数リストノード

合計カウントとリストノードの配列 (テストタイプのリストなど)。

"test_type": {
  "total_count": 2,
  "data": [
    {
      "type": "list_node",
      "id": "list_node.test_type.performance"
    },
    {
      "type": "list_node",
      "id": "list_node.test_type.regression"
    }
  ]
}

"changes": {
  "test_type": {
    "oldValue": [
      {
        "type": "list_node",
        "id": "list_node.test_type.performance"
      },
      {
        "type": "list_node",
        "id": "list_node.test_type.regression"
      }
    ],
    "newValue": [
      {
        "type": "list_node",
        "id": "list_node.test_type.performance"
      }
    ]
  }
}
参照

タイプとIDからなるオブジェクト (リリースなど)。

"release": {
  "type": "release",
  "id": "2002"
}
複数参照

合計カウントと参照エンティティの配列 (アプリケーションモジュール (従来のプロダクト領域) など)。

"application_modules": {
  "total_count": 2,
  "data": [
    {
      "type": "application_module",
      "id": "2002"
    },
    {
      "type": "application_module",
      "id": "2001"
    }
  ]
}

"changes": {
 "application_modules": {
    "oldValue": [
      {
        "id": 1001,
        "type": "application_module"
      }
    ],
    "newValue": [
      {
        "id": 1002
        "type": "application_module",
      }
    ]
  }
}

トップに戻る

エンドポイントでのWebサービスのセットアップ

要求を受け取って情報を処理するエンドポイントで、サービスをセットアップして実行します。

Webサービスの開発とテストには、PostmanやTelerik FiddlerなどのHTTPクライアントツールを使用することをお勧めします。

Webサービスを設定するときは、次のガイドラインに従って、Webhookがトリガーされるようにしてください。

  • サービスでHTTP/S応答をすみやかに送信し、ALM Octaneが遅延を失敗と誤って解釈して再試行を繰り返すことがないようにする必要があります。

  • Webサービスで必ず有効なHTTP/S応答を返し、ALM Octaneが応答をwebhookの失敗と誤って解釈しないようにする必要があります。

潜在的な悪用を回避するために、ALM Octaneは、上記のガイドラインに従わない場合にURLをブロックする保護メカニズムを提供します。

ヒント: alm-octane-webhooks-listenerツールを使用して、Webサービスをシミュレートします。詳細については、ALM Octaneのwebhooksを聞く参照。

トップに戻る

ALM Octaneで作業すると、Webhookがトリガーされます

上記の項目と設定を構成した後、ALM Octaneでの作業により、ALM Octane設定で作成したWebhookルールがトリガーされます。

トップに戻る

参照情報: