Jira Data Center: How to change the user mention delimiter
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
When using the user search in Jira against a user's Display Name that is enclosed in non-space characters, it can be difficult to find the correct user consistently.
Since the user has a unique display name format, this can affect the effectiveness of searching for and mentioning the user.
Environment
Any Jira application where users have complex display names and where poor user searches have been identified due to names being enclosed in non-space characters.
Diagnosis
Find a project where the user can be assigned or mentioned and who has more than two words in the display name or is delimited by another character other than a space.
Examples of problematic user Display Names:
Atlassian Jira UserHello ATLASSIAN (사용자)
Try to search in the assignee field for this user by at least a third part of their display name, for example
Useror사용자.
Cause
We expect the user to be included in the returned list, but the expected user is not there.
Jira typically splits the display name into parts using a space character as a separator. However, in the previous examples, a different delimiting character is required.
How we search for text in Jira user searches
The conditions to search a user via this delimiter are based on rules Jira sets to parse the user value.
There are three rules:
The user's username starts with the search text,
The user's display name starts with the search text,
The user's display name contains the delimiter and the search text.
Solution
The suggested workaround is only available from Jira 8.19 and above. The resolved bug that created this property can be viewed here: JSWSERVER-21109 - Trying to search for mention or assignee in some cases doesn't return correct results.
⚠️ If you are using Jira 8.19 or earlier, you will need to upgrade to a newer version of Jira and apply this workaround. Check out our great Upgrade Checklist for your appropriate target version of Jira.
Since 8.19, we have introduced a new Jira property for administrators to specify:
com.atlassian.jira.bc.user.search.display.name.separator
You can add this property in several ways:
As a JVM property via setenv.sh/.bat,
the Windows Service,
and the jira-config.properties file.
The default settings (without mentioning the flag) are -Dcom.atlassian.jira.bc.user.search.display.name.separator=" ".
The value in the parenthesis is a space character, allowing search text to be searched by a space separator in their Display Name.
Example
When declaring this system property manually, for example, to -Dcom.atlassian.jira.bc.user.search.display.name.separator="-", you can change how Jira's user search navigates values when looking for a user.
In this example, if the separator is set to - the search text is John and the display name:
JohnDoe-Engineeringwill be matched as it starts with theJohnDoe-JohnENGINEER-ID10001andDoe-ENGINEERING-JohnID10001will be matched as both contain-John
Was this helpful?