Welcome to blogs.conchango.com

In this post I am going to explain how to add a new work flow state to the "Sprint Backlog Item" (SBI) work item type definition and how to enable [the new state] in the Task Board for Team System.

• Why would you want to add a new state?
• Step 1 - Exporting the work item template
• Step 2 - importing the altered work item template
• Step 3 - updating the Task Board configuration file
• Step 4 - updating the Task Board default column layout file
• Nearly done
• Limitations and Disclaimers
• Links

Why would you want to add a new state?

The default work flow of states (available to the SBI) when you install the Scrum for Team System process template are:

• Not Done (work on task has not started)
• In Progress (work on the task has started)
• Ready for Test (the task functionality is complete and needs to be tested)
• Done (the task is complete to your definition of "Done")
• Deferred (the task has been put off until a subsequent sprint)
• Deleted (the task is removed from the work flow)

The default states and workflow for Version 2 of the SfTS process template

This array of states is designed to give you all the required work flow options so that you may move SBIs through the sprint process from "Not Done" to "Done". For more information on the default states and what they all mean, please review the Scrum for Team System process guidance.

http://scrumforteamsystem.com/processguidance

But what happens if your company has different work flow needs or requires another step in the chain of events? How do you add your new requirement to the default process flow?

For this example, I’m going to add a new state to the work flow entitled "Blocked". The Blocked state will be an indicator that the SBI cannot be progressed and is Blocked the completion of the parent product backlog item.

The new proposed workflow with the added Blocked state.

As you can see the new state can only be entered from "In Progress" and can only be changed to either "In progress", "Ready for Test" or "Deleted".

Step 1 - Exporting the work item template

The first step in applying our new state is to export the SBI work item template definition file from the TFS project so that we can edit it. This is accomplished by using the "WITEXPORT" command line utility.

Here is an example command line that exports the SBI work item template from a project entitled "DemoData" which resides in a TFS with a URL of "http://TFSRTM08:8080":

Switches:

• /f = local path to save the exported work item template file
• /t = TFS URL (or machine name)
• /p = the source project
• /n = name of the work item type to export

Executing the command line will result in a new XML document being created at "c:\temp\Sprint Backlog Item.xml"

Next up, we need to add the new "Blocked" state to the work item definition. So, open the "Sprint Backlog Item.xml" document in your text editor of choice and follow the below instructions.

1. Navigate to the node: WITD / WORKITEMTYPE / WORKFLOW / STATES
2. Add a new child node:
   
   

   <STATE value="Blocked" />

3. Next navigate to node: WITD / WORKITEMTYPE / WORKFLOW / TRANSITIONS
4. Add 4 child transition nodes:
   
   

   <TRANSITION from="In Progress" to="Blocked">
     <REASONS>
       <DEFAULTREASON value="Item is blocked" />
     </REASONS>
   </TRANSITION>
   <TRANSITION from="Blocked" to="In Progress">
     <REASONS>
       <DEFAULTREASON value="Item is unblocked" />
     </REASONS>
   </TRANSITION>
   <TRANSITION from="Blocked" to="Ready For Test">
     <REASONS>
       <DEFAULTREASON value="Ready for testing" />
     </REASONS>
   </TRANSITION>
   <TRANSITION from="Blocked" to="Deleted">
     <REASONS>
       <DEFAULTREASON value="Item deleted" />
     </REASONS>
   </TRANSITION>

5. Then save the document.

Step 2 - importing the altered work item template

Now we need to get the edited work item definition file back into the Team Project. For this we use a command line utility entitled "WITIMPORT".

Here is an example command line that will import our edited XML document back into the "DemoData" project.

Switches:

• /f = local path of the work item template file to import
• /t = TFS URL (or machine name)
• /p = the target project

Executing the command line will import our altered SBI work item definition template in the "DemoData" project. Once complete, you can test the new state through Team Explorer. Remember, you will only be able to select this state if the SBI is in a state of "In Progress".

Step 3 - updating the Task Board configuration file

