If you have an issue TEST-1234, then that whole thing is called the issue key
The project key is TEST and the issue number is 1234
A project with the project key TEST also has a project name, which is something longer such as "Testing project for the Test Team"
Right, now let's correct some things that developers might assume when they try to integrate with Jira.
Not so. Project names are really easy for a Jira administrator to change, they're just a bit of text.
And Jira administrators can also change those short project keys.
So TEST-1234 might one day become QA-1234
The issue number part won't change, and the Jira UI will nicely redirect you to the new issue key.
But don't assume that a project key will never change.
This is even less true than the previous thing that wasn't true.
Issue keys change all the time when users move issues from one project to another.
If I move TEST-1234 into the ENG project, then it will change both its project key and issue number.
It could become something like ENG-2345, with a totally unrelated issue number
The Jira UI will still redirect you to the new issue key, so this isn't usually a problem.
Every Jira issue does have an underlying issue id that never changes, and it is just an integer.
You don't really need to use the issue id though, because the redirection to the new issue key just works.
Sadly, this is rarely true. Jira workflows are made up of statuses, with status names such as "To Do", "In Progress" and "Done".
A specific Jira issue's workflow depends on the Jira project that it is currently in, and the issue type. Issue types have names like "Bug" and "Feature".
Just because a Bug in one Jira project has a status named "Done", this doesn't mean that a Bug in a different Jira project will ever have that status too.
To add to the fun, Jira administrators can create new statuses. One day I saw a status named "Done Done", which made me laugh.
Sometimes what one person thinks is an obvious meaning for a status name is not always shared by someone else.
For example, "In Review". Is that for before the work is done, or for after the work has been done? That depends on where someone has put it in the workflow.
Options are the values in Jira drop-down fields. A drop-down field has a set of options that people can choose from.
The same custom field can have a different set of options depending on which Jira project an issue is in.
The option names can change, but their option ids will stay the same
Would that that were true. To add a field to a Jira project, you have to find the particular Jira screen that an issue is using.
Which screen that is depends on both the project and on the issue type.
So, the follow-up question is always "which issue types should the field be added to?"
The next hassle is when a screen is used by many issue types in a project.
For example, if a screen is shared by Bug issues and Task issues, and you want to add a field just for Bug issues, then the administrator has to create a copy of the screen, add the field to the copy, and configure the project to use the new screen for Bugs. Phew!
Well, perhaps. I blame the English language for some of the confusion in this case.
People ask for a "new custom field", but often really mean "an existing field that will be new to our project".
The performance of Jira is directly related to the number of custom fields that have been added. So we can't just create them willy-nilly.
That means that if you are asking for a "brand new to Jira custom field", then the questions from your Jira administrators will get more detailed. For example:
'Will this new field be useful in other projects?"
"Do you need to write reports based on this field, or can you store the data in a different field?"
"What makes you so special?"
You'd think so, but that is not in fact the case
And in various places in the Jira UI, you can end up seeing multiple choices with the same name, which is confusing
When you are looking up a Jira custom field in code, use the unique custom field id instead of the name.
Oh, yes there are! Jira keeps track of the history of an issue in the History tab. Almost every change creates an entry there.
After some thousands of edits, the issue will take a long time to load. Eventually it won't load at all.
This is usually only a problem when scripts are editing the issue.
After all, how many times are real people going to edit an issue by hand? Wait, I know some people who might do that. But only a few.
Now we're getting silly. Of course there are limits. Everything has limits.
The question is whether Jira checks for them or not.
Attachment size? That's checked. But number of attachments? Not checked. So that's an obvious safety gap.
Size of text fields? Checked now, but didn't used to be
Number of comments? Not checked. And adding lots of comments will cause problems somewhere down the line. We're just not totally sure where.
The list goes on, but the most common one I see is not knowing that the Summary field is limited to 255 characters.
Actually, it is spelled "Jira".
Atlassian renamed the product from JIRA to Jira a few years ago.
That seems like an odd change to me, but I guess that's why I'm not in marketing.
What other assumptions and erroneous beliefs about Jira have I missed out? Send them to me and if I get enough I'll write another article.
Matt Doar
Head Toolsmith
Adaptavist
San Jose, CA
71 accepted answers
11 comments