Cloud
Data Center 9.17
Versions

Advanced use of the Jira issue collector

Using the issue collector

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Customizing the Jira issue collector

The Jira issue collector can be used without any additional JavaScript beyond the single line generated in the issue collector administration screens in Jira. However, you can also customize the Jira issue collector in a number of different ways:

  • Set up a custom trigger, so the feedback form launches from a different link or button than the packaged triggers provided.
  • Set the default values of fields for your users, using JavaScript.  
  • Specify the values of fields on the issue, which are not shown in the feedback form.

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

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

On this page:

Setting up a custom trigger

Configure your collector to use a custom trigger

If you want to use a different trigger, or button, to launch the issue collector on your website, configure your issue collector as described below:

  1. Add a new issue collector, or edit an existing issue collector.
  2. Scroll down to section Trigger and select the option 'Custom'.
  3. You don't need to set any Trigger Text as this will be overridden by your custom trigger.

Add the issue collector script for a custom trigger


Creating and debugging custom scripts are outside of the scope of Atlassian Support. For assistance, please post any questions at https://answers.atlassian.com

The issue collector script generated by Jira for adding a custom trigger is slightly different to the script generated for the standard triggers, because it includes the JavaScript function for the custom trigger.

Customization of the issue collector is done by creating/extending the global object ATL_JQ_PAGE_PROPS.  This allows you to add a custom trigger, set default values for fields and more.

In Jira 5.1 (and version 1.1 of the Issue Collector plugin), the issue collector administrative interface let you define the custom trigger function UI, and you did not need to include it in the JavaScript on the page.  In version 1.2 of the Issue Collector, the custom trigger JavaScript is a part of the generated JavaScript that you should copy and paste into your web page.

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

In the example below, we've added a simple button in HTML, and made that button launch the issue collector. This is done simply by replacing 'myCustomTrigger' in the generated JavaScript with the HTML id of the button ('feedback-button')

<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>


Adding the custom trigger function manually

The custom trigger JavaScript will be included in the JavaScript generated by the issue collector.  However, this section provides details on how you could do it without pasting in the additional lines of generated JavaScript.

To add a custom trigger, add the property triggerFunction in the global object ATL_JQ_PAGE_PROPS.  triggerFunction needs to be defined as a function and takes one argument which is the function for displaying the issue collector.

You can invoke the issue collector from any element on your page by adding a click handler in triggerFunction as shown below. In this example, we will be calling the issue collector from our #feedback-button anchor tag defined in the above HTML markup.  You can assign multiple triggers for the same issue collector by adding more click handlers.

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
	}

});

The triggerFunction will be invoked by the issue collector after the $(document).ready() phase.

Setting field values from JavaScript

Set field values

The issue collector gives you the option to set field values for any of the fields on the issue 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 Issue Create Screen to extract the field names and values relevant to your issue collector. Please note that the Issue 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 issues from external websites. The Jira Travel App is a good example of how you can build a front end interface with Jira as the back end.

Visible fields (set default field values)

If you set the value of a field that is visible on the issue collector feedback form, the fields will already be filled in with that value when the form opens.  

Set hidden fields

There might be cases where you might want to set a field value without actually displaying the field on the issue 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 issues created with the issue collector.

JavaScript for setting field values

Setting field values is done by specifying field name / value pairs within the "fieldValues" block of window.ATL_JQ_PAGE_PROPS.  If you already have a custom trigger defined, you can simply add to the definition of window.ATL_JQ_PAGE_PROPS like the example below.

Note the names of the fields are always the names of the field in the Jira Create Issue Screen, not any overridden names you may have provided in the issue collector form.

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

Examples of how to set specific field types 

Text field example

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


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

And here's how you set the value of the field in JavaScript:

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

Select list example with issue priority

Setting the value for a select list field, such as the issue priority, requires a little more effort, because you need to know the HTML element id for the choice you want to select.  Here's the markup for the Priority field in the issue collector (you do not need to add this, this is simply to show the representation that the issue collector contains):

<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>

And here's how you set the value of the field in JavaScript:

fieldValues: {
	'priority': '2'
}

