Customize the Task Board Page

  • Article

You can customize the task board of Team Web Access (TWA) to specify different work item types (WITs) and increase the number of work items that appear on the page. For example, you might want to add bugs in addition to tasks to appear on the task board. With the task board, your team can update work items and report progress. The work items that are displayed include all tasks that have been assigned to the current iteration and their parent items, regardless of the iteration to which the parents have been assigned. To learn more about using the task board, see Work in sprints.

If your team project was created using a process template other than those provided by Visual Studio Application Lifecycle Management (ALM) or you have customized the WIT definitions or modified their workflow, you may need to customize one of the definition files for process configuration.

In this topic

  • WITs that appear on the task board page

  • Column headings and column sequence

  • Sort order of backlog items

  • Number of items that can appear on the task board page

To customize the backlog page, including adding metastate mappings for workflow states, see Customize the Backlog Pages.

Requirements

  • To run the witadmin command-line tool, you must be a member of the Team Foundation Administrators group or a member of the Project Administrators group for the project. For more information, see Team Foundation Server Permissions.

  • To view the task board page, your Team Web Access Permissions must be set to Standard. Additional licensing requirements may apply. For more information, see Change access levels.

WITs that appear on the task board page

The following elements determine which work items appear on the task board page.

  • Backlog items correspond to those WITs assigned to the Requirements Category. Only backlog items that have been assigned to the current iteration or that have tasks that have been assigned to the current iteration appear on the task board. They can be in any workflow state.

  • Task items that can be added as child tasks to the backlog items correspond to the WITs assigned to the Task Category.

    Only tasks that have been assigned to the current iteration appear on the task board.

    Tasks appear under the column heading of their workflow state. As you drag and drop the tasks from one column to another, the state field is automatically updated.

Note

If you add a WIT to the Task category, make sure that you add those fields that you used to track work to the definition for the work item type. For an end-to-end example of adding a WIT to the task board, see Add bugs to the task board or backlog.

To specify the types of task work items that appear

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

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

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

  2. Type 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 specifies the name and location for the file to export. Then choose Enter.

    witadmin exportcategories /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\categories.xml"

  3. Open the categories file in Notepad, and locate the CATEGORY element for the "Task Category".

  4. To add a new type of work item, add a WORKITEMTYPE element that specifies the friendly name of another work item type that you want to add.

    For example, the following syntax adds the "Work Request" WIT to the Task Category for a team project that uses the Agile process template.

    <CATEGORY name="Task Category" refname="Microsoft.TaskCategory">
   <DEFAULTWORKITEMTYPE name="Task" />
   <WORKITEMTYPE name="Work Request" />
</CATEGORY>

    Tip

    You must specify a WIT that has been defined for your team project. A WIT can belong to more than one category. However, a WIT cannot belong to both the Task Category and the Requirement Category.

  5. Type the following command to import the definition file:

    witadmin importcategories /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\categories.xml"

To assign metastates to workflow states of task types of work items

  1. From the Command Prompt window for witadmin, type 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 specifies the name and location for the file to export. Then choose Enter.

    witadmin exportcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"

  2. Open the CommonConfiguration file in Notepad and locate the TaskWorkItems element.

    For example, for the Agile process template the following syntax appears:

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

    The task board displays the column headings of New, Active, and Closed.

  3. (Optional) To include the workflow states for another type of work item, for example bug, you must add an assignment for the Resolved workflow state.

    For example, you can update the <TaskWorkItems> to contain metastate assignments for both tasks and work requests that are linked to backlog items. In the following syntax, the Resolved workflow state is assigned to the InProgress metastate.

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

    Important

    You must specify a value for the State element that corresponds to a valid workflow state. A valid workflow state in this case is a state that has been defined for a WIT that is included in the Task Category for your team project. Also, you must assign a metastate type within the Agile group, that is Proposed, InProgress, and Complete. For a description of each of these states, see Workflow states, metastates, and process configuration.

  4. Type the following command to import the definition file:

    witadmin importcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"

  5. Press F5 to refresh the web page for Team Web Access to reflect the changes.

Columns and the column sequence

The column headings that appear on the task board page correspond to the workflow states assigned to the default task type assigned to the Task Category. The column sequence corresponds to the natural progression of the workflow transitions, moving from left to right. The workflow states defined for the default task type in the Task Category must be assigned to a valid metastate within the Agile group as described in Workflow states, metastates, and process configuration.

Sort order of backlog items

Backlog items are listed in ascending order according to the value of the field assigned to type="Order" in the definition for CommonConfiguration. This field controls the order of backlog items that appear on both the iteration and task board pages.

To specify a different field to use to sort backlog items

  1. From the Command Prompt window for witadmin, type the following command substituting your data for the arguments 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 specifies the name and location for the file to export. Then choose Enter.

    witadmin exportcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"

  2. Open the CommonConfiguration file in Notepad, and locate the TypeField element with type="Order".

    For example, the default assignment for the Agile process template is:

    <TypeField refname="Microsoft.VSTS.Common.StackRank" type="Order" />

  3. Change the value assigned to refname to the field that you want to base the sort order on.

    For example, the following syntax specifies to sort the backlog items based on the custom field, Fabrikam.Order.

    <TypeField refname="Fabrikam.Order" type="Order" />

    Important

    You must specify the reference name of a field that is defined for the default type of work item specified for the Requirements Category for your team project.

  4. Type the following command to import the definition file:

    witadmin importcommonprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\CommonConfiguration.xml"

  5. Press F5 to refresh the web page for Team Web Access to reflect the changes.

Back to top

Number of items that can appear on the task board page

For performance reasons, the task board is by default restricted to a total of 500 work items. When you open the task board, all work items are loaded into cache. Limiting the number of work items may yield quicker load times. You can change this limit by specifying a value for the workItemCountLimit attribute of the IterationBacklog element.

  1. From the Command Prompt window for witadmin, type 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 specifies the name and location for the file to export. Then choose Enter.

    witadmin exportagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"

  2. Open the AgileConfigurations file in Notepad, and locate the section for IterationBacklog.

  3. Specify a value for the workItemCountLimit attribute.

    For example, the following syntax increases the count to 800.

    <IterationBacklog workItemCountLimit="800">
. . .
  </IterationBacklog>

  4. Type the following command to import the definition file:

    witadmin importagileprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\AgileConfiguration.xml"

  5. Press F5 to refresh the web page for Team Web Access to reflect the changes.

See Also

Concepts

Work in sprints

Process Configuration XML Element Reference

Customize the Backlog and Board Pages Using Process Configuration