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.

Tips for Setting up a New Project in IBM's Jazz Team Server

I've just set up my first few projects on IBM's Jazz platform.  It's dead simple, but there are a few things I've learned which are worth knowing.  I've listed them so others can benefit from my experiences.  

NOTE: this is all done with the Web UI.  Once you've completed these steps, its best to move to the Eclipse-based client for the rest of your configuration as the errors are less cryptic / actually exist.

1. Think about what you need before you do anything.  You need to know what you will name your project (we named ours after the client), which process you will use (we are going for Scrum), what your development lines are (we have the default mainline and also an existing release (we have inherited a codebase) and what teams ("Team Areas") you will need (we have one for our client who will access the web UI as well as multiple for ourselves).  There are other descicions to make, but these are the ones you will need at the beginning.
2. Create an admin user for your project area.  Give them JazzAdmin priviledges and also (temporarily) a Developer licence.
3. Logged in as your project admin user deploy the bundled process configurations
4. Still logged in as your project admin user, create the users you need, allocating them licences as appropriate.  As well as the "real" users, you will likely need a Build user.
5. Before you create your Project area, deploy the bundled process configurations
6. Create your project, making sure you select the process you want to use.  Add the users you have created as applicable.  Allocate the users to process roles (i.e. Team Member, ScrumMaster etc.)
7. Create any additional Development Lines.  We kept the default "Main Development Line" but also added a "Support Development Line"
8. Create team areas as required.  We had several - one for the client, one for our onsite support, another for the existing app maintenance, and a fourth for new development.  Team Members can belong to more than one team so don't worry about allocation when designing this layout.  Make sure when you create a Team Area that you select the required Development Line
9. Allocate team members to the team areas as appropriate.  I choose to send the invite emails as this makes getting new members onboard easier
10. Remove the default admin user (archive the account)
    
11. Set up backups 

Additional Notes:

• I've tried this on Jazz 1.0 and 1.0.1
• It might seem as if you can't rename or archive some things after you've created them if you're using the Web UI.  Swap to the Eclipse client and you will probably be in luck.
• I've not covered adding additional "Setup Work Items" which are automatically generated for each user upon creation.  This should be done before team members are added.  I'll cover this in a later blog post

Adding a Non-Eclipse Project to Jazz SCM

IBM's new Jazz platform works most intuitively when you're in an all-IBM world.  We're not in that world on my current project and were having to find our way a little (with excellent support from IBM).  Here's how to share a non-Eclipse project with Jazz SCM.

Pre requisites: I'm assuming you have some stuff in a filesystem you want to share.

1. Download and unzip the RTC Client for your operating system - its any of the "Zip > Client" files under "Express-C", "Express" or "Standard".  They're all the same.
   
2. Startup the RTC eclipse client - e.g ./RTC-Client-1.0.1-Win/jazz/client/eclipse/TeamConcert
3. Switch to / open the Java Perspective (Window > Open Perspective > Other... > Java)
4. Switch to the Package Explorer View (if you can't see it open it by navigating to Window > Show View > Other... > Package Explorer)
5. In the Package Explorer View (it should have opened in the left hand pane.  If not, open it by going to Window > Show View > Package Explorer) ...
6. ... and right click in it and select New > Other
7. In the dialog which appears type "Project" and select General > Project which should be visible
8. Click "Next"
9. Enter a project name (the name of the folder containing the files which you want to share is good)
10. Leave the "Use default selection" ticked.  This will mean the project is created in your RTC workspace.  If you want it to be elsewhere, untick this and Browse to where you want it to be.  NOTE: we will be copying your project into this Eclipse project so don't point straight at the project you are going to share
11. Click "Finish"
12. You should see your newly created project in the Package Explorer View
13. Right click on the new project in the Project Explorer and select "Import..."
14. Type "file" in the text box and select General > File System which should be visible
15. Click "Next"
16. Click on "Browse" and select the folder containing the content you wish to share
17. In the right hand pane, tick all of the contents of the folder you with to share.  Make sure the folder itself is not ticked.  You already have a folder with the same name you are importing into
18. Click "Finish"
19. Once the import has finished, expand your project in the Package Explorer and check that what you have imported is there.  You may have to press "F5" with your project selected to refresh if things are not visible
20. Now you can share your project.  Right click on the project in the Package Explorer and select "Team > Share Project ..."
21. Select "Jazz Source Control" and click "Next"
22. Select a component to associate this project with.  (NOTE: See the Jazz docs for more detail on what a component is.  If you need to you can create a Component at this point in the process.  We'll assume that the components available include one which you want to use.) Click "Next" when you're done
23. Tick the "Show all resources" checkbox and check that all the files you want to share are shown.  If you want to exclude files, you can select them and click the "Ignore" button.  Alternatively you can set a new pattern.
24. Click "Finish"
25. Switch to the "Pending Changes" view. (If you can't see it go to "Window > Show View > Other..." and select "Jazz Source Control > Pending Changes")
26. Expand the workspace that you shared your project into.  You should see a folder called "Outgoing"
27. Right click on "Outgoing" and select "Deliver"
28. Congratulations! You've shared your project.