How to count multiple values in a histogram?

If I have a JIRA issue with a field that can have more than one value, how should a report count the values in all the issues? For example, issue TEST-1 has the values "Alice" and "Bob" in the field, and issue TEST-2 has the values "Bob" and "Charlie". Do the counts look like this:

Alice - 1
Bob - 2
Charlie - 1

or this:

"Alice, Bob" 1
"Bob, Charlie" 1

JIRA 4.3 and earlier chose the first way for custom multiselect fields. JIRA 4.4 and later have changed it to the second way (accidentally?) and some people are not impressed. I think that the first way seems more like a natural combination of the histograms of the different values.

Note that since JIRA enforces an order for all the options for a custom multiselect field we don't have to deal with the theoretical question of whether ["Alice", "Bob"] is the same as ["Bob", "Alice"].

Theoretical Administration Simplification

Any tool such as JIRA has many ways to control who can do what with it. For example, JIRA has permission, issue type, field configuration and all its other schemes. The number of dimensions of control has at least two consequences - performance and maintenance.

Performance - every piece of information that is shown to a user has to check that it is in fact supposed to be seen

Maintenance - how to define the permissions in a coherent manner, and then how to make them easy to maintain over time and by different people.

I can imagine solutions for the first consequence, since however the constraints are defined they can be converted to data structures that are reasonably efficient for each kind of checking. Not easy, but doable. But I think handling with the second problem is even harder.

For example, JIRA groups these permissions in one way but someone will always want to group them in another totally-unexpected way. How can that be made easier for everyone is not at all clear to me.

I've seen a massive permission matrix (ExtraView) but that was hard to comprehend. Whatever approach is used, a record of changes and differences between two points in time is also necessary for future maintainers.

Moving Custom Fields in JIRA Plugins

How can you change where a custom field type comes from in JIRA?

JIRA custom field types are defined in JIRA plugins, and are uniquely identified by their plugin key and field key. For instance if a plugin has a groupId "com.mycompany.jira.plugins" and an artifactId "myplugin", then (by default) the plugin key is "com.mycompany.jira.plugins.myplugin". A field key is something like "mycustomfield".

If I install such a plugin and create a custom field using the new custom field type, then what happens if I want to deploy the custom field type in a different plugin? I can see three choices:

1. Keep the same plugin key and field key - rather limiting

2. Create the custom field type in the new plugin, create a new custom field and migrate all the data from the old field to the new field. Then remove the old plugin.

3. Change the key of the custom field in the database.

The last option is probably the neatest in the long term, but it's an ugly way to have to administer a tool such as JIRA.

Does anyone have any better ideas? I suppose I could write a plugin that updates the database directly. What I'd really like is a way to have aliases for a custom field's type so that it could change over time.

Sort order of select lists in JIRA

I had an "surely I already knew that?" moment the other day. My select list custom field had values A, B and C. I changed the order in the configuration screen to be A, C and B. Yet when I displayed the field in the Issue Navigator list of issues and sorted by it, the issues were sorted alphabetically, not at all how I had configured.

It turns out there's a long-standing bug about this that needs some of your voting love: JRA-14161
Until it's resolved, you have to add a prefix to make the values sort the way you them to, e.g.

01 My First Value
02 Another Value

I can see what the underlying problem is - field contexts. A custom field in JIRA can have contexts associated with it, where a context is project and issuetype. Then you can have different sets of options per context for the same field., e.g.

My Custom Field

Project A, Issue Type T1, options A, B, C
Project A, Issue Type T2, options Z, Y, C

The problem is that there is no sort order defined between these two sets of options. And just because option C occurs in both sets doesn't mean that they would be sorted together since the order is defined per context too. Tricky.

~Matt

Adding components to JIRA automatically with a script

Both the SOAP or REST APIs for JIRA are missing a method to add a component to a JIRA project. The shell script below calls the appropriate URL to do this. File under "ugly but effective", and thanks to Justin for his handy post.

~Matt


#
# Add components to a JIRA project.
#
# The parameters to the URL are encoded by passing them with -d


USERNAME=admin
PASSWORD=admin
SERVER_URL="http://jira.example.com:8080"
# Set this to the project you want to add components to
projectid=10001


DASHBOARD_PAGE_URL=$SERVER_URL/secure/Dashboard.jspa
COOKIE_FILE_LOCATION=jiracoookie


# Get the authentication cookie
curl -u $USERNAME:$PASSWORD --cookie-jar $COOKIE_FILE_LOCATION -sS --output /dev/null $DASHBOARD_PAGE_URL


for component in "Able Baker Charlie" "Lowly Work" "Huckle Cat"; do
  echo "Adding component: $component"
  curl --cookie $COOKIE_FILE_LOCATION --header "X-Atlassian-Token: no-check" -sS --output /dev/null -d "name=$component" -d "pid=$projectid" "$SERVER_URL/secure/project/AddComponent.jspa"
done


rm $COOKIE_FILE_LOCATION

Oldest Active JIRA?

I've just seen an instance of JIRA 3.12 running happily on a public site. Does anyone know of even older versions?  I'd suggest obfuscating the URL a bit because there are a number of vulnerabilities in those old releases.

~Matt

No Need To Restart JIRA

Atlassian Summit has come and gone, and was a lot of fun. My book was well received, so I'm happy. Something else makes me very happy is the release of JIRA 4.4. Beta1 because now all JIRA plugins can be reloaded without restarting JIRA.

It's a simple thing but it used to suck so much time during plugin development. This time I was creating a new Active Objects plugin, so installed it as usual for a JIRA plugin. Then I rebuilt it and uploaded it from the JIRA plugin manager. Three clicks later the updated plugin was installed and working.

Hurrah!

~Matt

More JIRA book news

