Update Your Agile Team Project to Support Additional Functionality After You Upgrade from TFS 2010 to TFS11 Beta

Ewald Hofman - MSFT

Summary

When a new version of TFS comes out, there are new features. Some of those features are backed by metadata such as work item types and work item categories. If you had to upgrade your TFS 2008 team project to TFS 2010 you know that this can be a daunting exercise. For TFS11 there are also a couple of features that need changes to the metadata. 

There is metadata that is required for a feature to get it working. To add the required metadata for all new TFS11 features, follow steps in the MSDN article Updating an Upgraded Team Project to Access New Features.

Besides the required metadata, there is also metadata that is optional. Features function correct if you leave the optional metadata out, but you get a lesser experience on these features. This blog post talks about adding the optional metadata to your Agile team project.

The optional metadata is:

  1. Add the New state to the User Story
  2. Add the Removed state to the User Story and the Task
  3. Add StartWork and StopWork actions to support state transitions when adding a task or bug in progress or removing it from progress in the My Work pane
  4. Add the Storyboard tab in the User Story work item type

This post is talking about a team project that was created with the Agile process template, however step 3 and 4 can also be applied to Scrum and CMMI projects.

Adding the New state

TFS11 introduced the planning tools (Product Backlog, Iteration Backlog and Board). The items shown in the Planning Tools are configured with the so-called metastates. When you open the CommonConfiguration.xml file (found in the “AgileWorkItem TrackingProcess” subdirectory) for the process template MSF for Agile Software Development 6.0, you see the following mapping

image

The metastates are defined in the type attribute (Proposed, InProgress or Complete), and you map these metastates to the states in your work items.

The logic the Product Backlog is using to build this query is in psuedo code

SELECT fields FROM WorkItems WHERE
    ((State = ‘Proposed’ OR State = ‘InProgress’) AND IterationPath == ‘RootIterationPath’) OR 
    ((State = ‘Proposed’) AND IterationPath <> ‘RootIterationPath’)

The process template MSF for Agile Software Development v5.0 has for its requirement (the User Story work item type) only the states Active, Resolved and Closed. When you take a close look at the file CommonConfiguration.xml file in the subdirectory Agile of the localized zip (provided in the article Updating an Upgraded Team Project to Access New Features), you will see that it is a slightly modified version, were the following mapping is applied:

image

With this modified settings, you are able to apply the settings to your VS 2010 Agile team project. The effect of these settings is that a user story that is assigned to an iteration stays on the Product Backlog until you have resolved it which is not what you’d expected. To fix this, you have to add the New state to the user story and fix the metastate mappings.

Modify the work item type

