Thursday, December 23, 2010

Why can't I delete an issue?

That's a question that involves various levels of configuration in JIRA, but in this case has a nice, simple answer.

What does deleting a JIRA issue mean?

Deleting an issue in JIRA is permanent, making it almost as though the issue had never existed. This is usually only useful when you've created an issue by mistake or have been creating issues to test JIRA itself. After a deletion the only way you can usually tell that there used to be an issue is that there is a gap left in the issue keys, e.g. TEST-12, TEST-13, (missing issue), TEST-15. The missing issue TEST-14 may have been moved to another project, in which case JIRA will redirect to the new issue key. But if there is no helpful redirection then the issue was probably deleted.

Who can delete an issue?

The permission to delete an issue is named "Delete" in a permission scheme. For a given project check which permission scheme is being used and who has the Delete permission in that scheme. By default the permission is granted to a Project Role such as Administrators. Then check which user has that role for the project.

But I still can't delete any issues!

It's time to look deeper into the bowels of JIRA. Deleting an issue is a JIRA system issue operation, just like Linking or Moving an issue. These operations are controlled by a system plugin unsurprisingly named "Issue Operations Plugin". If you go to Admin, System, Plugins then it's there in the ridiculously long list of plugins. The Universal Plugin Manager hides these plugins by default. If an issue operation is disabled in the Issue Operations Plugin then it won't appear anywhere in JIRA at all. 

Summary: if you can't delete any issue in any project, it's probably because deleting has been disabled in the Issue Operations plugin.

Extra tip: new issue operations can be added to JIRA using a plugin and the Issue Operations Plugin Module.

Friday, November 19, 2010

JIRA as a Platform

The San Francisco Atlassian User Group met last night in the coolest place so far, PariSoMa. ParisSoMa is a "innovation loft" - imagine a shared loft with lots of tables, chairs and people to talk with. About a dozen people chatted about Atlassian tools and tools in general. Thanks to Atlassian for the beer and food!

I gave a short talk about using JIRA as a platform, where different groups can use JIRA without their changes affecting each other. The original slides are above and also available from here. A reformatted version of the notes is below.

JIRA as a Platform


JIRA often starts in one department and then spreads. Of course, each department often has different needs for JIRA. The question is how best to configure JIRA for separate uses. This post contains a worked example of one way to add a new department to JIRA without affecting other existing departments.


Using the combination of (project, issue type) in JIRA we can change:

- the active custom fields, and most system fields
- position of fields on the screen (1 column only)

and also

- Components
- Versions
- Permissions
- Notifications

However, there's not much documentation on how to do this in an organized manner.

Also, maintaining hundreds of custom fields in JIRA can become tedious. For example, a set of 20 related fields need to be added to the issues in a new project, but they were originally restricted by project. Now each field in turn has to be updated by hand.

Worked Example: Setting up a New Department

1. Create a new Project Category for the department, e.g. "Accounts". Some scheme names will get this word as a prefix.

2. Create a new issue type for that department's issues, e.g. "Invoice". Other scheme names will have this word as a prefix.

3. Create a test project, e.g. ACCTEST

Summary so far: ACCTEST is a project in the Accounts category and contains Invoice issues.

Basic Project Setup

  • Set the category for the test project to "Accounts"
  • Create a notification scheme named "Accounts Notification scheme", e.g. copy the default
  • Set the notification scheme for the project to "Accounts Notification scheme"
  • Create a permission scheme named "Accounts Permission scheme", e.g. copy the default
  • Set the permission scheme for the project to "Accounts Permission scheme"
  • Create a workflow scheme named "Accounts Workflow scheme" and configure it to use a copy of the default JIRA workflow
  • Set the workflow scheme for the project to "Accounts Workflow scheme"

Advanced Project Setup

We need to define the more complex schemes:

  • Issue Type Scheme
  • Field Configuration Scheme
  • Issue Type Screen Scheme, which uses a Screen Scheme

and to configure the ACCTEST project to use them.

As an aside, an Issue Security Scheme is only needed if you have some departments that are more private than others, e.g. Legal

1. Issue Type Scheme

