Update the workflow for agile team projects

After you have configured features for your upgraded team project, which was created with a process template based on Microsoft Solutions Framework (MSF) for Agile Software Development v5.0, you should manually update the user story and task workflow assignments. If you don't update the workflow, then the task board provides only two states, Active and Closed, as shown in the following illustration. This prevents you and your team from distinguishing between tasks that are in progress from those that haven't been started.

Task board for an Agile team project without the recommended manual updates

Updates made by the Configure Features wizard were made to match the existing workflow that is defined for your team project. For version 5.0 of the MSF Agile process template, this means the New and Removed states introduced with the latest version are not present. These states support transitioning user stories from a New state to an Active state. Without the New state defined, a User Story assigned to an iteration remains on the product backlog until it is resolved, which is not the desired or expected behavior.

In the same way, adding the New state to the Task workflow lets users move tasks from New, to Active, to Closed using the task board. In addition, by adding the Removed state to both the User Story and Task type definitions you enable users to cut stories and tasks using the planning tools.

To support the desired behaviors, you must add the New and Removed states to the user story and task work item types, and update the metastate mappings assigned in the process configuration.

Note

You can perform some of the procedures described below using Process Editor, a power tool add-in for Visual Studio which you can download and install. Located under the Tools menu, Process Editor provides a graphical user interface for customizing Team Foundation Server process templates. You can use this tool to import and export work item types and modify the contents of the process template. For more information, see the following page on the Microsoft website: Team Foundation Server Power Tools.

Requirements

• To run the witadmin command-line tool, you must be a member of one of the following groups: Team Foundation Administrators, Project Collection Administrators, or Project Administrators group for the team project. See Permission reference for Team Foundation Server.

Update the workflow and metastates for an Agile team project

Important

The procedures in this topic were written based on the MSF for Agile Software Development 6.0. To update your team project to support the latest workflow defined for MSF for Agile Software Development 6.1, you can adapt these procedures to instead copy the WORKFLOW sections of the latest Agile process template. Significant updates were made to the workflow for several work item types in the latest quarterly update. These changes support backward transitions so that when you inadvertently drag a work item on the Kanban board or the task board to a resolved or closed state, you can drag it back to an earlier workflow state.

To learn more about the update, see What's new in planning and tracking.

You will need to perform the following steps:

• Export the definitions for the User Story and Task types and for process configuration.

• Insert code snippets to the workflow section for both User Story and Task.

• Update the metastate mappings for the process configuration.

• Import the updated definitions for the work item types and process configuration.

• Verify that the changes appear on the task board.

Important

For the following procedures to work, the Active state must be specified in the workflow defined for the User Story and Task types of work items.

To update the workflow states and transitions for User Story

1. To run the witadmin command-line tool, open a Command Prompt window where either Visual Studio or Team Explorer is installed and type:

   cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDE
   

   On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.

2. To export the type definition for User Story, enter the following command, substituting your data for the arguments that are shown here, where CollectionURL specifies the URL of a team project collection, ProjectName specifies the name of a team project defined within the collection, and "DirectoryPath\FileName.xml" specifies the name and location for the file to export. Then press Enter.

   witadmin exportwitd /collection:CollectionURL /p:"ProjectName" /n:"User Story" /f:"DirectoryPath\FileName.xml"
   

   Use this format for the URL: **http://**ServerName:Port/VirtualDirectoryName/CollectionName, for example: http://srvalm:8080/tfs/DefaultCollection.

3. In a text editor or in Visual Studio, open the file you exported.

4. Add this 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>
   <STATE value="Removed" />
   

5. Replace the section that begins with <TRANSITION from=" " to="Active"> and ends with <TRANSITION> with this 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="New" to="Removed">
      <REASONS>
         <DEFAULTREASON value="Removed from the backlog" />
      </REASONS>
   </TRANSITION>
   <TRANSITION from="Active" to="New">
      <REASONS>
         <DEFAULTREASON value="Implementation halted" />
      </REASONS>
   </TRANSITION>
   <TRANSITION from="Removed" to="New">
      <REASONS>
         <DEFAULTREASON value="Reconsidering the User Story" />
      </REASONS>
   </TRANSITION>
   

6. Save and close the file.

7. Import the file, substituting your data for the arguments that are shown.

   witadmin importwitd /collection:CollectionURL /p:"ProjectName" /f:"DirectoryPath\FileName.xml"
   

To update the workflow states and transitions for Task

1. Export the type definition for Task, substituting your data for the arguments that are shown.

   witadmin exportwitd /collection:CollectionURL /p:"ProjectName" /n:"Task" /f:"DirectoryPath\FileName.xml"
   

2. In a text editor or in Visual Studio, open the file you exported.

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

   <STATE value="New">
      <FIELDS>
         <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>
   <STATE value="Removed" />
   