To add this state apply these steps to the User Story and Task work item types (replace the yellow marked text with your configuration and replace the green text with the appropriate work item type)

  1. Run the following command from the Developer Command Prompt to export the User Story work item type

        witadmin exportwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /n:”wit” /f:”%temp%wit.xml”

  2. Run the following command from the Developer Command Prompt the following command to open the exported work item type in Visual Studio

        devenv “%temp%wit.xml”

  3. Add the following code snippet between the lines <STATES> and <STATE value=Active>

    <STATE value=New>
       
    <
    FIELDS
    >
            <
    FIELD refname=Microsoft.VSTS.Common.ResolvedDate
    >
                <
    EMPTY
    />
            </
    FIELD
    >
            <
    FIELD refname=Microsoft.VSTS.Common.ResolvedBy
    >
                <
    EMPTY
    />
            </
    FIELD
    >
            <
    FIELD refname=Microsoft.VSTS.Common.ClosedDate
    >
                <
    EMPTY
    />
            </
    FIELD
    >
            <
    FIELD refname=Microsoft.VSTS.Common.ClosedBy
    >
                <
    EMPTY
    />
            </
    FIELD
    >
            <
    FIELD refname=Microsoft.VSTS.Common.ActivatedDate
    >
                <
    EMPTY
    />
            </
    FIELD
    >
            <
    FIELD refname=Microsoft.VSTS.Common.ActivatedBy
    >
                <
    EMPTY
    />
            </
    FIELD
    >
        </
    FIELDS
    >
    </
    STATE>

  4. Now that you have added the New state, the next step is to fix the transitions. The instructions assume you have not any modified states nor transitions.
    Replace the current initial state (which are the lines between <TRANSITION from=“” to=Active> and the closing </TRANSITION> tag) with the following code snippet:
    <TRANSITION from=“” to=New
      <
    REASONS

        <
    DEFAULTREASON value=New
    /> 
      </
    REASONS

      <
    FIELDS

        <
    FIELD refname=System.Description

          <
    DEFAULT from=value value=As a &lt;type of user&gt; I want &lt;some goal&gt; so that &lt;some reason&gt;
    /> 
        </
    FIELD

      </
    FIELDS

    </
    TRANSITION
    >
    <
    TRANSITION from=New to=Active

      <
    REASONS

        <
    DEFAULTREASON value=Implementation started
    /> 
      </
    REASONS

      <
    FIELDS

        <
    FIELD refname=Microsoft.VSTS.Common.ActivatedBy

          <
    COPY from=currentuser
    /> 
          <
    VALIDUSER
    /> 
          <
    REQUIRED
    /> 
        </
    FIELD

        <
    FIELD refname=Microsoft.VSTS.Common.ActivatedDate

          <
    SERVERDEFAULT from=clock
    /> 
        </
    FIELD

        <
    FIELD refname=System.AssignedTo
    > 
          <
    DEFAULT from=currentuser
    /> 
        </
    FIELD
    > 
      </
    FIELDS
    >
    </
    TRANSITION
    >
    <TRANSITION from=Active to=New
    > 
      <
    REASONS
    > 
        <
    DEFAULTREASON value=Implementation halted
    /> 
      </
    REASONS
    >
    </
    TRANSITION>

  5. Save the file

  6. Run the following command from the Developer Command Prompt to import the modified definition for the User Story work item type

                witadmin importwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /f:”%temp%wit.xml”

Modify the metastate mapping

The next step is to fix the mapping of the states in the CommonConfiguration.xml file. To do this follow these steps:

  1. Run the following command from the Developer Command Prompt to export the current common configuration

        witadmin exportcommonprocessconfig /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /f:%temp%commonconfiguration.xml

  2. Run the following command from the Developer Command Prompt the following command to open the exported common configuration settings in Visual Studio

        devenv %temp%commonconfiguration.xml

  3. Locate the tag <RequirementWorkItems category=Microsoft.RequirementCategoryplural=Stories>
  4. Replace the line <State type=Proposedvalue=Active> with the following lines

    <State type=Proposedvalue=New>
    <State type=InProgressvalue=Active>

  5. Locate the tag <TaskWorkItems category=Microsoft.TaskCategory>
  6. Insert the following line as first metastate mapping in the TaskWorkItems

    <State type=Proposedvalue=New>

  7. The result should be like

    image

  8. Save the file
  9. Run the following command from the Developer Command Prompt to import the modified common configuration

        witadmin importcommonprocessconfig /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /f:%temp%commonconfiguration.xml

Adding the Removed state

Because all states of the user story and the task work item type are mapped to a metastate, the iteration backlog and the task board show all the existing work items. In practice there is work that needs to be cut. To be able to cut work, a new state is required that will not be mapped. Therefor we have added the Removed state to the user story and the task work item type in the TFS 11 Agile process template. If you want to be able to cut work in your upgrade team project, you want to add this Removed state too.

To add this state apply these steps to the User Story and Task work item types (replace the yellow marked text with your configuration and replace the green text with the appropriate work item type)

  1. Run the following command from the Developer Command Prompt to export the User Story work item type

        witadmin exportwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /n:”wit” /f:”%temp%wit.xml”

  2. Run the following command from the Developer Command Prompt the following command to open the exported work item type in Visual Studio

        devenv “%temp%wit.xml”

  3. Add the following code snippet to the <STATES> section (the order of the states is not important):

    <STATE value=Removed” />

  4. Now that you have added the Removed state, the next step is to fix the transitions. Add the following code snippet to the <TRANSITIONS> section (the order of the transitions is not important)
    <TRANSITION from=“New” to=Removed
      <
    REASONS

        <
    DEFAULTREASON value=Removed from the backlog
    /> 
      </
    REASONS
    >
    </TRANSITION
    >
    <
    TRANSITION from=Removed to=New

      <
    REASONS

        <
    DEFAULTREASON value=Reconsidering the User Story
    /> 
      </
    REASONS
    >
    </TRANSITION>

  5. Save the file

  6. Run the following command from the Developer Command Prompt to import the modified definition for the work item type

        witadmin importwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /f:”%temp%wit.xml”

