Dependencies on the user input

In Jira, limiting the number of options available in select lists for custom fields is important for both user experience and system reliability.

When too many options are available, several challenges can arise:

Usability: Too many options can make the field hard to browse and search.
Performance: Fetching and rendering large datasets can slow down the field.
API restrictions: Many APIs limit the number of results returned per request.
Elements Connect limits: By default, Elements Connect custom fields and connected items can display up to 1,000 values at once.

To avoid these issues, it is recommended to delay the data source request until the user has typed a minimum number of characters, and to filter the results based on that input. This is achieved using the $userInput dependency.

$userInput represents the text entered by the user in the field and can be injected dynamically into SQL queries or REST API requests to reduce the dataset before it is returned.

Example: Customer list from a CRM

Consider a custom field called Customer, populated from a CRM database containing thousands of company names. Displaying all customers at once would be impractical.

Instead, you can configure the field to return only customers that match what the user types.

If the user starts typing “Acme”, the field will only search for customer names containing that value.

SQL data source example configuration:

CODE

SELECT name FROM customers WHERE company_name ILIKE '%' || '$userInput' || '%'

When the user types "Acme", the executed SQL query will be:

CODE

SELECT name FROM customers WHERE company_name ILIKE '%' || 'Acme' || '%'

This query dynamically filters results as the user types, making it suitable for very large datasets that cannot be queried in full.

REST API data source example configuration:

CODE

GET /api/customers?name=$userInput*

When the user types "Acme", the executed REST API request will be:

CODE

GET /api/customers?name=Acme*

An additional advantage of using $userInput in a REST API context is that most APIs return a limited number of options (e.g., 100). Filtering the results with $userInput is the only way to access specific values within large datasets efficiently.

Example: Local Jira data source

When using a Local Jira data source, $userInput can be injected into a JQL query to search issues dynamically.

This is especially useful when selecting issues from large Jira projects.

Example use case

You want a custom field that allows users to select an issue from the PROD project by typing part of the issue summary.

CODE

/search/jql?jql=project = PROD AND summary ~ '$userInput*'&fields=issuekey,summary

Executed request when the user types “login”:

CODE

/search/jql?jql=project = PROD AND summary ~ 'login*'&fields=issuekey,summary

In this example:

Results are filtered by issue summary as the user types
The wildcard (*) allows partial matches

This approach ensures that users can quickly find relevant issues without loading or scanning the entire project.

Min characters

This option appears as soon as your query or path includes a dependency on $userInput.

It allows you to define the minimum number of characters a user must type in the Connected field before a request is sent to the data source.

If the field is left empty, the default value is 0 (the request is triggered immediately).
If the value is greater than 0, the user will see a message in the Connected field:
“Please type at least <number> character(s).”
Once the required number of characters is entered, the data source call is triggered, and matching results are displayed.

Conclusion

By dynamically filtering options based on user input, you can enhance both usability and performance in Jira custom fields. Whether using SQL queries or REST APIs, this approach ensures that only relevant options are presented to the user, improving the overall experience.