Jira 課題コレクターの高度利用

Jira 課題コレクターのカスタマイズ

Jira 課題コレクターは、Jira 課題コレクター管理画面で生成される 1 行の他には JavaScript を追加することなく使用できます。しかし、いくつか他の方法を使って Jira 課題コレクターをカスタマイズすることもできます。

パッケージ化されたトリガーで提供されるものとは別のリンクやボタンからフィードバックフォームを起動するように、カスタム・トリガーを設定します。
ユーザーの便宜のため、JavaScript を使用して、フィールドの既定値を設定します。
フィードバックフォームに表示されない、課題のフィールド値を指定します。

このページでは、すでに課題コレクターの使用に習熟しているユーザーを前提にしています。

課題コレクターが公開する JavaScript は安定的な API とは見なされておらず、新しい Jira リリースで変更される可能性があります。

On this page:

カスタムトリガーの設定

コレクターを設定してカスタムトリガーを使用する

別のトリガーやボタンを使用して、ウェブサイト上で課題コレクターを起動する場合は、以下の説明のように、課題コレクターを設定します。

新しい課題コレクターを追加するか、既存の課題コレクターを編集します。
トリガーのセクションまで下にスクロールし、「カスタム」オプションを選択します。
トリガーテキストはカスタムトリガーによって上書きされるため、設定する必要はありません

カスタムトリガー用の課題コレクタースクリプトを追加する

カスタムスクリプトの作成やデバッグは、アトラシアンサポートの範囲には含まれません。サポートが必要な場合は、https://answers.atlassian.com に質問を投稿してください。

カスタムトリガーの追加用に Jira で生成される課題コレクタースクリプトは、カスタムトリガー向けの JavaScript 機能が含まれているため、標準のトリガー用に生成されたスクリプトとは若干異なります。

課題コレクターのカスタマイズは、グローバルオブジェクト ATL_JQ_PAGE_PROPS の作成または拡張によって行います。これによって、カスタムトリガーの追加、フィールド既定値の設定、その他が可能になります。

Jira 5.1 (ならびに課題コレクタープラグインのバージョン 1.1) の場合、課題コレクターの管理インターフェイスでカスタムトリガー機能の UI を定義できるため、そのページの JavaScript に含める必要はありませんでした。課題コレクターのバージョン 1.2 では、カスタムトリガーの JavaScript は生成される JavaScript の一部であり、これをコピーして Web ページに貼り付ける必要があります。

以下のコードスニペットは、生成された課題コレクターの JavaScript を貼り付けたサンプル HTML ページを示しています。

以下の例では、HTML に簡単なボタンを追加し、そのボタンで課題コレクターを起動するようにしています。これは、生成された JavaScript の「myCustomTrigger」をボタン（「フィードバックボタン」）の HTML ID で置き換えることにより、簡単に実行できます。

<head>
	<!-- We pasted the generated code from the Issue Collector here, after choosing a custom trigger -->

	<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css"
		integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">

	<!-- This is the script for the issue collector feedback form -->

	<script type="text/javascript"
		src="<Jira URL>/s/en_US-ydn9lh-418945332/803/1088/1.2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=d03d7bd1"></script>

	<!-- This is the script for specifying the custom trigger.  We've replaced 'myCustomTrigger' with 'feedback-button' -->

	<script type="text/javascript">
		window.ATL_JQ_PAGE_PROPS = {
			"triggerFunction": function (showCollectorDialog) {
				//Requries that jQuery is available! 
				jQuery("#feedback-button").click(function (e) {
					e.preventDefault();
					showCollectorDialog();
				});
			}
		};
	</script>


</head>

<body>

	<h2>Jira Issue Collector Demo</h2>
	<a href="#" id="feedback-button" class='btn btn-primary btn-large'>Report feedback</a>

</body>

手動によるカスタムトリガー機能の追加

カスタムトリガー JavaScript は課題コレクターによって生成される JavaScript に含まれています。しかし、このセクションでは、生成される JavaScript に追加行を貼り付けることなく、カスタムトリガー機能を追加する方法について説明します。

