外部アクションの追加

外部のWebサイトまたはアプリケーションを起動するALM Octaneツールバーにカスタムアクションを追加できます。外部のウェブサイトまたはアプリケーションは、ALM Octane起動エンティティから情報を読み取り、コマンドをALM Octaneに送り返すことができます。

注: 外部アクションは、テクニカルプレビューとして利用できます。

概要

ALM Octaneで指定されたエンティティのツールバーに追加されるカスタムアクションを設定できます。ボタンは、指定したエンティティのグリッドビューまたは詳細ビューのいずれかに追加できます。

例:

この場合、ツールチップ一般的な詳細を使用したカスタムアクションを不具合グリッドツールバーに追加しました。クリックすると、アクションはグリッドで選択された不具合を一覧表示する外部Webサイトを開きます。

カスタムアクションを追加するには、共有スペース管理者権限が必要です。

トップに戻る

カスタムアクションの追加

外部アクションエディターでJSONファイルを構成することにより、カスタムアクションを追加します。

カスタムアクションを追加するには:

  1. 共有スペース管理者としてALM Octaneにログインします。

  2. メインのALM Octaneユーザーエリアから、設定 > 管理 > 外部アクションエディターを選択します。

    エディターを使用すると、ALM Octaneに追加するカスタムボタンを表すJSONコードを記述または貼り付けることができます。

  3. デモの読み込みをクリックして、カスタムアクションのさまざまな構成オプションの例を含むJSONコードを読み込みます。

JSONファイルには、1つ以上のカスタムアクションのコードを含めることができます。

トップに戻る

JSON構造

以下は、単一のカスタムアクションのコードサンプルです。プロパティについて以下に説明します。

[
	{
		"name": "defect-details",
		"title": "Defect Details",
		"entity_type": ["defect"],
		"views": ["list", "details"],
		"icon": "rss",
		"url": "https://server.domain.com/some-application?entity_ids={entity_ids}&entity_type={entity_type}&shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&action=defect-details",
		"single_entity": true,
		"events": false,
		"dialog": "large"
	}
]

カスタムボタンのプロパティ

プロパティ 説明
name ログおよびエラーでアクションを識別するために使用される一意のアクション名。
title

アイコンとラベルが表示されているツールバーの場合、この値がボタンラベルとして使用されます。

アイコンのみが表示されるツールバーの場合、この値はボタンのツールチップとして使用されます。
entity_type

ボタンが適用されるエンティティタイプのリスト。

エンティティタイプ名はREST APIと同じです。例: 不具合、テスト、リリース

work_itemなどの集約型も使用できます。ボタンは、集約されたタイプのすべてのサブタイプに適用されます。例: タイプwork_itemを定義して、ボタンをユーザーストーリー、不具合に適用します。
views

このアクションが表示されるビュータイプのリスト。

許可される値: リスト、詳細
icon このボタンに表示されるアイコン。可能なアイコンのリストを参照してください。
single_entity

trueに設定すると、グリッドで1つの項目が選択された場合にのみボタンが有効になり、複数の項目が選択された場合にボタンが無効になります。

falseに設定して、単一または複数の項目が選択されたときにボタンが有効になるようにします。
dialog

標準設定では、参照されているWebサイトまたはアプリケーションが新しいタブで開きます。

新しいタブではなく、ALM Octaneダイアログボックス内にアプリケーションを埋め込むには、ダイアログプロパティを定義します。

許容値: 小、中、大

注意: アクションを埋め込むと、埋め込まれたアプリケーションが適切に保護されていない場合、ALM Octaneユーザーにセキュリティリスクが生じる可能性があります。

ダイアログが定義されている場合、urlプロパティ (以下を参照) には、ダイアログボックス内で開くiframeのソースが含まれている必要があります。

組み込みアプリケーションは、「メッセージ」を介して、ダイアログボックスを制御するイベントをトリガーできます。メッセージによって処理されるワークスペース、shared_spaceとdialog_idの値に提供されたものと同一である場合にのみ、ALMOctane組み込みアプリケーション。その他の値を指定すると、メッセージは無視されます。