An Issue Type Scheme controls which issue types can be used in a project.

Under Admin, Issue Types (middle tab) create a new Issue Type Scheme named "Accounts Issue Type Scheme"

Add the main issue type, .e.g "Invoice" as the default

Add other issue types, e.g. "Task", "Improvement" if they will be used by the new department

2. Field Configuration Scheme

A field configuration controls which fields are part of an issue type, e.g. what data is in an Invoice. Fields can be marked as Required, and Hidden fields are not shown as searchable.

Create a new Field Configuration named "Invoice Field Configuration"

Don't hide any fields here yet, use screens for that

Create a new Field Configuration scheme named "Accounts Field Configuration Scheme"

Configure the scheme to use the Invoice Field Configuration for Invoice issues

3a. Screen Schemes

Screens control whether a field appears in an issue, and also the order in which the fields appear. Screen Schemes choose which screen is used to Create, Edit or View an issue

Create a screen named "Invoice Edit Screen". This screen should have all the fields in the Accounting Issue issue type

Create a screen scheme named "Invoice Screen Scheme"

Configure the Create, Edit and View issue screens to be the same screen for now

Later on, copy the Edit screen to be a Create screen and remove fields not needed at creation time

3b. Issue Type Screen Scheme (ITSS)

An ITSS ensures that the right screens are used for each issue type.

Create an ITSS named "Accounts ITSS"

Configure the default screen scheme to be the "Invoice Screen Scheme" defined in the previous page

Adding a Custom Field

Adding a custom field is the real test of all this work. It's just as usual except:

  1. Restrict the custom field to just the issue types that use it, e.g. Invoice
  2. Don't restrict the custom field to a project
  3. Add the custom field to the Invoice Edit screen (and Invoice View screen and Invoice Create screen if defined)
  4. Don't add the field to any other screens at all
  5. Hide the field in the Invoice Field Configuration to stop it being searchable

You will likely need to select a project and issue type to have the searchable custom fields appear properly

Existing Schemes

Having a standard approach to creating schemes and issue types is all very well, but what about an existing instance of JIRA? The following ideas may help with the clean-up.

Document the existing system, ideally by talking with the original designer. Sometimes there was a vision, sometimes they were still learning how to use JIRA.

Change one department at a time to whatever approach you have settled on.


Users hate being surprised by new fields that they don't care about!

The key to using JIRA for many groups is to have a standard way of using JIRA schemes and issue types. And since JIRA schemes can get complicated, document what you did and why.

Occam's Razor comes into play here. Too few schemes and every change will have unexpected consequences. Too many and you'll lose track of how they differ.

Monday, November 8, 2010

Resolved, Resolution and Resolution Date

This week's jiradev post is one result of the Second Atlassian Doc Sprint last week. For two days over thirty people from many different groups in Atlassian and others from all over the world "scratched their itches" to add and update the Atlassian documentation. I'm looking forward to the next one sometime in 2011.

One area that sometimes confuses JIRA users and administrators is the difference between Resolved and Resolution. Many of the standard JIRA reporting gadgets expect the Resolution field to be set as described below or confusing results can occur.

Resolved is one of the issue statuses in the default JIRA workflow.
Resolution is a system field with values of Fixed, Not Fixed, etc. The Resolution field is usually set during transitions.
The Resolution Date system field is the latest date that the Resolution field was set to a value.


JIRA comes with a default workflow (Admin, Global Settings, Workflows) that has the following expected series of statuses for an issue:
Open to In Progress to Resolved to Closed
The idea is that a bug is created with a status of Open, and is then moved to In Progress and Resolved by the person who fixes it. The bug is then moved to Closed by someone who checks that it really was fixed. Resolved is just a name for an issue status - the status could as well be named "Believed Fixed" or "Ready for Testing".
The Resolved status has not connected directly with the Resolution field


It's a good idea to keep the number of statuses in your workflow as small as possible to make maintenance easier. So it makes sense to avoid having lots of statuses with names like:
  • "Closed and Fixed"
  • "Closed and Won't Fix"
  • "Closed because Duplicate"