カスタムトリガーを追加するには、グローバルオブジェクト ATL_JQ_PAGE_PROPS に triggerFunction プロパティを追加します。triggerFunction は関数として定義し、課題コレクターを表示する関数を示す引数を 1 つ取る必要があります。

以下に示すように、triggerFunction にクリックハンドラを追加することにより、ページ上の任意の要素から課題コレクターを呼び出すことができます。この例では、上記の HTML マークアップで定義された #feedback-button アンカータグから課題コレクターを呼び出します。クリックハンドラをさらに追加することにより、同じ課題コレクターに複数のトリガーを割り当てることができます。

window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {


	// ==== custom trigger function ====
	triggerFunction : function( showCollectorDialog ) {
		$('#feedback-button').on( 'click', function(e) {
			e.preventDefault();
			showCollectorDialog();
		});
 
		// add any other custom triggers for the issue collector here
	}

});

triggerFunction は、$(document).ready() 部分の後で、課題コレクターによって呼び出されます

JavaScript からフィールド値を設定する

フィールド値の設定

課題コレクターによって、課題タイプの任意のフィールドにフィールド値を設定するオプションを利用できます。これを実行するには、グローバルオブジェクト ATL_JQ_PAGE_PROPS に fieldValues プロパティを追加します。異なるフィールドタイプの既定値を設定するには、それぞれ別の方法を使用します。下記のコード例では、Jira フィールドと関連するマークアップの実際の例と、そのフィールドタイプの既定値を設定する方法を示しています。Jira 課題作成画面で DOM 検査ツール (Firebug など) を使用すると、課題コレクターに関連するフィールド名と値を抽出できます。課題コレクターは Jira REST API の代替として想定されているわけではないことに注意してください。さらにカスタマイズされたソリューションが必要な場合、Jira REST API を利用して、外部のウェブサイトから Jira 課題を作成できます。Jira をバックエンドとするフロントエンドインターフェイスを構築する例として、Jira Travel App をご参照ください。

表示フィールド (既定のフィールド値の設定)

課題コレクターのフィードバックフォーム上に表示されるフィールドの値を設定すると、フォームが開いたときに、フィールドにはすでにその値が入力されています。

非表示のフィールドを設定する

課題コレクターでフィールドを実際に表示しないで、フィールド値を設定したい場合があります。この場合は、上記と同様の方法で、JavaScript を使用してフィールド値を設定するだけです。そのフィールドはフォームテンプレートに追加されておらず、表示されませんが、フィールド値は課題コレクターによって作成された課題に含まれます。

フィールド値を設定する JavaScript

フィールド値を設定するには、window.ATL_JQ_PAGE_PROPS の "FieldValues" ブロック内のフィールド名とフィールド値のペアを指定します。すでにカスタムトリガーを定義している場合は、以下の例のように、window.ATL_JQ_PAGE_PROPS の定義に追加するだけですみます。

フィールドの名前は常に Jira 課題作成画面のフィールド名であり、課題コレクターフォームで与えられる上書き名ではないことに注意してください。

window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {

	// ==== custom trigger function ====
	triggerFunction : function( showCollectorDialog ) {
		$('#feedback-button').on( 'click', function(e) {
			e.preventDefault();
			showCollectorDialog();
		}); 
	},
	// ==== we add the code below to set the field values ====
	fieldValues: {
 		summary : 'Feedback for new website designs',
		description : 'The font doesn\'t quite look right',
 		priority : '2'
	}					
});

特定のフィールドタイプを設定する方法の例

テキストフィールドの例

課題サマリのような、テキストフィールドの値を設定するのは簡単です。以下は、課題コレクターのサマリなど、テキストフィールドのマークアップです。（これは課題コレクターに含まれる表現を表示しているだけなので、追加する必要はありません。）。

<div class="field-group">
	...
	<input class="text long-field" id="summary" name="summary" type="text" value="">
	...
