Discover Jira Cloud products
Learn more about Jira Cloud products, features, plans, and migration.
Customize the Jira issue collector
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.
Warning: The JavaScript exposed by the issue collector is not considered a stable API and may change with new Jira releases.
Setting up a custom trigger
Configuring 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:
Add a new issue collector, or edit an existing issue collector.
Scroll down to section Trigger and select the option 'Custom'.
You don't need to set any Trigger Text as this will be overridden by your custom trigger.
Adding 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 on the Atlassian Community forums.
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.
Note: In Jira 5.1 (and version 1.1 of the Issue Collector plugin), the issue collector administrative interface lets 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')
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<head>
<!-- We pasted the generated code from the Issue Collector here, after choosing a custom trigger -->
<!-- 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
Setting 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.
Visible fields (setting 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.
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 key-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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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):
1
2
3
4
5
6
7
8
<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:
1
2
3
4
5
6
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):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<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:
1
2
3
4
5
6
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
<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.
1
2
3
4
5
6
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:
1
2
3
4
5
6
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.
1
2
3
4
5
6
7
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 in the environment field in the Jira issue.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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:
Include the generated JavaScript for both of your issue collectors in the page.
Find the id of each collector. This can be done one of two ways:
The parameter of the script is "collectorId=<8 character id>. That's the ID you want.
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.
1
2
3
4
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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 Include Macro. Note that using the HTML Include 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.
Embedding the issue collector is not currently supported in Confluence Cloud.
Full source code
This source code shows how to embed two different issue collectors on the same page with custom triggers.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
<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:
The issue collector strings set by the Jira Administrator
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:
Use the custom feedback template for the issue collector
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.
Was this helpful?
Still need help?
The Atlassian Community is here for you.