The system field Resolution (Admin, Issue Settings, Resolutions) can be used to avoid this increase in the number of statuses. The default values of Fixed, Won't Fix, Duplicate, Incomplete and Cannot Reproduce cover many of the reasons a bug could be closed.
The intended use of Resolution is that when a bug is created the field is empty, with no value. This is shown in an issue as a value of "Unresolved". When an issue is moved to another state such as Resolved or Closed, the Resolve Issue Screen is shown during the transition and this screen has the Resolution field on it. So a bug can have its Resolution set to Fixed while it moving to the Resolved state.
Tip: in a standard JIRA installation, the Resolve Issue Screen is the only screen where you can set the Resolution field for an issue, and this screen is only used for transitions to the Resolved and Closed statuses.
Once the Resolution has been set, the issue is considered "resolved" by JIRA, even if the status of the issue is not the Resolved status.
The only way to remove the resolution from an issue in a standard JIRA installation is to Reopen an issue. You can add the Resolution field to the Default Screen to make it easier to change the value, but a transition is still required to reset the resolution to empty.

Resolution Date

The system custom field Resolution Date is the latest date for a given issue that any value was set in the system Resolution field. As noted in JRA-20286 with the default JIRA workflow, changing the issue status from Resolved to Closed will change the resolution date. The Resolution Date will only be empty if there is no value at all in the Resolution field.
The Resolution Date is confusingly named "Resolved" in the list of Issue Navigator columns.

Other Approaches

Many organizations using JIRA don't use the Resolution field because
  • It's hard to reset the value to empty for "unresolved"
  • It doesn't appear on standard screens, just during transitions
  • It's hard to make it required on custom transition screens
Instead they base their reporting only on the name of the statuses in the workflow. They may also create their own custom select field named "Our Resolution" or "Sub-status" with values such as Unresolved, Fixed, Won't Fix, Duplicate, Incomplete and Cannot Reproduce.
-Avoids confusion of the words Resolved and Resolution
-Works well with custom workflows since there is no need to add post-functions to set the system Resolution field for new transitions
-The standard JIRA reporting gadgets are no longer as useful
Don't add a resolution named "Unresolved" to your the system Resolution field because the issue will still be treated as resolved by the standard JIRA gadgets, since it has a value.

Friday, October 29, 2010

JIRA book news

Last month I posted an article about why I wasn't writing a book about JIRA. Now Packt publishing is working on one and have asked me to be a technical reviewer for it.  Nothing is certain until a book is printed (probably next year) but this is good progress.


Tuesday, October 12, 2010


Summary: how to get Atlassian's attention effectively.

If you were an Atlassian Product Manager, what would get your attention? Obviously show-stopping issues such as the security problems earlier this year are going to stop you cold. But after that, what to do first with your limited time and small, only-human team? You've got literally thousands of issues to choose from.

There's no need to keep guessing because Atlassian publish an official "how we choose what to work on" guide. Here's my take on what it says:
  • We use JIRA and Confluence to track issues and we expect you to also
  • No roadmaps (they change too often)
  • Votes do matter
  • Feature Requests are not Bugs, and are not treated the same way
and finally "We schedule features based on a variety of factors", which I take to include "the importance of your request depends on more than just how irritated you were when you submitted it".

Failed Approaches
  • Angry rants: "this issue has dozens of votes, so you obviously don't care about your customers, I hate you all!"
  • Unfounded estimates: "this is so simple, it should only take you an hour or two"
  • Snarky "Happy Birthday" comments in an issue
I think I've tried all of these in the past five years. None of them worked very well.

Better Approaches
  • Good bugs - define action (what did you do), expectation (what should have happened) and observation (what actually happened)
  • Crisp and concise communication, because vagueness or wordiness makes it look like you don't care
  • Pointing out how your request fits in so nicely with the rest of the Atlassian products
  • Talking to Atlassians about the request at AtlasCamp, AtlasSummit and Atlassian User Groups
Open Questions
  • Does an existing implementation help or hinder your request? It can live on as a workaround, or it could provide a working specification for Atlassian. There's probably no definite answer to this.

Disclaimer: The author, Matt Doar, is an Atlassian Partner with no secret access to Atlassian product managers.