</div>

そして、次は JavaScript でフィールドの値を設定する方法です。

fieldValues : {
	summary : 'This is the default summary value'
}

課題優先度の選択リストの例

課題の優先度など、選択リストフィールドの値を設定するには、選択項目の HTML 要素 ID を知っている必要があるため、もう少し努力が必要になります。以下は、課題コレクターの優先度フィールドのマークアップです。（これは課題コレクターに含まれる表現を表示しているだけなので、追加する必要はありません）。

<div class="field-group">
	...
	<input id="priority-field" class="text aui-ss-field ajs-dirty-warning-exempt" autocomplete="off">
	...
	<select class="select" id="priority" name="priority" style="display: none; " multiple="multiple">
		<option class="imagebacked" data-icon="/images/icons/priority_blocker.gif" value="1">Blocker</option>
		<option class="imagebacked" data-icon="/images/icons/priority_critical.gif" value="2">Critical</option>
		...
	</select>
	...
</div>

そして、次は JavaScript でフィールドの値を設定する方法です。

fieldValues: {
	'priority': '2'
}

複数選択またはチェックボックスの例

複数選択（ブラウザのフィールドなど）またはチェックボックスの値を設定するには、値の配列を入力する必要があります。選択リストと同様に、課題作成画面のマークアップを見て、設定する値を知っている必要があります。

<div class="field-group">
	...
	<select class="select" id="customfield_10110" multiple="multiple" name="customfield_10110" size="5">
		<option value="-1" selected="selected">None</option>
        	<option value="10039">All Browsers</option>
		<option value="10037">Chrome</option>
		...
	</select>
	...
</div>

そして、次は JavaScript でフィールド値を設定する方法です。フィールド値が 1 つだけの場合でも、値の配列として設定する必要があります。

fieldValues : {
	'customfield_10110': [ '10039', '10037' ]
}

カスタムフィールド

カスタムフィールドの値を設定する方法は、Jira の他のフィールドとまったく同じです。複数のカスタムフィールドは同じ名前を共有することが可能であるため、カスタムフィールドは、"customfield_" + Jira のカスタムフィールドの ID によって参照されます。この ID は、Jira の課題作成画面の HTML マークアップに表示されるだけでなく、Jira 管理のカスタムフィールド画面の URL を見て確認することもできます。Jira での ID が 11111 であるカスタムフィールドを設定する場合、JavaScript は次のようになります。

fieldValues : {
	'customfield_11111': 'San Francisco'
}

カスケード選択

カスケード選択の設定は 2 つの手順で行います。親値用の手順と子値用の手順です。以下は、カスケード選択フィールドの値を設定する例です。

fieldValues : {
	'customfield_12345': 'Australia',
	'customfield_12345:1': 'Sydney'
}

特殊なフィールド

環境フィールド

既定では、課題コレクターは、URL、ユーザーエージェント、画面解像度などのユーザーコンテキストを環境フィールドに置いています。環境フィールドにもっと多くの情報を含めたい場合があります。この場合は、グローバルオブジェクト ATL_JQ_PAGE_PROPS に environment プロパティを追加します。これによって、JIRA 課題の環境フィールドに表示されるキー値のペアを追加できます。

window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
	// ==== custom trigger function ====
	triggerFunction : function( showIssueCollector ) {
		...
	}, 
	// ==== default field values ====
	fieldValues : {
		...
	}, 
	// ==== Special field config for environment ====
	environment : {
		'Custom env variable'  : $('#build-no').text(),
		'Another env variable' : '#007'
	}
});

制限付きフィールド

Jira へのログインを必要とするフィールドがあり、その設定には JavaScript を使用できません。担当者は、JavaScript を使用した設定ができないフィールドの例です。

動的関数

Environment と fieldValues プロパティは、JSON オブジェクトを返す関数でもあり、この関数は（コレクターフォームを開く直前ではなく）コレクタートリガーが表示されたときに、直ちに実行されます。これは、ユーザーに関するコンテキスト情報を取得したい場合に便利なことがあります。