The breaking news is that I just signed an agreement with O'Reilly to produce another book. The working title is "Practical JIRA Development" and the scope is JIRA administration and plugin development, just like this blog.

It's part of O'Reilly's push towards realtime publishing so it will be sweet and short. As Mike Loukides noted:

"We're looking for manuscripts that are roughly 30-70 print pages long"

The book will be written in DocBook and committed to a repository with automated builds of the book. Nice and agile!

JIRA Workflow Common Transitions

This post was written by Pat Callahan who describes his current position at Hara Software as "a little of this... a little of that", and some of that involves digging into JIRA.

Do you have something JIRA-related that you would like to write about? Or a topic you want see an article about? If so please contact me at mdoar@pobox.com.


Common Transitions

JIRA workflows can have common transitions, which are transitions that are defined once but used from multiple statuses. The default JIRA workflow contains one common transition: Close. If you change it in one place then all the other places it is used are also changed. JIRA displays the names of such transitions in italics.

JIRA does not provide a way to define new common transitions. You can vote for that feature, but until then the only way is to edit the workflow XML directly.

What's so great about common transitions?

If you have a transition you need to create which is accessible from multiple points in your workflow, you could end up creating multiple duplicate instances of that transition, all of which are different.

This quickly becomes a nightmare if you are setting up post functions or other sorts of validations in that transition because you'll need to edit the transition in multiple spots.

How to Create Common Transitions

It's not hard but you will need a decent text editor and a rudimentary understanding of XML, or even HTML.

Step 1: download the workflow you want to fix from the workflows page (Admin, Workflows) and open it in your editor.

Take a moment and look at the file. You'll see the XML has several sections up at the top. One key section to call out is the "common actions" section. The tag is <common-actions>. In there, you'll see some sections like this: <action id="2" name="Close Issue" view="fieldscreen">. This one represents the "Close Issue" transition and will show up in the UI in Italics because it is in the "common actions" section. Naturally that XML tag is only the opening tag, so you'll need to have the closing tag too, which looks like this </action>. You should also note that this has an "id" value in the action tag. For "Close Issue" the ID is "2" in this example.

So now that we know "Close Issue" is a common action, you can scroll down through the XML to find an instance where it is used. Look for the section <steps> and you'll see something like this:

<step id="4" name="Resolved">
      <meta name="jira.status.id">5</meta>
      <actions>
        <common-action id="2" />
    ...

What this shows you with the last line is that in the "Resolved" step, there is going to be a close button. To do it, it's just referencing the common action for "Close Issue" by using the ID for it, e.g. <common-action id="2" />

Tip: JIRA's built-in IDs tend to be lower digits than ones created after JIRA installation, which tend to be in the 700's or 800's. Here's an example from one of my workflows:

<action id="751" name="To Review" view="fieldscreen">

Common transitions are created in the "Common Actions" area of the XML file and they are later referenced in each workflow step. That's how you can simplify your workflows so that when you edit one transition that is shared across the workflow, it changes everywhere. You just need to edit the XML and move at least one instance of your transition into the common actions section, and then put in a new reference to it in each workflow step.

Let's walk through that last paragraph.

Step 2: Find the action you want to move within the workflow step and move it to the common actions section.

For my example, I am looking for an action called "Send To Test" so I can move it into a Common Action.

<step id="4" name="Resolved">
      <meta name="jira.status.id">5</meta>
      <actions>
        <common-action id="2" />
        <common-action id="3" />
      <action id="781" name="Send To Test" view="fieldscreen">

Aha! The last line indicates which chunk of XML I need to move into common actions. Above it, you can already see other common actions referenced (ids 2 and 3 are for "close" and "reopen" in my workflow).

Cut the entire "action" tag, making sure to catch the closing tag as well. Move it into the Common Actions section at the top of the file. I wouldn't bother updating the ID because you won't be sure if any of those IDs are used in other JIRA workflows, so don't change it. Put it at the end of the Common Actions section just before the </common-actions> tag.

Step 3. Add the reference to your new common actions in the workflow step where you removed the transition. For me, it looks like this::

<common-action id="2" />
  <common-action id="3" />
  <common-action id="781" />  

You'll need to put this reference into any workflow step that needs it.

Save the file and upload the XML back to JIRA and you are done!

Acknowledgements

Neal Applebaum was an early contributor to how to do this on the JIRA Forums.

Starting JIRA automatically with FreeBSD

JIRA runs not only on Windows, OSX and Linux but also on FreeBSD. There are some unofficial installation steps which don't differ that much from the official Linux installation documentation.

This post describes how to make JIRA start automatically after a restart. But after starting it I realized that I can not only edit but also add pages to the Atlassian documentation (and so can you). So I did and the result is Starting JIRA Standalone automatically on FreeBSD.

What's a "metatracker"?

There's an updated Python document about how the Python development team should triage issues. While every team does this differently, it's interesting to compare concepts in another system to the same ideas in JIRA. There's also a reference to a "meta tracker", defined as "the tracker about the issue tracker". I suppose the canonical example of a meta tracker is the Atlassian JIRA instance at http://jira.atlassian.com/browse/JRA.

It's a useful word for me because I often end up having to create a JIRA project or component for clients for tracking the changes they want to make to JIRA. Now I can refer to it as the metatracker and say things like "the tracker is the meta tracker". Just not with a straight face.

~Matt

p.s. The technical review work on the upcoming JIRA book is proceeding nicely, but I've heard no news on a release date yet.

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.

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

Summary

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.

Overview

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.


Conclusion

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.

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.

~Matt

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.

Summary 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.

Resolved

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

Resolution

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.

Also see How to Clear the Resolution Field

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.

Pros:
-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

Cons:
-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.

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.

~Matt

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.