Using the issue collector
What is an 'issue collector'?
The issue collector allows you to easily embed a JIRA feedback form into your own web site. This form is typically accessed by clicking a 'trigger' tab exposed along the edge of pages in your web site.
When used by people visiting your web site click this trigger tab and submit the resulting JIRA feedback form, an issue is conveniently created in JIRA.
Visitors to your web site do not require a user account in JIRA to use the JIRA feedback form.
Note: For all of the following procedures, you must be logged in as a user with the JIRA Administrators global permission.
Accessing JIRA's issue collectors
In JIRA applications, issue collectors are configured (and hence organized) on a per-project basis.
To access all issue collectors configured in JIRA:
- Choose
> System. - Select Issue Collectors to open the Issue Collectors page, which shows a list of all existing issue collectors in your JIRA system.
- Click the name of a project to access a more detailed list of issue collectors belonging to that project or click the name of an issue collector to access detailed information about it. On the issue collector page (containing detailed information), you can access:
- An activity graph, showing the number of issues created via this issue collector (Y-axis) on a daily basis (X-axis).
- A list of recent issues in reverse chronological order, which have been created via this issue collector.
On this page:
Related pages:
To access issue collectors belonging to a specific project:
- Choose
> Projects, and select the relevant project. - Select a project.
- From the project administration page, click the Issue Collectors tab. The Issue Collectors page is displayed, listing any issue collectors that have already been set up in your project:
- Click the name of an issue collector to access detailed information about it — in particular, its recent activity and details on how to embed the issue collector into your web site.
Adding an issue collector
- Choose > Projects, and select the relevant project.
- On the left of the Project Summary page, click the Issue Collectors tab. The Issue Collectors page is displayed, listing any issue collectors that have already been set up in your project.
- Click the Add Issue Collector button to open the Add Issue Collector page.
In the top section of the Add Issue Collector page, specify the following:
Name Specify the name of the issue collector, as you want it to appear throughout the JIRA user interface. Description Specify a description for the issue collector. This description will appear adjacent to the name of your issue collector, throughout the JIRA user interface. Issue type Select the type of issue that you want created in JIRA when visitors to your web site submit your issue collector's JIRA feedback form. Issue reporter Specify the username that will be the default reporter of JIRA issues created when visitors to your web site submit your issue collector's JIRA feedback form. Match reporter? Select either of the following: - Always use Issue Reporter — select this option to ensure that the default issue reporter you specify above, will always be the reporter of issues created by submission of the JIRA feedback form on your web site.
- Attempt to match user session of submitter or submitter email address — select this option if you want the reporter of an issue created by submission of the JIRA feedback form on your web site, to be a JIRA user:
- Who is logged in to JIRA when they submit a JIRA feedback form on your web site (in the same browser session).
- Who's email address matches the email address specified in the email field of the JIRA feedback form.
Please note that if the JIRA user does not have the Create Issues project permission in your JIRA project, the default issue reporter you specify above will be used as the issue's reporter.
Collect browser info Select this option to collect meta-information about your browser's statistics, which will be incorporated into issues created by submission of the JIRA feedback form on your web site. In the middle section of the Add Issue Collector page (entitled 'Trigger'), specify the following:
Trigger text Specify a short, brief phrase that will appear on the trigger tab on your web site. Trigger style Choose the style in which the trigger tab will appear on your web site. 'Custom' will not display a trigger, but will add additional javascript to the generated script, so you can create a custom trigger on your web page. In the lower section of the Add Issue Collector page (entitled 'Issue Collector Form'), specify the following:
Template Choose from the options provided. Typically, your choice would reflect the type of issue being created (i.e. chosen above). You can choose:
- A predefined template for your JIRA feedback form — either 'Got Feedback?' or 'Raise a Bug'.
- Custom to create a custom JIRA feedback form, which allows you to specify your own wording on the dialog box, as well as add or remove other fields on the form, and change their positions on the form.
- Please note that if a field is required for the chosen issue type but that field has:
No specified a default value, the field will automatically appear on the form. This field's position can be changed on the form, although it cannot be removed.
- A default value but the field is not added to the form, then the field's default value is used when an issue is created via the issue collector.
- Not all fields of types of fields can be added to the form, since some fields cannot be displayed to anonymous users. The fields types that can be displayed are:
- Standard Fields: Summary, Description, Components, AffectsVersion, Environment, Priority, Attachment
- Custom Field Types: Date Time, Radio Buttons, Multi-Checkbox, Multi-Select, Number, Select List, URL field, Version Picker, Cascading Select, Project Picker, Single Version Picker, Text Field, Free Text Field
- Please note that if a field is required for the chosen issue type but that field has:
Message Type a message, which appears in the blue 'information' panel along the top of the dialog box. Click the Submit button to save your changes.
Embedding an issue collector into your web site
After clicking the Submit button to save your new issue collector, a page containing code snippets is displayed. Use the code and information provided to embed your new issue collector into your web site.
If you accidentally click away from this page, you can easily retrieve the information that was on it by accessing your issue collector's details (above) and scrolling to the end of the page.
Editing an issue collector
Editing an issue collector should not require any changes to web pages that include the issue collector, unless you change the trigger style to or from a custom trigger. Changing the trigger style to or from a custom trigger will change the generated javascript, so you may need to change what you embed in any web page that includes the issue collector.
- Log in to JIRA as a project administrator or a user with the JIRA Administrators global permission.
- Access the relevant project's list of issue collectors (above).
- In the Operation drop-down for the issue collector you would like to edit, select Edit to open the Edit Issue Collector page.
- Update the issue collector, as desired.
- Click Update to save your changes.
Copying an issue collector
Copying an issue collector will create an entirely new issue collector and will not affect any existing issue collectors. You will need to embed it in whatever web pages you would like, just as if you had created a new issue collector.
- Log in to JIRA as a project administrator or a user with the JIRA Administrators global permission.
- Access the relevant project's list of issue collectors (above).
- In the Operation drop-down for the issue collector you would like to copy, select Copy to open the Add Issue Collector page.
- All the information from the copied issue collector will be the same as the copied issue collector, with the exception of the name (which will be "Copy of " + the original name of the copied issue collector.)
- Update the issue collector, as desired.
- Click Submit to save your changes
Disabling or deleting an issue collector
- Access the relevant project's list of issue collectors (above).
- On the list of the project's issue collectors, click Disable or Delete to respectively disable or delete the associated issue collector. While an issue collector is disabled, its trigger tabs will still be visible on pages of your web site(s) to which the issue collector code has been added until a user refreshes the page. However, clicking these triggers results in a message indicating that the issue collector is currently out of action.
Known limitations
- Placing the Issue Collector plugin within an iframe will not close the prompt window automatically.
This is a known limitation for the Issue Collector plugin, and has been tracked at JRASERVER-41400 - Getting issue details... STATUS
If an anonymous user tries to create an issue collector in a project and there are required fields present in this project, these fields are not shown to the anonymous user. As a result, the user cannot create the collector.
The workaround is to make the fields optional.This is a known limitation for the Issue Collector plugin, and has been tracked at JRASERVER-67094 - Getting issue details... STATUS