メッセージの例については、埋め込みアプリケーションのコード例を参照してください。
url

ユーザーがボタンをクリックしたときにアクティブ化されるURLまたはURI。

urlは次のいずれかになります。

  • https: またはhttp: プロトコルのいずれかを使用するWebサイト

  • mailto: などのプロトコルハンドラURI、またはユーザーのマシンにプロトコルハンドラが登録されているカスタムアプリケーション。

    標準設定では、URIはhttpsやmailtoなどの一般的なWebベースのプロトコルに制限されています。追加のプロトコルを許可するには、ENTITY_EXTERNAL_ACTIONS_SUPPORTED_PROTOCOLSサイトパラメーターを更新します。詳細については、設定パラメーターを参照してください。

URLトークン

ターゲットアプリケーションのURLまたはURIに加えて、トークンを含めることもできます。トークンは、選択したエンティティに関する情報を表します。トークンは、実行時にALM Octaneによって実際の値に置き換えられ、ターゲットアプリケーションに転送されます。

次の例には、urlプロパティに含めることができるすべてのトークンが含まれています。

https://server.domain.com/some-application?entity_ids={entity_ids}&foo_bar={entity.foo_udf}&entity_type={entity_type}&shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&action=defect-details

サポートされているトークンの一部またはすべてをURLに含めることができます。呼び出されたアプリケーションに必要なトークンのみを含めるのが最善です。

さらに、URLに他のクエリパラメーターを追加して、ターゲットアプリケーションに追加情報を送信できます。上記の例では、クエリパラメーターとしてaction=defect-detailsを追加しました。これにより、ターゲットアプリケーションはアクティブ化されたカスタムアクションを認識できます。

