Issue Picker

A field that allows for picking an issue, or issues, from a pre-defined JQL query. Examples for usage might be:

  • A field that represents the development issue for this support request

  • In an ITIL workflow, you may wish to link Incident records to Problems

This is similar to a standard issue link, but has some advantages, and disadvantages, versus an issue link.

  • The primary problem with issue links is that you can’t control the subset of issues that can be linked to. This field allows you to do that by specifying a JQL query

  • Issue links are not fields, which means linking is always available. With a field you can enforce a link, or hide it at certain states of the workflow

  • All aspects of the field can be controlled with a behaviour, for example setting read-only, required, hidden, setting a default value, or even changing the JQL controlling which issues can be selected. For example, you may want additional issue types to be shown in the picker field, depending on the data entered previously on the issue screen.

    groovy
    setConfigParam('currentJql', 'type=Task')

  • Link types are global. You may have a link between issues which is a very specific type - if you create this as a link type it will be available globally

A disadvantage of using this field is that there is no reciprocal link available currently. In order to find issues linking to an issue you would need to execute a JQL query.

For advanced usage, including customisation of the JQL, the drop-down behaviour and how the displayed value is rendered, see Issue Picker Customizations.

Usage

  1. Create a new field via Admin → Script Fields.

    Although you can create these types of fields via Admin → Custom Fields, you cannot configure them there, so it is easier to do it through the ScriptRunner interface.

  2. Enter a Preview Issue Key and click Preview to view the drop-down.  Previewing is useful to verify that the picker is only displaying the correct candidate issues.

  3. Select an issue, or issues, in the drop-down, to view how the result will be displayed when viewing an issue, and in the Issue Navigator (column view).



After creating the field ensure it has the correct context and the correct screens.

Search Fields

By default, when selecting an issue from the drop-down, users search for an issue by typing terms from the Summary or the Issue Key which display in the drop-down. Then, when viewing an issue, a user can see the Issue Key, Summary, Status and Priority.


It is possible however, to show information from other fields in your issue picker alongside the Issue Key. For example, you may want to show details of a custom field. Any field that is added here can also be searched upon in the drop-down.

If you use multiple fields, they are separated with a hyphen symbol. We recommend previewing the results, and select different target issues to verify the result are as you expect.

We recommend keeping the Issue Key in the list of Fields to Search - if the user knows the key they want to select, this will be the easiest way for them to enter it.

You should ensure that any custom or system fields you choose to be part of search fields have a non-empty and unique value, at least in combination with other fields you choose to show.

You can ensure that the value is non-empty by adding a clause to your JQL query for each field (other than issue key and summary) to the JQL, for instance: IncidentID is not empty.

If you would like to further customise the display value, then see Issue Picker Customizations.

Searching

You can search for issues linking to a particular issue, example:

"Related Problem" = "MSD-5"
"Related Problem" in ("MSD-5", "MSD-6")

You can also use the IN, !=, NOT IN operators, or the basic search mode.

To find issues based on a search of the issues they link to, see issuePickerField function.

Programmatic Updates

Creating an issue using IssueService:

        def issueService = ComponentAccessor.issueService
        def issueInputParameters = issueService.newIssueInputParameters()

        issueInputParameters.addCustomFieldValue(fieldId, "MSD-5")

If you retrieve or set the value directly on the issue, the result will be an Issue object, or if you have chosen a multiple issue picker, a Collection<Issue>.

        // single issue picker
        assert issue.getCustomFieldValue(customField) instanceof Issue

        // multiple issue picker
        assert issue.getCustomFieldValue(customField) instanceof Collection
        assert issue.getCustomFieldValue(customField).every { it instanceof Issue }

REST

Setting a multiple issue picker:

groovy
fields: {
    customfield_12345: ["MSD-5", "MSD-6"]

Adding to a multiple issue picker:

groovy
update: {
    customfield_12345: [
        {"add" : "MSD-5"}
    ]
}
On this page