A search field lets you search in a data source and select an entry out of a list. This is especially good for large data sets with more than 1000 items. Search fields can be combined with other search fields, info panels or native custom fields to build complex use cases.

A search field is a virtual field that will render selected values into a specified native Jira custom field.

How the result looks like

Search field

This is the initial state of a typical search field with no value selected.

Searching an entry

Starting to type or opening the dropdown will trigger a live search and the result shown as a dropdown list below the field with a maximum of 100 items.

Selecting values

Selecting a value from the dropdown will write the selected value (based on the configuration) into the target custom field and additionally show the value within the field itself.

Multi-select (optional)

The selection of multiple values can be activated in the configuration

Select-list behaviour

Just opening the search field will display up to 100 items without the need for a search query. This way the search field can also act like a normal select list.

Dependant / Nested Search

A common use case is the need to have dynamic select lists that depend on other search fields or custom fields. A search field can be dependent on other fields by using the Context Filter in the configuration step. In the Context Filter section of the documentation you will find good examples for building dependencies between fields.

Field Placement

There are two options to place a search field within the issue view.

  • Glance (right side)

  • Content View (left side)

In addition to the placement in the issue view you can enable Jira Service Management Create Request support to display this field in your customer portal at creation time.

Glance (right side)

When using glance as placement navigate to any issue and find it at the right side bar.

The Glance (right side) placement is also supported in the Jira mobile app.

Content View (left side)

When using content view as placement navigate to any issue. The panel will be at the top right below the summary.

Setup

Data Source

After selecting the data source the simulation starts and displays the raw result of your data to work with. In the following we will use a data source with this JSON result:

{
  "userlist": [
    {
      "id": 1,
      "name": "Mario Speedwagon",
      "role": "Owner",
      "alias": null
    },
    {
      "id": 2,
      "name": "Anna Sthesia",
      "role": "Developer",
      "alias": "Anna"
    }
  ]
}
JSON

Context Filter

The optional context filter allows you to filter the search repository based on issue values. In this example we don’t use a context filter because we want to search over all items of our list. But in this field you would define any dependency on other fields (nesting)

More examples and details about Context Filter can be found in the dedicated section of the documentation.

Select List Repository

First select the list in which the search takes place. The result must be a list of entries.

$.userlist[*]
CODE

ID Field

ID stands for Identifier and must be a unique number or string that identifies an item in the data set.

Relative to the selected repository list define a path to an unique identifier. This field is used to find the selected value later. It can be the same as search field and value field

$.id
CODE

Search Field

Relative to the selected list define a path to the field that is used as a base for the search. This means when a user starts typing only this value will be searched for matches.

$.name
CODE

or

{$.name} {$.role} {?$.alias}
CODE

Using multiple fields like this will let you search in role, name & alias. It is important to use the ? for the alias field because it can contain null values. This will simple replace the alias with an empty string instead of failing because of a missing value.

Value Field

Relative to the selected list define a path to the value that should be written into the target custom field after selection.

$.name
CODE

This will write Mario Speedwagon into the target custom field

user:{$.name} role:{$.role} alias:{?$.alias}
CODE

This will write user:Mario Speedwagon role:Owner alias: into the target custom field

Value Label (optional)

Relative to the selected list define a path to the value that should be displayed for selected values. Is the same as Value Field if left empty

{$.role}: {$.name}
CODE

This is resulting in Owner: Mario Speedwagon if selected

Search Template (optional)

Lets you define the dropdown list rendering

{{ name }} – [{{ role }}]
CODE

This is resulting in Mario Speedwagon [Owner] for the first entry. See the Template Syntax section for more details on how to build more complex templates

Enable Multi-select

This options allows you to select more than one value. When activated a separator can be chosen which splits all the values. A selection of multiple values with the separator ; would look like this:

value1;value2;value3
CODE

Using a Text Field (multi-line) for the search result you can spread the values across lines. To accomplish this set the separator to the following value:

{break}
CODE

This will enforce a single line per value and would look like this:

value1
value2
value3
CODE

When using a Labels field type the separator will be ignored and each value will be its own label tag. When using a Labels field be aware that whitespaces within a value will split it into multiple label tags.

Target Behaviour

You can choose between the following two options:

  • Write value field (default)

  • Read and write ID field

Write value field (default)

With this option the search field writes the value field of the selected option(s) into the target field. The value field can use any kind of value(s). This is a one way street, meaning a manual change in the target field has no effect on the state of the search field.

Read and write ID field

With this option the search field writes the ID field of the selected options(s) in the target field. The ID field must always point to the same search field entry. A manual or automated change of the target field will also change the state of the search field.

The target behaviour “Read and write ID field” does currently not support JSM Create Requests.

Target Jira Field

This option defines the Jira custom field to write the value of the selected options to. Value Field defines the value that gets written.

No Issue Refresh

If activated, this field will not trigger an issue page refresh after a value is selected or deselected. An issue page refresh is useful if you display the target field on the issue and want any change to be reflected without a manual page refresh. An issue refresh can impact usability and performance, because the refresh will also reload all fields.

Enable JSM Create Request

This option enables this field on the create request screen of Jira Service Management customer portal.

Combining Fields

A search field can be combined with an Info Panel or a dependant field. This allows for a use case where you want your userbase search for an entry in your data source and show them additional infos based on that search and/or save additional custom fields based on that search.

Positioning

When using multiple search fields in combination with info panels you might need to order them. By default fields are ordered by name in ascending order. To overwrite this behaviour use the Position field by setting a value bigger than 1. The field with the lowest number will appear at the top.