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

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

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

This page assumes you are already familiar with using the work item collector.

Warning: The JavaScript exposed by the work item collector is not considered a stable API and may change with new Jira releases.

カスタムトリガーを設定

Configure your collector to use a custom trigger

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

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

Add the work item collector script for a custom trigger

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

Jira がカスタムトリガーを追加するために生成する作業項目コレクタースクリプトは、カスタムトリガー用の JavaScript 関数が含まれているため、標準トリガー用に生成されるスクリプトとは若干異なります。

作業項目コレクターのカスタマイズは、グローバルオブジェクトATL_JQ_PAGE_PROPSを作成/拡張することで行います。これにより、カスタムトリガーの追加、フィールドのデフォルト値の設定などが可能になります。

注意：Jira 5.1（および作業項目コレクタープラグインのバージョン 1.1）では、作業項目コレクターの管理インターフェースでカスタムトリガー機能 UI を定義でき、ページの JavaScript に含める必要はありませんでした。作業項目コレクターのバージョン 1.2 では、カスタムトリガーの JavaScript は生成された JavaScript の一部であり、これをコピーして Web ページに貼り付ける必要があります。

The code snippet below shows a sample HTML page with the generated work item collector JavaScript.

以下の例では、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 からフィールド値を設定する

フィールド値の設定

The work item collector gives you the option to set field values for any of the fields on the work type. This is done by adding the property fieldValues in the global object ATL_JQ_PAGE_PROPS. There are different methods for setting default values for different field types. The code samples below show a visual representation of a field in Jira and its relevant markup, and how to set a default value for that field type. Use a DOM inspection tool such as Firebug in the Jira Work Item Create Screen to extract the field names and values relevant to your work item collector. Please note that the Work Item Collector is not supposed to be a replacement for the Jira REST API. If you require a more customized solution, make use of the Jira REST API to create Jira work items from external websites.

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

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

非表示フィールド

There might be cases where you might want to set a field value without actually displaying the field on the work item collector. In this case, simply use the same method as above to set the field values via JavaScript. The fields will not be shown as they were not added in the form template but their values will still be present in work itemd created with the work item collector.

フィールド値を設定する 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'
	}					
});
    

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

テキストフィールドの例

Setting the value for a text field, like the summary of the work item, is straightforward. Here's the markup for a text field like Summary in the work item collector (you do not need to add this, this is simply to show the representation that the work item collector contains):

    
            <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;
 
	}
});
    

Embedding multiple work item collectors

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

Include the generated JavaScript for both of your work item collectors in the page.
各コレクターの 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>
    

Then, create separate namespaces for each of the work item collectors in the ATL_JQ_PAGE_PROPS object.

    
            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
		}
	}
});
    

Embedding the work item collector

Confluence サイトに作業項目コレクターを埋め込む

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

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

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

完全なソースコード

This source code shows how to embed two different work item collectors on the same page with custom triggers.

    
            <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 言語で使用したい単語に変更します。

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

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

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

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

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

コミュニティに質問