Tuesday, October 5, 2010

JIRA Levels of Change

Summary: the different levels of changes to JIRA for plugins are listed

A few months ago Vincent Thoulé of Minyaa and I were discussing the different kinds of changes we've done to JIRA. We came up with the following list different levels of changes.


0. Client side install, no JIRA restart required, e.g. a JIRA CLI
1. One plugin jar file, no JIRA restart required - mostly not possible yet but can happen for groovy scripts
2. One plugin jar files and JIRA restart required - the common case
3. One plugin jar file, some custom jsp files, JIRA restart required
4. One plugin jar file, modified system jsp, vm or XML files, JIRA restart required
5. One plugin jar file, modified system files with possible recompilation, JIRA restart required
6. More than one plugin jar file, new language installation required, first-born child required.

No classification is perfect, but some are more useful than others. It would great to have each of the public plugins for JIRA fall into one of these categories, to help give a sense of what you're in for if you try to get it running.

What do you think?

JIRA Versions




Monday, September 27, 2010

Storing data in JIRA properties tables

Summary: store your own data in existing JIRA tables using the same classes that JIRA uses.

One of the most common questions when adding new functionality to JIRA is "where do I store my own configuration data?". The brute-force way is to add new tables or new columns to the database by modifying entityde fs/entitymode.xml, but then your future upgrades will need the same changes.

A better approach that's easier to maintain is to store your data where JIRA stores this sort of data itself, the propertyentry table. This also has the advantage of using the same classes that JIRA uses for accessing the data.

The propertyentry table is documented in the JIRA database schema as being where JIRA stores the user information, but JIRA also stores its own licenses and other configuration values in this table.

The way that JIRA uses the propertyentry table is based on the PropertySet interface from OpenSymphony. This interface lets you store unique "key=value" pairs with various get and set methods.

Let's take a look at the propertyentry table and its fields.

mysql> describe propertyentry;
| Field        | Type          |
| ID           | decimal(18,0) |
| ENTITY_NAME  | varchar(255)  |
| ENTITY_ID    | decimal(18,0) |
| PROPERTY_KEY | varchar(255)  |
| propertytype | decimal(9,0)  |

The documentation is a bit terse about what each of these fields is for: "each property has a record in the propertyentry table specifying its name and type, and a record in one of propertystring, propertydecimal, propertydate, propertytext, propert ydata or propertynumber, depending on the type."

In more detail, the purposes of each of the fields in the propertyentry table are:
  • ID - a unique identifier for every piece of data
  • ENTITY_NAME - class name of the data object
  • ENTITY_ID - identifies an instance of the data object
  • PROPERTY_KEY - the key of the key=value pair
  • propertytype - the data type of the value, e.g. 5 for a string
For each propertytype the corresponding table for the data value is:

1  propertynumber
5  propertystring
6  propertytext
One Example

Let's say I want to store two street addresses. In XML they might look something like this:

<address id="10010" housenumber="10" street="Oak Avenue" city="San Jose">
<address id="10200" housenumber="32" street="Long Street" city="London">
In the propertyentry table they would look like this


100 Address      10010      House_Number    5
101 Address      10010      Street          5
102 Address      10010      City            5

103 Address      10200      House_Number    5
104 Address      10200      Street          5
105 Address      10200      City            5
First, the ID is a unique identifier for every piece of data in this database.

Then the entity name "Address" is the kind of data we want to store. In an Object Relational Model (ORM) this is the class name of the object being stored.

Then comes the entity id to used distinguish multiple addresses. In ORM this is a unique identifier for each instance of an object.

Then property_key contains the name of a data field within each address. This is the "key" of the "key=value" pair that is being stored.

There's one last field in the propertyentry table - propertytype. The most common value is 5, which means that the value is a string stored in the propertystring table. 1 is for boolean settings such as enabling or disabling voting and its value is stored in the propertynumber table. 6 is for blocks of text such as the license data and is in propertytext.

The values in propertystring for our example are:


100  10
101  Oak Avenue
102  San Jose

103  32
104  Long Street
105  London

Accessing the Data

We first have to create a PropertySet object propertySet that knows how to refer to just one address, say the first one with has an entity id value of 10010.

