Adding a Bespoke Work Item in Jazz Team Server

UPDATE: I've had a chat with IBM about some of the areas in this post. I've cleaned this up as a result.

I've been using IBM's Jazz Team Server 1.0.1 recently. Most of my time has been setting it up for a new project where the client wants to use the Work Item Functionality to log incidents. We're using the Scrum process configuration and the default Work Items which come with this did not meet their requirements - not that is without us ending up removing functionality from the "Task" and "Bug" Work Items which we wanted to also use internally for development.

Consequently, it was necessary to create a new Work Item: "Incident". This would allow us to specify the fields, presetation and workflow for the three sub-types of incident we needed, without altering anything else which came out of the box which we would need elsewhere.

Now, there is already some existing documentation on how to create a new Work Item,with associated presentation and workflow but after following this, I have realised some subtleties which I will highlight.

The Work Item and Enumerations

Firstly, you should create your enumerations. To aviod namespace clashes, try and use the same conventions as IBM (prefixing ID's with "com.mycompany.team.workitem." is generally how this is done, but not universally). In my case I created four new enumerations:

com.mycompany.team.workitem.enumeration.incidentPriority

com.mycompany.team.workitem.enumeration.incidentImpact

com.mycompany.team.workitem.enumeration.incidentEnvironment

com.mycompany.team.workitem.enumeration.incidentSource

Then I created the new Work Item Type Category:

com.mycompany.team.workitem.workItemType.incident

Next I added the types of incident which could occur:

ID: incident-failure-defect, Name: Failure - Defect

ID: incident-failure-bug, Name: Failure - Bug

ID: incident-service-request , Name: Service Request

Then, making sure the editor was showing my new type, I added the four enumerations as Custom Attributes.

ID: incidentPriority-n, Name: Priority-n

ID: incidentImpact-n, Name: Impact-n

ID: incidentEnvironment-n, Name: Environment-n

ID: indicentSource-n, Name: Source-n

Why the Italics? Why the Funny Names?

RTC does not allow you to remove attributes once you've created them, even if you got it wrong. This is because you might have created the custom attribute, then created work items using it, and then subsequently made a change. To preserve these old work items, you cannot create another custom attribute with the same ID. This means you need to make sure you get things right.

If you do make a mistake, just bite the bullet, all is not lost. Remove the incorrectly added custom attribute and then add it again in the right place. Make sure that you use a distinct ID (I got into the habit of appending a "-#" on the end) and do the same to it's Name. This will allow you to distinguish between the multiple choices when adding it to a presentation. Once you have added it, you will see the slightly offputting Name with "-#" appended. To remove this, go back to the custom attribute, and edit it to remove this. All will then be well.

NOTE: IBM are aware of this pecadillo and in release 2.0 they will display the Name and the ID in the drop downs. Cool.

Creating the Presentation Elements and Binding to the Work Items

Now you are ready to add the presentation. I tended to take a "Test A Lot" approach to this, just to make sure I wasn't getting myself messed up. In my case I followed the default editor very closely, with the same tabs end presentations, save for a different "Details" section in the Overview Tab.

Firstly I created the presentation:

com.mycompany.team.workitem.editor.incident

Then I created an Overview Tab:

com.mycompany.team.workitem.tab.incidentOverview

And a new Section for the Incident Details:

com.mycompany.team.workitem.section.incidentDetails

Then I added the first presentation:

com.mycompany.team.workitem.presentation.incidentType

Once this was done I swapped out to the bindings page and bound my three new work items to this new presentation, saved, and pressed CTRL-Shift-N. This allowed me to check that when I created a new Service Request, that the screen was building up as I expected. I did this after each new Presentation.

I carried on adding Presentation elements as required. I populated the rest of the editor by copying the structure of the default editor and reusing the existing elements.

Associating a Workflow

Finally I associated my new Work Item type with a Workflow. I reused the Bugzilla one which comes out of the box as it was more than sufficient for my needs. If you need to create your own, the aforementioned tutorial on the Jazz site provides an introduction on how to do this.