How to: Add a Custom State

There are a few steps which should be followed in order to add a new state to a work item type (WIT) in TeamPulse and TFS.  The diagram below displays an overview of the process:

 enlarge screenshot

 

1. First of all the state should be added in TeamPulse for the particular work item type. In the example here a new state will be added for a Story but still keep in mind that the flow is exactly the same no matter what the WIT is.  Note: to edit project settings in TeamPulse you must be a member of the Project Administrator group.

 

In TeamPulse, navigate to Settings -> Project Settings -> Edit Advanced Settings.  Save a backup and after that add the needed state ("Ready For Test" in this case) in the format shown in the image below:

 enlarge screenshot

 

 Also the state should be added properly to the relevant state group:

enlarge screenshot 

 

 2. The second step is to add all the transitions between the new state and some of the other states.  The end result should look similar to the example below:

enlarge screenshot

 

NOTE: The case of the letters should be exactly as the same as the one in the default template.  Also the case of the state added should be exactly the same in both TFS and TeamPulse.  In this case, "Ready For Test" should be used everywhere because if, for example, "Ready for Test" (note the lowercase 'f') is used in TFS, it will cause issues during synchronization.

 

3. The next step is to add the new state to the respective TFS project.

 NOTE: This step requires you to have the TFS power tools installed in order to get access the work item type definitions.  The power tools can be found here.

 In Visual Studio, navigate to Tools -> Process Editor -> Work Item Types -> Export WIT.  Use the dialog to connect to a project collection and then in the "Select Work Item Type" dialog expand your TFS project and select the WIT you want to edit (Product Backlog Item in this case):

enlarge screenshot

 

NOTE: It is important to export the file without Global List Definitions.

 

NOTE: If you are not sure which WIT in TeamPulse is mapped to which WIT in TFS, in TeamPulse, navigate to Settings -> TFS Sync Information -> expand TFS Server Configuration -> Edit Synchronization Mappings.  Find the 'EntityMapping' elements to see which WITs are mapped together as in the screenshot below:

enlarge screenshot

 

NOTE: Before editing the file be sure you stored a backup!

 

4. Open the exported file for editing and add the new state with all transitions exactly as it was added in TeamPulse:

enlarge screenshot

 

At the end, import the updated file with the original name in TFS.

 Now the newly added state should be taken into account properly.