Advanced use of the JIRA issue collector
Customizing the JIRA issue collector
- Set up a custom trigger, so the feedback form launches from a different link or button than the packaged triggers provided.
- 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.
On this page:
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
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.
Adding the custom trigger function manually
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.
The triggerFunction will be invoked by the issue collector after the $(document).ready() phase.
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. 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 (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.
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.
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):
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):
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.
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.
Special case fields
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.
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.
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:
- 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.
Then, create separate namespaces for each of the issue collectors in the ATL_JQ_PAGE_PROPS object.
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.
Embedding the issue collector is not currently supported in Confluence Cloud.
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.
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.
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?
Thanks for your feedback!