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

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

  • Comments 7

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 “Agile\WorkItem Tracking\Process” 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 &amp;lt;type of user&amp;gt; I want &amp;lt;some goal&amp;gt; so that &amp;lt;some reason&amp;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.RequirementCategory" plural="Stories">
  4. Replace the line <State type="Proposed" value="Active"> with the following lines

    <State type="Proposed" value="New">
    <State type="InProgress" value="Active">

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

    <State type="Proposed" value="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="New" to="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="Active" to="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.Description" Type="HtmlFieldControl" Dock="Fill"
    >
    </Tab
    >
  4. Add the following code snippet between the Details and the Implementation tab

    <
    Tab Label="Storyboard"
    >
      <Control Name="StoryboardsControl" Type="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

Leave a Comment
  • Please add 7 and 8 and type the answer here:
  • Post
  • Thanks Hofman, I think your video also important which is here

    channel9.msdn.com/.../Upgrading-to-Team-Foundation-Server-11-Process-Templates

  • The included XML snippet for the Storyboard tab is incorrect. The FieldName attribute on the Control element should not be present. Also several other elements are missing the closing syntax (ie /> )

    Regards,

    Jason

  • Thanks Jason. I have updated the storyboard snippet.

  • What steps need to do for converting CMMI project to TFS 11?

  • When you follow the steps in the article Updating an Upgraded Team Project to Access New Features you will find the steps required for upgrading a CMMI project.

  • When I try to add the Storyboard link type to the my PBI (story), it says the Storyboard link type is not found.  What does the Storyboard link type look like?  When I try to export linktypes from the standard scrum template with witadmin listlinktypes ... I don't get all of the link types.  What am I missing?

  • BABRC,

    The storyboard link type is not a WIT link but an “external link”, so witadmin listlinktypes will not display it.

    On server side upgrade, the storyboard external link type will be created on the server.

    However, on the client side of things, you do not get a VS dialog to edit the link type unless you are working with VS2012 (e.g. you cannot create or edit storyboard links using VS2010). What version of the client are you using?

    Another thing to test is to do the same thing through web access, that should work on the web for sure. If it does, then it more clearly points to problems with the rich client.

Page 1 of 1 (7 items)