JIRA 6.0 has user keys, should we be using user keys in JQL instead of usernames in 6.0?

So JIRA 6.0 and the corresponding milestones are now avaliable and JIRA has added in a 'key' field to Users (as well as introducing a ApplicationUser class). However, I was wondering how this affects JQL. So, if I make the following JQL query:

reporter = <what goes here>

In the empty space do I put a 'username' or a 'user key'?

1 answer

1 accepted

1 vote

The answer to this question (direct from the JIRA team) is: Nope - JQL will continue to use the username.

As I understand it, the gist of the change is that User keys are like id numbers: nobody should need to know what they are. End users of Atlassian products should only have to care about what they would call the user: which is the users 'username'.


This means that anything "user visible" will continue to use the users 'username' and never use the key. This includes JQL, User Pickers etc...

The key is actually the same as the username, until the username changes. So are the Atlassian team saying that JQL won't work for users with changed usernames? I'm sure that's not the case...

The key is actually the same as the username, until the username changes. So are the Atlassian team saying that JQL won't work for users with changed usernames? I'm sure that's not the case...

The idea is that the userkey is never exposed to the end-user, in the same way that we try not to expose (for example) the Version ID.

If you write JQL like "assignee = jamie", save this as a filter and then rename that user to "jechlin", then the filter will no longer work. (You would need to change it to "assignee = jechlin")

This is consistent with general JQL behaviour, because JQL mostly uses display names that can be changed over time.
e.g. "fixVersion = '3.0' and project = 'iFoo System' and assignee=jechlin@example.com"
would break if you change the name of the version, or the project, or the user's email address.

I think searching for userkey should be possible to make sure your filters won't break. For versions this is possible and a best practise:

It is safer to search by version ID than by version name

OK, that makes sense Mark. I don't think it's entirely the same though because a version ID is an inscrutable Long, whereas a user key looks identical to a user name. But again, my example of JQL is not a good one because as you say, other JQL clauses break if you change the display name of the thing you're querying on.

Suggest an answer

Log in or Sign up to answer
How to earn badges on the Atlassian Community

How to earn badges on the Atlassian Community

Badges are a great way to show off community activity, whether you’re a newbie or a Champion.

Learn more
Community showcase
Published Monday in Jira Software

How large do you think Jira Software can grow?

Hi Atlassian Community! My name is Shana, and I’m on the Jira Software team. One of the many reasons this Community exists is to connect you to others on similar product journeys or with comparabl...

619 views 6 12
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you