サポートされているトークン:

  • {entity_ids}. ユーザーが選択したエンティティのIDのカンマ区切りリスト。

  • {entity.foo_field}. ここで、foo_fieldは、String型またはNumber型のエンティティのフィールド (UDFを含む) のいずれかです。

    ボタンのURLにフィールドを含めることにより、外部システムの特定の項目に移動できます。たとえば、外部システムからのチケットのIDをUDFに保存する場合、外部アクションを使用して、そのチケットシステムへのURLを作成し、URLにチケットIDを含めることができます。

    または、エンティティをALMからALM Octaneに同期し、ALM IDがUDFに保存されている場合、URLでALM TD://プロトコルを使用して項目をALMで直接開く外部アクションを作成できます。

    フィールドを含むカスタムボタンは、単一のエンティティでのみ機能します。

  • {entity_type}. 選択したエンティティの集約タイプ。たとえば、不具合、これはwork_itemに置き換えられます。
  • {shared_space}. アクションがトリガーされたスペースのID。
  • {workspace}. アクションがトリガーされたワークスペースのID。
  • {user_login}. ユーザーがALM Octaneに接続したときに使用したログイン名。
  • {user_emailALM Octaneに記録されているユーザーのメールアドレス。
  • {dialog_id}. オプション。ダイアログボックスに埋め込まれたアクションの場合、この値は、アクションからのメッセージをALM Octaneにポストバックするために必要です。詳細については、組み込みアプリケーションのコード例を参照してください。

  • {octane_url}. 外部アクションが呼び出されるALM OctaneサイトのURL。
イベント

オプション。アクションがターゲットWebアプリケーションからのイベントの受信をサポートするかどうかを示します。

許可される値: true / false

標準設定: falseこの機能は、潜在的なセキュリティリスクをもたらします。

注: Internet Explorerではサポートされていません。

サポートされているイベント:

  • octane_refresh_entity. ALM Octaneに、指定されたエンティティが外部アプリケーションで更新された後に更新するように指示します。
  • octane_display_entity. ALM Octaneに、指定されたエンティティの詳細を表示するように指示します。
  • octane_entity_was_added. ALM Octaneに新しいエンティティが作成されたことを通知します。

実装上の注意とコード例については、以下を参照してください。外部アプリケーションからALM Octaneイベントをトリガー
ワークスペース

オプション。存在する場合、アクションが適用されるワークスペースを指定します。

構文: ワークスペースIDの番号配列。例:  "workspaces": [1002, 1004]

注: ワークスペースは、exclude_workspacesが指定されていない場合にのみ指定できます。
exclude_workspaces

オプション。存在する場合、アクションが適用されないワークスペースを指定します。

構文: ワークスペースIDの番号配列。例: "exclude_workspaces": [1002, 1004]

注: exclude_workspacesは、ワークスペースが指定されていない場合にのみ指定できます。

トップに戻る

組み込みアプリケーションのコード例

次の例では、paramsが、urlパラメーターを介して外部アプリケーションに送信されたパラメーターを保持していることを前提としています。

例1。ダイアログボックスのタイトルを設定する

var message = {
	event_name: 'octane_set_dialog_title',
	shared_space: '1004',
	workspace: '1006',
	data: {
		dialog_id: params.dialog_id,
		title: 'Our custom dialog title',
	},
};
window.parent.postMessage(message, '*');

例2。ダイアログボックスを閉じる

var message = {
	event_name: 'octane_close_dialog',
	shared_space: '1004',
	workspace: '1006',
	data: {
		dialog_id: params.dialog_id,
		refresh: true,
	},
};
window.parent.postMessage(message, '*');

メッセージでrefresh: trueを設定して、表示されたビューを更新するようにALM Octaneに指示します。これにより、アクションがトリガーされたビューに応じて、グリッドビューまたは詳細ビューのいずれかが更新される可能性があります。

埋め込みアクションに関連する上記のイベントに加えて、外部アプリケーションから他のイベントをトリガーできます。詳しくは、外部アプリケーションからトリガーALMOctaneを参照。

トップに戻る

外部アプリからALM Octaneイベントをトリガーする

以下は、ALM OctaneでイベントをトリガーするJavaScriptコードサンプルです。コードは、ターゲットWebアプリケーションに実装する必要があります。

var message = {
	event_name: 'octane_refresh_entity',
	shared_space: '1004',
	workspace: '1006',
	data: {
		entity_type: 'work_item',
		entity_ids: ['1003', '4005'],
	},
};
window.opener.postMessage(message、 '*');

実装上の注意

  • 新しいブラウザタブで開いたアクションの場合、メッセージはwindow.openerを使用して投稿する必要があります。
  • ALM Octaneダイアログボックス内に埋め込まれたアクションの場合、メッセージはwindow.parentを使用して投稿する必要があります。
  • 「openerundefined」でコードが失敗した場合は、アクションが「events」: trueで設定されていることを確認してください。
  • ユーザーが現在編集中で、サーバーに変更が保存されていないエンティティに対して更新イベントまたはメッセージが送信された場合、データの損失を防ぐためにUIは更新されません。

サポートされているイベントのコード例

ALM Octaneに、指定されたエンティティが外部アプリケーションで更新された後に更新するように指示します。

{
	event_name: 'octane_refresh_entity',
	shared_space: '1004',
	workspace: '1006',
	data: {
		entity_type: 'work_item',
		entity_ids: ['1003', '4005'],
	},
}

ALM Octaneに、指定されたエンティティの詳細を表示するように指示します。

{
	event_name: 'octane_display_entity',
	shared_space: '1004',
	workspace: '1006',
	data: {
		entity_type: 'work_item',
		entity_id: '1050',
	},
}

新しいエンティティが作成されたことをALM Octaneに通知します。ALM Octaneは、ALM Octane自体の内部に新しいエンティティが作成されたときと同じように応答します。

たとえば、新しい不具合を追加するときに、不具合グリッドが現在表示されている場合、グリッドが更新されると、グリッドの上部に新しい不具合が表示されます。

{
	event_name: 'octane_entity_was_added',
	shared_space: '1004',
	workspace: '1006',
	data: {
		entity_type: 'defect',
		entity_id: '1050',
	},
}

トップに戻る

アイコン

以下のリストからアイコンを選択して、カスタムボタンとして使用します。

ヒント: 詳細を表示するには、クリックしてズームインし、画像を右クリックして新しいタブで開きます。

トップに戻る

外部アクションにCORSを使用する

外部アクションがALM Octane以外のドメインでホストされている場合は、コードでAPIキーを使用するか、CORSメカニズムを使用して信頼を確立できます。

このセクションでは、外部アクションにCORSメカニズムを使用する方法について説明します。

外部ALM OctaneアクションのCORSメカニズムには、以下が含まれます。

  • CORS設定パラメーターを設定する。
  • リクエストでアンチCSRFCookieを送信する。

CORSアクションを有効にするには:

  1. 次のCORSパラメーターが有効になっていて設定されていることを確認してください。CORS_ENABLED、CORS_ALLOW_ORIGIN、CORS_MAX_AGE

  2. 次のサイトパラメーターを設定します。

    パラメーター 値
    SAME_SITE_COOKIE_ATTRIBUTE なし

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

リクエストでXSRF Cookieを送信するには:

承認されていないサーバーがALM Octaneサーバーにアクセスできないようにするには、外部サーバーからのリクエストに、一意のCookieを送信するXSRFヘッダーを含める必要があります。

以下は、XSRFヘッダーのサンプルコードスニペットです。

let cookies = decodeURIComponent(document.cookie);
let xsrf = cookies
  .split(";")
  .map((s) => s.trim())
  .find((c) => c.startsWith("XSRF_COOKIE="))
  .split("=")[1];
await fetch(url, {
  headers: {
    "XSRF-HEADER": xsrf,
    "content-type": "application/json",
  },
  method: "PUT",
  ...
});

トップに戻る

ALM Octaneで外部アクションをホスト

外部サーバ上の外部アクションのコードを格納し、ALM Octaneとの信頼関係を確立する代わりに、あなたはALM Octaneに外部アクションコードをアップロードすることができます。

複数の外部アクションをアップロードでき、すべて同じバンドルに圧縮されています。さまざまな外部アクションで共有コードを使用することもできます。たとえば、共有コードcommonを参照する外部アクションfooとbarがある場合は、次のようにフォルダを構成します。

前提条件

  • パラメーターSUPPORT_EXTERNAL_ENTITY_ACTIONS_BUNDLEが有効になっていることを確認してください。
  • 必要に応じて、他の外部アクションパラメーターを設定します。EXTERNAL_ENTITY_ACTIONS_BUNDLE_MAX_SIZE、EXTERNAL_ENTITY_ACTIONS_FILE_EXTENSION_WHITE_LIST

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

外部アクションをALM Octaneにアップロードするには:

  1. コードファイルを圧縮します。
  2. [設定] メニューで、外部アクションエディターを選択します。
  3. アクションのアップロードをクリックして、zipファイルを選択します。

  4. 外部アクションエディターで、外部アクションURLがOctaneサーバーを指すようにします。例:

    "url": "{octane_url}/api/shared_spaces/{shared_space}/external-entity-actions/bundle/foo/foo.html

    • fooは、アプリケーションファイルをホストするフォルダーの名前です。
    • foo.htmlはバンドル内のファイルであり、アプリケーションへのエントリポイントです。

トップに戻る

外部アクション用のREST API

次の例は、外部アクションを読み取って更新するためのGETスクリプトとPUTスクリプトを示しています。

GET https://alm-octane.example.com/api/shared_spaces/1001/external-entity-actions
HEADERS:
 - ALM-OCTANE-TECH-PREVIEW: true
PUT https://alm-octane.example.com/api/shared_spaces/1001/external-entity-actions
HEADERS:
 - ALM-OCTANE-TECH-PREVIEW: true
 - Content-Type: application/json
DATA:
{
  "data": [
    {
      "name": "defect-details",
      "title": "Defect Details",
      "entity_type": [
        "defect"
      ],
      "views": [
        "list",
        "details"
      ],
      "icon": "rss",
      "url": "http://corporate.domain.example.com?entity_ids={entity_ids}&entity_type={entity_type}&shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&octane_url={octane_url}&story_points={entity.story_points}&logical_name={entity.logical_name}&action=defect-details",
      "single_entity": true,
      "events": true,
      "workspaces": [
        1002
      ]
    }
  ]
}

トップに戻る