This can be done with code such as

private static PropertySet getPS() {
        if (ofbizPs == null) {
            HashMap ofbizArgs = new HashMap();
            ofbizArgs.put("", "default");
            ofbizArgs.put("entityName", "Address");
            ofbizArgs.put("entityId", new Long(10010));
            ofbizPs = PropertySetManager.getInstance("ofbiz", ofbizArgs);
        return ofbizPs;
Then we can use that to call

propertySet.setString("Street", "Pine Avenue");
to update the row in propertystring so that it looks like

101  Pine Avenue
A similar method can be used to get the data:

String currentStreet = propertySet.getString("Street");

More Examples

User Properties are stored with a property key prefixed by "jira.meta.". So if you store a property "hair_color=brown", you will see an entry for the user with id 10000 in propertyentry such as

mysql> select * from propertyentry where property_key like 'jira.meta%';
| ID    | ENTITY_NAME | ENTITY_ID | PROPERTY_KEY          | propertytype |
| 10111 | OSUser      |     10000 | jira.meta.hair_color  |            5 | 

and an entry in propertystring such as

mysql> select * from propertystring where id=10111;
| ID    | propertyvalue |
| 10111 | brown         | 


The JIRA Create and Link plugin stores its configuration as an XML string in the propertyentry table and is an example of storing general data for a plugin. The class that does this in a generalized way is

JIRA Versions



The "User Details" section of the [Issue Fields|] part of the database schema documentation is more helpful after reviewing the example in this article.

Wednesday, September 22, 2010

JIRA Groups and JIRA Project Roles

Summary: JIRA groups are made up of JIRA users and can only be changed by JIRA administrators. JIRA project roles are made up of JIRA users and JIRA groups and can be changed per project by project administrators.

The difference between groups and project roles seems to confuse many JIRA administrators. This article explains the differences and what each one is good for. Up until a few years ago JIRA had users and groups of users, but no project roles. Groups were pretty powerful - wherever you could do something with a user, you could probably use a group instead.

For instance, if you wanted to allow a user John.Smith to change the reporter field in your issues, you could

1. Create a new permission scheme named something like "John.Smith can change reporter"
2. Add the John.Smith user to the appropriate Modify Reporter permission entry in the new permission scheme
3. Change the appropriate projects to use the new permission scheme

You could also do the same thing with a group

1. Define a new JIRA group "Can Modify Reporters"
2. Add the user John.Smith to the new group
3. Create a new permission scheme named something like "My new group can change reporter"
4. Add the group (instead of the user) to the appropriate Modify Reporter permission entry in the new permission scheme.
5. Change the appropriate projects to use the new permission scheme

All good so far, but there are two main problems with groups: scaling and updating


If I want John.Smith to be able to edit the reporter in some of my projects, and also allow a different user Jane.Bloggs do the same in some other projects, then I have to create two permission schemes, one for each user. If I then decide that they are both allowed to edit the reporter in some shared projects, then I need a third permission scheme. With lots of users this leads to an explosion in the number of permission schemes (or any other JIRA scheme that supports groups). Keeping track of the difference between each of these schemes is tedious and error-prone, even with the scheme comparison tools.


Only JIRA administrators can change the membership of groups, which means extra work for them that could be better handled by JIRA project leads.

Project Roles

What was needed was another level of indirection and that's what exactly JIRA project roles are. Every JIRA project has three default project roles - Administrators, Developers and Users. The default roles can be changed, but for now let's stick with those three. For each role in every project, you can define who plays that role by adding a user or a group to the role.
Viewing a project's roles

A project's default roles

Once you've chosen who plays each role for each project, we can use the roles in our schemes. For instance, when you look at a permission scheme, you'll see that all of the permissions are granted to project roles, not to users or groups. The key thing about roles is that they can be changed per project by people who aren't JIRA administrators.

Creating a New Role

Another way to understand what's going on here is to create a new role. Let's say for some reason we want to allow a Technical Publications user assigned to each project to modify the reporter of an issue.

The default permission scheme allows users in the Administrator role for a project to modify the reporter of an issue. We don't want to allow tech pubs to administer the project, just give them that one specific permission.

We can create a new role "Technical Publications" in Admin, "Users, Groups & Roles", Project Role Browser. We can also add our Tech Pubs lead Bobby.Jo as a default member of the new role so that she will be in the Tech Pubs role for all projects by default.

Adding the new "Technical Publications" project role

Now every JIRA project has this new role. We can add the appropriate tech pubs user (or group) to the Tech Pubs role for each project. Once the users for this role have been added, we can edit the permission scheme and add the Tech Publications role to the Modify Reporter permission entry. The permission scheme now checks which users are in the role for each project, rather than looking at a fixed list of users or groups of users.

If the tech pubs person changes for the project, then the people with the project Administrator role can change the members of the Technical Publications role for their project. And there is no need to ask the JIRA administrator to make the changes.

Should I use a group or a project role?

If you want to refer to the same set of users across multiple projects, use a group. If you want to refer to a set of users that is different per project, use a role.

JIRA Versions



Signs that a new version of JIRA is imminent

Atlassian is a more open company than most and they're also smart enough not to provide release dates and then have to change them later on. Atlassian partners usually get a week's notice that the next release is coming up, but I have my own set of signs. Once all these have happened, the next JIRA release is imminent.

  • Cut and paste text appears from Atlassian PM in a few issues with lots of votes,  explaining why each issue is not going to be fixed in the near future.
  • A larger number of other issues were recently resolved (use the Resolution Time chart with a filter for the next version)
  • The most reliable indicator seems to be when the upgrade documentation changes.

Based on these inputs, I expect to see JIRA 4.2 before the end of this month, certainly before AtlasCamp in mid-October when some of the key JIRA developers might be out of the office for a few days.


Wednesday, September 15, 2010

Older articles about JIRA

I run a separate blog for my company Consulting Toolsmiths where I 've published various articles related to JIRA over the past three years. Future JIRA articles will appear on this blog instead, but some of the more technical other ones include:

All posts labeled with JIRA are here.


Why isn't there a JIRA book?

People occasionally ask me why I haven't written a book about JIRA. I wrote Practical Development Environments for O'Reilly a few years ago and enjoyed doing so. I have lots of ideas for what would make a good book about JIRA. So what's the problem? Well, here's the gist of a reply I sent to a publisher recently:
I'd love to write that book! My problem is that I don't want to spend a year working 8pm to 2am for minimal pay.  That's horribly destructive to family life. Nowadays I'm in a consulting position where I could probably do it as a day job in around 6 months, but who's going to pay me to do that? Atlassian might consider it taking it on as marketing expense but my understanding is that what it would cost them is far larger than what they might ever expect to make.
My sense is that technical books are created because their authors felt "it just needed doing" or "because it's there", but not for rational financial reasons. Yet if this blog ends up containing a useful number of articles I wouldn't object to publishing them as a book.

Who's using your JIRA?

Sometimes it's interesting to see who is actually using a JIRA instance. The Participants field in the JIRA Toolkit is a custom field that shows the issues that you've reported, are assigned to, or have commented on. The useful thing is that you can create an Issue Statistics gadget to summarise the participants by user name.
  1. Create a filter to select the issues to be examined. This could be all issues, or just a few select projects
  2. Create an Issue Statistics gadget on a dashboard
  3. Select the Participants field for Statistic Type
  4. Select Total for Sort By
  5. Select Descending for Sort Direction
  6. Select Yes for Show Resolved Issue Statistics
  7. Select Never for Refresh Interval
You should get a list of users as in the screenshot below.

Last year I posted a summary of who had reported issues with JIRA using only the Reporters field. This time I looked at who were the participants in JIRA issues in the past year. As expected most participants in JIRA issues work for Atlassian. Neal Applebaum and Sergiy Lizenko (ILS-Ukraine) are still the most active and I still come in a distant third. Greg Brauer of DreamWorks is the newest user in the list.

Write what you want to read

This blog contains articles about JIRA, the issue tracker from Atlassian. Most of the articles are technical in nature. If you have an article you would like to see appear here, please submit it to the editor, Matt Doar.