Now we have altered SBI, we need to tell the Task Board for Team System (TBfTS) about it. This involves editing 2 xml configuration files in the TBfTS installation folder.

The default installation location is:

We need edit the "Conchango.TeamSystem.TaskBoard.WpfUI.exe.config" file. This amendment tells the task board application that SBI work items have a new state.

• Open "Conchango.TeamSystem.TaskBoard.WpfUI.exe.config" in your chosen text editor.
• Change text:
  
  

  <setting name="WorkItemStates_SBI" serializeAs="Xml">
    <value>
      <ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <string>Not Done</string>
        <string>In Progress</string>
        <string>Ready For Test</string>
        <string>Done</string>
        <string>Deferred</string>
        <string>Deleted</string>
      </ArrayOfString>
    </value>
  </setting>
  

• To equal:
  
  

  <setting name="WorkItemStates_SBI" serializeAs="Xml">
    <value>
      <ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <string>Not Done</string>
        <string>In Progress</string>
        <string>Ready For Test</string>
        <string>Done</string>
        <string>Deferred</string>
        <string>Deleted</string>
        <string>Blocked</string>
      </ArrayOfString>
    </value>
  </setting>
  

• Save the document.

Note: The sequence of the listed SBI states is important. This determines the colours and icons used in the task board. For example, the first state in the sequence will have the Exclamation icon and the second will have the right pointing arrow icon.

Step 4 - updating the Task Board default column layout file

Next, we need to edit the "DefaultColumnLayout.xml" file. This file controls the default appearence of the task board columns including display text, width and display order.

Open the file "DefaultColumnLayout.xml" in your text editor and you will be presented with the below XML:

As you can see from the above XML, the column layout data is split into 2 MODEs; Sprinting and Planning. These sections correlate with the task board modes, so when the task board is in "Sprinting Mode" the data under <MODE Name="Sprinting"> is used.

Each COLUMN node contains the following attributes:

• DisplayText = the text to be shown along the column headings section of the task board.
• Width = the actual width of the column (set to zero in order to hide that column)
• MinumumWidth = the smallest possible width of the column (must be zero if you wish to hide a column)
• State = the SBI state displayed in the column.

Note:
The sequence of the COLUMN elements determines the display position within the task board application.
The first column node is reserved for the backlog item row header and cannot be used as a state container.

Edit the XML to read as follows:

Note: Don't forget to delete the "Spare" column definition. There must be exactly 7 columns in each mode.

Save the document.

Nearly done

The required configuration changes are now complete and we can launch the task board application to see the new state in action. Well almost!

In order to apply the changes [made to the "DefaultColumnLayout.xml" file], you will need to reset the column layout in the task board application. This is accomplished via the "Edit" -> "Reset Column Layout" task board menu option.

And that’s it; you should now see the new Blocked column in the task board and be able move SBIs from an "In Progress" state into the "Blocked" state.

The "Blocked" state in the task board

Limitations and Disclaimers

• The Task Board for Team System can support a maximum of 6 swim lane states.
• The above example is based on the Task Board for SfTS v2.x application. The listed states will be different for Task Board for SfTS 1.2 applications.
• Due to the inability to access the work item template data via SQL Reporting services, the Scrum for Team System reports (installed by default) will not auto-magically detect changes to the work item templates. Removing states and or fields that are required by the reports will cause incorrect functionality and possible reporting failure.
• Conchango cannot offer support for customised instances of the Team Projects. Only unaltered Team Projects created from the Scrum for Team System template are supported.
• It is your own responsibility to ensure the stability of your Team Foundation Server environment. Make backups where possible before attempting any of the changes described in this article.

Links

Scrum for Team System:

http://scrumforteamsystem.com/en/default.aspx

Task Board for Team System:

http://scrumforteamsystem.com/en/TaskBoardBeta/Default.aspx

Community Forum:

http://scrumforteamsystem.com/cs/forums/

What next?

To complete the process, you could also add a new "Blocked" state to the Product Backlog Item and alter the Scrum for Team System event handler process to auto change the PBI status whenever a child SBI is set to blocked. But that is a blog for another day...

Crispin Parker