window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
	// ==== custom trigger function ====
	triggerFunction : function( showIssueCollector ) {
		...
	}
	// ==== Special field config for environment ====
	, environment : function() {
		
		var env_info = {};
 
		if ( window.ADDITIONAL_CUSTOM_CONTEXT ) {
			env_info[ 'Additional Context Information' ] = window.ADDITIONAL_CUSTOM_CONTEXT;
		}
 
		return env_info;
	}
	// ==== default field values ====
	, fieldValues : function() {
 
		var values = {};
 		
		var error_message = $('.error_message');
		if ( error_message.length !== 0 ) {
			// record error message from the page context rather than asking the user to enter it
			values[ 'summary' ] = error_message.children('.summary').text();
			values[ 'description' ] = error_message.children('.description').text();
		}
 
		return values;
 
	}
});

複数の課題コレクターの埋め込み

2 つの異なるフォームを同じ Web ページ上に表示したい場合、Jira で 2 つの異なる課題コレクターを作成する必要があります。カスタムトリガーの設定、または課題コレクターのフィールド値の設定を行うには、ページにいくつか変更を加える必要があります。

課題コレクターのそれぞれに対して生成された JavaScript をページに含めます。
各コレクタの ID を検索します。これには 2 つの方法があります。
1. スクリプトのパラメーターは、 "collectorId=<8 character id> です。それが必要な ID です。
2. 管理セクションの課題コレクターページに移動し、埋め込みたい課題コレクターをクリックします。URL から collectorId をコピーします。

https://<Jira_URL>/secure/ViewCollector!default.jspa?projectKey=<PROJECT_KEY>&collectorId=<copy this part here>

次に、ATL_JQ_PAGE_PROPS オブジェクト内に課題コレクターごとの名前空間を別々に作成します。

window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
	'<collectorId_1>' : {        
		triggerFunction:
			// define trigger function

		fieldValues: {
			// define field values here       	
		}
	},
	'<collectorId_2>' : {        
		triggerFunction: 
			// define trigger function		
		fieldValues: {
			//define field values here
		}
	}
});

課題コレクターの埋め込み

Confluence サイトへの課題コレクターの埋め込み

HTML マクロを使用して、課題コレクターを Confluence に埋め込むことができます。HTML マクロを使用する際、各ページに課題コレクターコードを個別に埋め込む必要がある点に注意してください。

The issue collector was previously embeddable in Confluence via a User Macro, allowing you to create a re-usable issue collector macro that other Confluence users can embed into their pages. This option is currently unavailable due to a known bug: CONF-26104 - Getting issue details... STATUS

現在、課題コレクターの埋め込みは、Confluence クラウドではサポートされていません。

Jira

上記のカスタムトリガー用のスクリプトと HTML マークアップを通知バナー設定画面に埋め込むことによって、課題コレクターを Jira ページの通知バナーに埋め込むことができます。カスタムトリガーの位置を変更したい場合、jQuery を使用して簡単に変更できます。次のスニペットは、すべての Jira ページのフッターにカスタムトリガーを追加する方法を示しています。

通知バナーの HTML マークアップがで無効になっているため、Jira クラウドサイトに課題コレクターを埋め込むことはできません。

window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
	// ==== custom trigger function ====
	triggerFunction : function( showIssueCollector ) {
		// button markup - relevant css can be added via the style attribute
		var feedbackButton = "<a id='feedback-button'>Got Feedback?</a>";
		// embed the button in the footer
		$('.footer-link').append(feedbackButton);
		
		$('#feedback-button').click(function(e) {
			...
		});
	}

});

課題コレクターを埋め込むには、通知バナーの HTML マークアップを有効にする必要があるので、注意してください。

完全なソースコード

このソースコードは、2 つの異なる課題コレクターをカスタムトリガーとともに同じページに埋め込む方法を示しています。

