Jira 作業項目コレクターをカスタマイズする

Jira 作業項目コレクターは、Jira の作業項目コレクター管理画面で生成される 1 行のコード以外に、追加の JavaScript を使用することなく利用できます。ただし、Jira 作業項目コレクターはさまざまな方法でカスタマイズすることもできます：

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

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

警告: 作業項目コレクターが公開する JavaScript は安定的な API とはみなされておらず、新しい Jira リリースで変更される可能性があります。

カスタムトリガーを設定

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

別のトリガーやボタンを使用して Web サイトで作業項目コレクターを起動したい場合は、以下の説明に従ってコレクターを設定してください：

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

カスタムトリガー用の作業項目コレクタースクリプトを追加する

カスタムスクリプトの作成やデバッグは、アトラシアンサポートの範囲には含まれません。支援が必要な場合は、アトラシアンコミュニティのフォーラムに質問を投稿してください。

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（'feedback-button'）に置き換えるだけで実行できます

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

	<!-- This is the script for the work item 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 Work Item 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 work item collector here
	}

});

triggerFunctionは、$(document).ready()フェーズの後に作業項目コレクターによって呼び出されます。

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

フィールド値の設定

作業項目コレクターでは、作業タイプの任意のフィールドにフィールド値を設定するオプションを利用できます。これを実行するには、グローバルオブジェクト ATL_JQ_PAGE_PROPS に fieldValues プロパティを追加します。さまざまなフィールドタイプの既定値を設定するために、それぞれ別の方法が存在します。下記のコード例は、Jira の 1 つのフィールドおよびそれに関連するマークアップを視覚的に表現したものであり、該当するフィールドタイプの既定値を設定する方法を示しています。Jira の作業項目作成画面で Firebug などの DOM 検査ツールを使用して、作業項目コレクターに関連するフィールド名と値を抽出します。作業項目コレクターは Jira REST API に代わるものとして想定されているわけではないことにご注意ください。高度にカスタマイズされたソリューションが必要な場合、Jira REST API を利用して、外部の Web サイトから Jira 作業項目を作成できます。

可視フィールド（既定のフィールド値の設定）

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

非表示フィールド

作業項目コレクターでフィールドを実際に表示しないで、フィールド値を設定したい場合があります。この場合は、上記と同様の方法で、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 の他のフィールドとまったく同じです。複数のカスタムフィールドが同じ名前を共有できるため、カスタムフィールドは Jira のカスタムフィールドの ID に "customfield_" を付けて参照されます。この ID は、Jira の作業項目作成画面の HTML マークアップで確認できますが、Jira 管理のカスタムフィールド画面の URL を確認することでも特定できます。JavaScript で、Jira の ID が 11111 のカスタムフィールドを設定する場合は次のようになります：

    
            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 Include Macro を使用して Confluence に埋め込むことができます。HTML Include Macro を使用する場合は、作業項目コレクターのコードを各ページに個別に埋め込む必要があることにご注意ください。

作業項目コレクターは以前はユーザーマクロにより Confluence に埋め込むことができ、再利用可能な作業項目コレクターマクロを作成し、他の Confluence ユーザーがページに埋め込むことができました。このオプションは既知のバグにより現在利用できません：CONF-26104。

作業項目コレクターの埋め込みは、現在 Confluence Cloud ではサポートされていません。

完全なソースコード

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

    
            <body>

	<h2>JIRA Work Item 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 Work Item 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 work item 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 言語で使用したい単語に変更します。

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

この内容はお役に立ちましたか?

正確ではなかった明確ではなかった関係なかった

さらにヘルプが必要ですか?

アトラシアンコミュニティをご利用ください。

コミュニティに質問