Adding the StartWork and StopWork action

In the new My Work pane you can add work items you’re working on to In Progress

image

 

and you can of course also remove it from In Progress

image

 

In addition to moving it around in the My Work pane, it also tries to change the state of the work item that you are adding to or removing from In Progress. To know which transition it needs to use, My Work is using two new actions. Until now there was only the action Microsoft.VSTS.Actions.Checkin, to transition the state of work items associated with a changeset at a checkin. Internally there is an API called “string GetNextState(string action)” that returns the next state for the given action.

To support transitioning the work item that is added to In Progress, there is the Microsoft.VSTS.Actions.StartWork action, and there is the Microsoft.VSTS.Actions.StopWork action to transition your work item when you remove it from In Progress. In the shipped Process Templates we have added the actions in the Task work item, and in the Bug work item in the CMMI process template.

To add these actions apply these steps to the Task work item types (replace the yellow marked text with your configuration)

  1. Run the following command from the Developer Command Prompt to export the User Story work item type

        witadmin exportwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /n:”task” /f:”%temp%task.xml”

  2. Run the following command from the Developer Command Prompt the following command to open the exported work item type in Visual Studio

        devenv “%temp%task.xml”

  3. Locate the snippet

    <TRANSITION from=Newto=Active>
      
    </TRANSITION>

  4. Insert the following code snippet in the transition

    <
    ACTIONS
  5. >
      <ACTION value=Microsoft.VSTS.Actions.StartWork
    >
    </ACTIONS>

  6. Locate the snippet

    <TRANSITION from=Activeto=New>
      
    </TRANSITION>

  7. Insert the following code snippet in the transition

    <
    ACTIONS
    >
      <ACTION value=Microsoft.VSTS.Actions.StopWork
    >
    </ACTIONS>

  8. Save the file

  9. Run the following command from the Developer Command Prompt to import the modified definition for the work item type

        witadmin importwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /f:”%temp%task.xml”

The following image shows the result of these actions in the Agile task

image

Add Storyboard tab

Since the early days there were requests to make it easier to define the user stories. TFS11 introduces Storyboarding which make use of PowerPoint to create a storyboard of your user story. We have added in TFS11 a new tab to the User Story work item type to integrate storyboarding.

To add this storyboard integration apply these steps to the User Story work item types (replace the yellow marked text with your configuration)

  1. Run the following command from the Developer Command Prompt to export the User Story work item type

        witadmin exportwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /n:”user story” /f:”%temp%user story.xml”

  2. Run the following command from the Developer Command Prompt the following command to open the exported work item type in Visual Studio

        devenv “%temp%user story.xml”

  3. Locate the snippet

    <Tab Label=Details>
       <Control FieldName=System.DescriptionType=HtmlFieldControlDock=Fill
    >
    </Tab
    >

  4. Add the following code snippet between the Details and the Implementation tab

    <
    Tab Label=Storyboard
    >
      <Control Name=StoryboardsControlType=LinksControl
    >
        <LinksControlOptions>
          <WorkItemLinkFilters FilterType=“excludeAll” /
    >
          <ExternalLinkFilters FilterType=“include
    >
            <Filter LinkType=“Storyboard” /
    >
          </ExternalLinkFilters
    >
          <LinkColumns
    >
            <LinkColumn RefName=“System.Title” /
    >
            <LinkColumn LinkAttribute=“System.Links.Comment” /
    >
          </LinkColumns
    >
        </LinksControlOptions>
      </Control>
    </Tab
    > 
  5. Save the file
  6. Run the following command from the Developer Command Prompt to import the modified definition for the work item type

        witadmin importwitd /collection:http://localhost:8080/tfs/defaultcollection /p:Agile5 /f:”%temp%user story.xml”

You have now successfully applied all changes to your Agile team project to use all the features as we have designed them. We would love to hear your feedback in the MSDN Forums to ask questions, on Microsoft Connect to file bugs and user voice to suggest new features.

Ewald Hofman
Program Manager, Team Foundation Server

0 comments

Discussion is closed.

Feedback usabilla icon