<body>

	<h2>Jira Issue Collector Demo</h2>
	<a href="#" id="feedback_button" class='btn btn-primary btn-large'>Report feedback</a><br />
	<a href="#" id="bug_button" class='btn btn-primary btn-large'>Report bug</a>

  	<!-- Jira Issue Collector - append this at the bottom of <body> -->
	<script type="text/javascript" src="https://<Jira URL>/s/en_US-ydn9lh-418945332/803/1088/1.2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=<collectorId_1>"></script>
	<script type="text/javascript" src="https://<Jira URL>/s/en_US-ydn9lh-418945332/803/1088/1.2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=<collectorId_2>"></script> 
 
	<!-- We will customize Jira in the following script tag -->

	<script type="text/javascript">
		// safely use jquery here since the issue collector will load it for you
		$(document).ready(function() {
 
			window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
 
				// ==== feedback collector ====
				  '<collectorId_1>' : {
 
					// === custom trigger function ===
					  triggerFunction : function( showCollectorDialog ) {
						$('#feedback_button').click( function(e) {
							e.preventDefault();
							showCollectorDialog();
						});
 					}
 
					// === default and hidden field values ===
					, fieldValues : {
 
						// default values
						  summary : 'Feedback for new website designs'
						, description : 'The font doesn\'t quite look right'
 
						// hidden field value
						, priority : '2'
						
					}
 
				}
 
				// ==== bug collector ====
				, '<collectorId_2>' : {
					// === custom trigger function ===

					  triggerFunction : function( showCollectorDialog ) {
						$('#bug_button').click( function(e) {
							e.preventDefault();
							showCollectorDialog();
						});
 					}


					// === additional environment details ===
					, environment : function() {
		
						var env_info = {};
 
						if ( window.ADDITIONAL_CUSTOM_CONTEXT ) {
							env_info[ 'Additional Context Information' ] = window.ADDITIONAL_CUSTOM_CONTEXT;
						}
 
						return env_info;
					}
					// === default field values ===
					, fieldValues : function() {
 
						var values = {};
 		
						var error_message = $('.error_message');
						if ( error_message.length !== 0 ) {

							// record error message from the page context rather than asking the user to enter it
							values[ 'summary' ] = error_message.children('.summary').text();
							values[ 'description' ] = error_message.children('.description').text();

						}
 
						return values;
 
					}
 
				}
 
			});

		});
	</script>

</body>

課題コレクターのローカライズは可能ですか？

Jira インスタンスの既定の言語に 100％ローカライズされた課題コレクターを作成できます。それ以上に、課題コレクターの完全なローカライズを行うのは不可能です。

課題コレクターの課題コレクターフィードバックフォーム内の文字列とテキストは、次の組み合わせになっています。

Jira 管理者が設定した課題コレクター文字列
Jira の既定の言語設定、またはユーザーが Jira にログインしている場合、ユーザーの言語選択のいずれか.

フィールドの名前は、Jira 管理者が設定した方法で、すべてのユーザーに表示されます。この表示は Jira の既定の言語に影響を受けることも、ログインした Jira ユーザーの既定の言語に影響を受けることもありません。
フィールドの説明は、JIRA 管理 UI で設定された方法で、すべてのユーザーに表示されます。
他のすべての項目の場合：
- 匿名ユーザーには、他のすべての項目が既定の JIRA 言語で表示されます。
- ログインしたユーザーには、フィードバックフォーム内の他のすべての項目が Jira プロファイルで指定された言語で表示されます。

以上のことから、すべてがエンドユーザーの使用する言語で表示される課題コレクターを作成することはできません。

しかし、匿名ユーザーに対して Jira インスタンスの既定の言語で表示される課題コレクターを作成したい場合、次のような方法をとります。

課題コレクター用のカスタムフィードバックテンプレートを使用します。
Jira のフィールドラベルおよび名前とメールのラベルを、既定の JIRA 言語で使用したい単語に変更します。

ブラウザの言語設定は、フィードバックフォームのテキストには影響しません。

ページ

Viewport

Confluence