Field Configuration

Quick access: You can also get to this same configuration page from the Fields Dashboard, which centralizes all your Dynamic Work Item Picker fields.

The Dynamic Work Item Picker field configuration is integrated directly into the Jira Cloud administration, allowing you to manage its behavior from the same place you manage the rest of your custom fields.

Where to find the configuration?

To start configuring your field, follow these steps:

1. From the main Jira navigation, go to Settings (⚙️) and then to Work Items.
2. In the left sidebar, under the FIELDS section, click Custom fields.
3. Find your Dynamic Work Item Picker Field type field in the list. On the right, click the actions menu (•••) and select Contexts and default value.

4. Within the field's context settings, you will find the link to Edit custom field configuration. Clicking it will open the add-on's specific configuration modal.

---

The configuration modal allows you to customize both the logic and the appearance of the field through two tabs: General and View.

General Tab

Here you define the business rules for your field.

Limit selectable work items with JQL

Use the JQL Filter field to create a query that filters the work items users can find and select. This is ideal for ensuring that only relevant work items are linked.

• Use case: If you want a field to only allow linking "Bugs" from the current project that have not been closed, you could use a JQL like:

  project = currentProject() AND issuetype = Bug AND status != Closed

JQL Validation on Edit

The Dynamic Work Item Picker field includes an intelligent validation to maintain data integrity when the JQL filter is changed.

• What happens if I change the JQL and there are work items that no longer meet the new condition?
  • The work items that were already selected in the field will be kept, but when editing the work item, the user will see a warning above the field indicating which work items are no longer valid.

This prevents the loss of historical data and, at the same time, ensures that new selections adhere to the rules you have defined.

Dynamic Variable Support in JQL

To make your JQL filters even more powerful and contextual, the field supports the use of dynamic variables. These variables are automatically replaced with the corresponding value from the current work item where the field is displayed.

The supported variables are:

• {{currentUser}}: Is replaced by the accountId of the user currently viewing the work item. Ideal for showing only work items assigned to the current user.
• {{issue.key}}: Is replaced by the key of the current work item (e.g., PROJ-123).
• {{issue.issuetype}}: Is replaced by the name of the current work item's type (e.g., Bug, Story).
• {{issue.priority}}: Is replaced by the name of the current work item's priority (e.g., High, Medium).
• {{issue.project}}: Is replaced by the key of the project the current work item belongs to (e.g., PROJ).
• {{issue.customfield_xxxxx}}: Is replaced by the value of a custom field in the current work item. Replace xxxxx with the custom field ID (e.g., {{issue.customfield_10001}}).

Example usage:

To show only issues of the same type and with the same priority as the current issue, you could use:

issuetype = '{{issue.issuetype}}' AND priority = '{{issue.priority}}'

Enable multiple selection

By default, the field only allows selecting one work item. If you need to link multiple work items, change the Selection type to Multiple selection.

Add a help note

The Note field allows you to write a short text as a visual aid for users who access the field configuration.

---

View Tab

Here you customize the information displayed for the selected work items, giving your team context at a glance without needing to open the work item in a new tab.

Enrich the field display

In addition to the icon, key, and summary of the work item (which are always displayed), you can choose to show:

• Assignee: Shows the avatar of the work item's assignee.
• Status: Shows the current status of the work item with its corresponding color (e.g., "In Progress," "Done").
• Priority: Shows the work item's priority icon.

By activating these options, the information will appear directly in the work item view where the field is used, as seen in the following image:

Once you finish adjusting the settings, don't forget to click Save Changes.

JQL Search

All Dynamic Work Item Picker fields are indexed by Jira, and their content can be searched via JQL. This allows you to create advanced queries, filters, and dashboards based on the values of your Dynamic Work Item Picker fields.

How it works

When you select an work item in an Dynamic Work Item Picker field, the field stores the key of that work item (e.g., PROJ-123). Therefore, your JQL searches should use the work item keys to filter.

Supported Operators

You can use the standard JQL operators for text fields, such as:

Operator	Search Example
=	"My Dynamic Work Item Picker Field" = "PROJ-123"
!=	"My Dynamic Work Item Picker Field" != "PROJ-123"
IN	"My Dynamic Work Item Picker Field" IN ("PROJ-123", "PROJ-456")
NOT IN	"My Dynamic Work Item Picker Field" NOT IN ("PROJ-123", "PROJ-456")
IS	"My Dynamic Work Item Picker Field" IS EMPTY
IS NOT	"My Dynamic Work Item Picker Field" IS NOT EMPTY

Remember to replace "My Dynamic Work Item Picker Field" with the actual name of your custom field.

---

Using the Field in Workflow Transitions

If you want to use the Dynamic Work Item Picker field on a workflow transition screen (for example, when closing or resolving a work item), you may need to enable Jira's new transition view, which is currently a "Labs" feature.

Follow these steps to activate the new transition experience:

1. Log in to your Jira account.
2. Click on your profile icon in the top right corner and select Account settings.
3. On the account settings page, go to the Product settings tab.
4. Locate and select the Jira instance you wish to modify (each instance is presented as a link).
5. Once in the instance's settings, navigate to the General tab.
6. Find the Jira Labs section and enable the New transition experience option.

Once this feature is enabled, you will be able to add your custom field to transition screens, and it will work as expected.