Multi-select or checkboxes example

Setting the value for a multi-select (like the Browser field) or checkbox requires that you provide an array of values. Like the select list, you need to know the values to set, by looking at the markup on the Create Issue Screen.

<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>

And here's how you set the value of the field in JavaScript: the field values must be set as an array of values, even if there is only one value.

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

Custom fields

Setting a value for a custom field is exactly the same as any other field in Jira. Since multiple custom fields can share the same name, custom fields will be referenced by "customfield_" + the Id of the custom field in Jira. This ID can be seen in the HTML markup for the Create Issue Screen in Jira, but can also be determine by looking at the URLs on the custom fields screen in Jira administration. Here's what the JavaScript would look like for setting a custom field whose id in Jira was 11111:

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

Cascading selects

Setting a value for a cascading select is done in two steps - one for the parent value and one for the child.  Below is an example of setting the value of a cascading select field.

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

Special case fields

Environment field

By default, the issue collector puts user context such as the URL, User-Agent and screen resolution in the environment field.  There might be cases where you wish to include more information in the environment field.  In this case, you can add the property environment in the global object ATL_JQ_PAGE_PROPS. This allows you to add key value pairs that will appear on the environment field in the Jira issue.

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

Restricted fields

Some fields that require a user to be logged into Jira cannot be set through JavaScript. Assignee is an example of a field that cannot be set via JavaScript.

Dynamic functions

Environment and fieldValues properties can also be a function returning a JSON object that will be executed immediately when the collector trigger is shown (not just before opening the collector form). This might come in handy when you might wish to capture contextual information relevant to the user.

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 issue collectors

If you want to have two different forms appear on the same web page, you will need to create two different issue collectors in Jira. To set custom triggers, or set field values on those issue collectors requires a few changes to your page:

  1. Include the generated JavaScript for both of your issue collectors in the page.
  2. Find the id of each collector.  This can be done one of two ways:
    1. The parameter of the script is "collectorId=<8 character id>.  That's the ID you want.

    2. Go to the Issue Collector page in the Admin section and click on the Issue Collector you wish to embed. Copy the collectorId from the URL.

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

Then, create separate namespaces for each of the issue 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 issue collector

Embedding the issue collector in your Confluence Site

The issue collector can be embedded into Confluence using the HTML Macro. Note that using the HTML Macro would require you to embed the issue collector code separately on each page.

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

Embedding the issue collector is not currently supported in Confluence Cloud.

Jira

The issue collector can be embedded in the announcement banner on a Jira page by embedding the above script and HTML markup for your custom trigger in the announcement banner configuration screen. If you wish to change the location of your custom trigger, this can be easily done via jQuery. The following snippet shows how you can add the custom trigger onto the footer of all Jira pages.

You cannot embed an issue collector in your Jira Cloud site since HTML markup is disabled for the announcement banner.

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

});

Please note that embedding the issue collector requires you to enable HTML markup for the announcement banner.

Full source code

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

<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>

Is localization of an issue collector possible?

You can create an issue collector 100% localized to the default language of your Jira instance. Beyond that, complete localization of the issue collector is not possible.

The strings and text in the issue collector feedback form of the issue collector is a combination of:

  1. The issue collector strings set by the Jira Administrator
  2. Either the default language setting for Jira, or the language preference of the user if they are logged in to Jira.
  • All users will see the names of the fields as they are set by the Jira Administrator. These are not affected by the default language of Jira, and are not affected by the default language of logged in Jira users.
  • All users will see the field descriptions as they are set in the Jira Administration UI.
  • For everything else:
    • Anonymous users will see everything else in the default Jira language.
    • Logged in users will see everything else in the feedback form in the language specified by their Jira profile.

Because of the above, you cannot create a single issue collector that will present itself entirely in the language of the end user.  

However, if you want to create an issue collector that will present itself to anonymous users in the default language of your Jira instance, you should:

  1. Use the custom feedback template for the issue collector
  2. Change the field labels in Jira, and the labels for name and email, to the words you want to use in the default Jira language.

The language setting of the browser will not impact the text in the feedback form.

Last modified on Dec 19, 2022

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.