4. Replace the first transition block, corresponding to the lines that fall between <TRANSITION from="" to="Active"> and its closing </TRANSITION> tag, with this code snippet:

   <TRANSITION from="" to="New">
      <REASONS>
         <DEFAULTREASON value="New" />
      </REASONS>
   </TRANSITION>
   <TRANSITION from="New" to="Active">
      <ACTIONS>
         <ACTION value="Microsoft.VSTS.Actions.StartWork" />
      </ACTIONS>
      <REASONS>
         <DEFAULTREASON value="Work 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">
      <ACTIONS>
         <ACTION value="Microsoft.VSTS.Actions.StopWork" />
      </ACTIONS>
      <REASONS>
         <DEFAULTREASON value="Work halted" />
      </REASONS>
   </TRANSITION>
   <TRANSITION from="New" to="Closed">
      <ACTIONS>
         <ACTION value="Microsoft.VSTS.Actions.Checkin" />
      </ACTIONS>
      <REASONS>
         <DEFAULTREASON value="Completed" />
         <REASON value="Cut" />
         <REASON value="Deferred" />
      <REASON value="Obsolete" />
      </REASONS>
      <FIELDS>
         <FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
            <READONLY />
         </FIELD>
         <FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
            <READONLY />
         </FIELD>
         <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
            <SERVERDEFAULT from="clock" />
         </FIELD>
         <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
         <COPY from="currentuser" />
            <VALIDUSER />
            <REQUIRED />
         </FIELD>
      </FIELDS>
   </TRANSITION>
   <TRANSITION from="Closed" to="New">
      <REASONS>
         <DEFAULTREASON value="Reactivated" />
      </REASONS>
      <FIELDS>
         <FIELD refname="System.AssignedTo">
            <COPY from="field" field="Microsoft.VSTS.Common.ClosedBy" />
         </FIELD>
      </FIELDS>
   </TRANSITION>
   <TRANSITION from="New" to="Removed">
      <REASONS>
         <DEFAULTREASON value="Removed from the backlog" />
      </REASONS>
   </TRANSITION>
   <TRANSITION from="Active" to="Removed">
      <REASONS>
         <DEFAULTREASON value="Removed from the backlog" />
      </REASONS>
   </TRANSITION>
   <TRANSITION from="Removed" to="New">
      <REASONS>
         <DEFAULTREASON value="Reconsidering the Task" />
      </REASONS>
   </TRANSITION>
   

5. Save and close the file.

6. Import the file, substituting your data for the arguments that are shown.

   witadmin importwitd /collection:CollectionURL /p:"ProjectName" /f:"DirectoryPath\FileName.xml"
   

To update the metastate mappings for process configuration

1. Type the following command to export the ProcessConfiguration file, substituting your data for the arguments that are shown.

   witadmin exportprocessconfig /collection:CollectionURL /p:"ProjectName" /f:"DirectoryPath\ ProcessConfiguration.xml"
   

   Where, CollectionURL specifies the URL of the team project collection and ProjectName specifies the name of your team project. Use this format for the URL: **http://**ServerName:Port/VirtualDirectoryName/CollectionName, for example: http://srvalm:8080/tfs/DefaultCollection.

2. In Notepad or in another text editor, open the ProcessConfiguration.xml file.

3. Locate the tag <RequirementWorkItems category="Microsoft.RequirementCategory" plural="Stories">.

4. Replace the line <State type="Proposed" value="Active" /> with these lines:

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

5. Locate the tag <TaskWorkItems category="Microsoft.TaskCategory">, and replace the line <State type="Proposed" value="Active" /> with these lines:

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

6. Verify that you have the following mappings:

   <RequirementWorkItems category="Microsoft.RequirementCategory" plural="Stories">
      <States>
         <State type="Proposed" value="New"/>
         <State type="InProgress value="Active" />
         <State type="InProgress value="Resolved" />
         <State type="Complete" value="Closed" />
      </States>
   </RequirementWorkItems>
   <TaskWorkItems category="Microsoft.TaskCategory">
      <States>
         <State type="Proposed" value="New" />
         <State type="InProgress" value="Active" />
         <State type="Complete" value="Closed" />
      </States>
   </TaskWorkItems>
   

7. Save and close the file.

8. Import the configuration file.

   witadmin importprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\ProcessConfiguration.xml" 
   

To verify that the changes appear on the task board

1. Open Team Web Access and then connect to your team project using a URL that has the following format:

   http://MyServer:8080/tfs/TeamProjectCollectionName/MyProject
   

   If TWA is already open, then refresh your browser to refresh the cache.

2. Verify that the task board columns now display New, Active, and Closed.

   Task board for an Agile team project with the updated workflow states

   

   To learn more about using the task board, see Work in sprints.

See Also

Concepts

Track work with Visual Studio ALM and TFS

Configure features after a TFS upgrade