How to Create and Configure đđ Issue Pickers
Complete guide to creating and configuring VIP.LEAN Issue Pickers: both ways to create one, the sections Field, Selection, Display and Links, the live preview, and adding the field to screens.
1. Create an Issue Picker in the App (Recommended)
Required Jira Role: Jira Administrator
- Open Settings âș Apps and choose Issue Picker in the sidebar. Jira admins also find it under Apps âș Issue Picker.
- Click + Issue Picker, or Create Issue Picker if the list is still empty.
- Fill in the sections described in chapter 3. Only the Name is required.
- Click Create. The app creates the Jira custom field and saves its settings; this can take a moment.
- Add the new field to your screens (chapter 4). The app does not do this for you.

2. Create an Issue Picker in Jira's Field Settings
Required Jira Role: Jira Administrator
- In Jira's custom field settings, create a new field of the type VIP.LEAN Issue Picker and give it a name and, optionally, a description.
- Open Settings âș Apps âș Issue Picker and click Re-index. Only then does the app know the new field. Until then, the field shows âIssue Picker configuration is broken, please contact your JIRA administrator.â on work items.
- Open the new picker with Edit and configure it (chapter 3). After the re-index it starts with default settings: no link type, no JQL, and Use app permissions for the search switched on.
3. How to Configure an Issue Picker
Required Jira Role: Jira Administrator
The editor has four sections. A tag next to each one shows where its settings apply:
- All contexts: the same for every space and work type.
- Default context: the defaults of the picker. A context can override them for specific spaces and work types; see How to Manage Existing Issue Pickers.
3.1 Field

| Setting | Default | Description |
|---|---|---|
| Name | Required | Shown as the field name on work items and saved on the Jira custom field. Up to 255 characters. |
| Description | Empty | Optional. Saved as the description of the Jira custom field. |
| Field ID | â | Shown when you edit a picker, read-only, e.g. customfield_10096. Use it in JQL, Automation rules and the REST API. |
| Multi-Select | Off | Several work items can be picked in the field. The same in every context, because the stored value and the links depend on it. |
3.2 Selection
How the picker searches and which work items it offers. These are the defaults; a context can override them.

| Setting | Default | Description |
|---|---|---|
| Hide key in picker | Off | The picker lists summaries only. Turning it on also turns on Deactivate key search. |
| Deactivate key search | Off | Typing a work item key no longer finds the work item directly. |
| Use app permissions for the search | Off | The search runs with the app's permissions instead of those of the user filling the field. Users can then see key and summary of work items they cannot open. Pickers from older app versions have it on. |
| Restricted to current space | Off | Only work items of the current space are offered. |
| Add subtasks of the current work item | Off | Subtasks of the current work item are offered in addition to the selection filter. Off: no subtask is offered. Pickers from the previous version show âNot set yetâ and keep offering subtasks that match the filter until you click Leave them out. |
| JQL | Empty | Optional. Only work items matching this query are offered. Checked against Jira while you type; up to 8,000 characters. |
3.3 Preview the Search
Below the filter, Preview runs the real search in Jira, as the field does: with the app's permissions or with yours, depending on Use app permissions for the search.
- Screen: Create, View or Transition, and Portal create for service spaces.
- Current work item: on View and Transition, the work item the field is on. On Create and Portal create, choose Space · Work type instead.
- Search sent to Jira: the exact JQL, followed by the work items it finds, 100 at a time.
In the picker's own Selection section, the preview covers the spaces and work types that have no context of their own.

3.4 Display
What the field shows for each picked work item on the work item view. Choose any of Issue Type, Issue Key, Summary, Status, Assignee and Priority; new pickers show all six. Issue Key or Summary stays shown, so each picked work item can be recognised. Hiding the key also removes the link to the picked work item.
The display fields apply to the work item view. The list in the picker itself shows the work type icon, key and summary.

3.5 Links
Keeps the field value and the Jira issue links of the work item in sync. The same in every context.

| Setting | Default | Description |
|---|---|---|
| Link type | No issue link | The Jira issue link created between the work item and each picked work item. Removing a work item from the field deletes its link. This also applies to values set by Automation rules or the REST API. |
| Remove field value if link is deleted | Off | Deleting the issue link in Jira also removes the work item from the field. |
| Add field value if link is added (multi-select) / Add field value if empty and link is added (single) | Off | Creating the issue link in Jira also puts the work item in the field, if the picker would offer it there. A single-select field is only filled when it is empty. |
4. How to Add the Issue Picker to Screens
Required Jira Role: Jira Administrator
The app creates the field but does not add it to any screen. Do this with Jira's standard functions.
4.1 Company-Managed Spaces
Add the field to the create, edit and view screens of the spaces and work types where you need it, and to transition screens if people should fill it during a transition. The field appears in Jira's list of custom fields with the type VIP.LEAN Issue Picker.
4.2 Team-Managed Spaces
In the space settings, open the work type, find the Issue Picker in the list of fields and drag it into the layout.
4.3 Jira Service Management Portal
To use the field in the portal, add it to the request form of the request type.