Customize Work Item Tracking and Your Team Project

What you can customize related to areas and iterations:

• Add child areas and iterations that nest up to 14 levels deep.

• Specify a default area path and a default iteration path for a team. The defaults are automatically assigned to those backlog items that you create through the quick add panel on the product backlog page.

• Select which areas and iterations your team will use. See Specify your sprint schedule.

• Set the start and end date for iterations that your team uses to track an iteration or sprint.

• Limit access to view, create, or edit work items and manage test plans that are defined under an area.

• Restrict who can add or modify child nodes that are defined under an area or iteration.

Implementation notes:

• Child areas and iterations appear in the drop-down menus of the Area Path and Iteration Path fields. These fields appear in most work item forms and in the filter criteria within the query editor. Also, many out-of-box (OOB) reports reference these fields for the purposes of filtering.

• Links for iteration backlog pages appear on the backlog page only for those iterations that have been selected for a team.

• You must select at least one area path as active for a team before you can use features such as the product backlog, the task board, or team home page. See Add another team.

• If you define a path that contains more than 256 characters, you will not be able to specify it in Microsoft Project. To avoid this problem, label child areas and iterations with fewer than 10 characters, and do not nest nodes more than 14 levels deep.

How you customize:

• To add or modify area, open Team Web Access, and choose the gear icon next to your user name at the top of the page. On the administrative page, choose areas. Or, from Visual Studio, choose Team, Team Project Settings, Work Item Areas.

• To add or modify iteration paths, from the Team Web Access administration page, choose iterations.

  See Create and Modify Areas and Iterations.

What you can customize related to teams:

• Manage team members and access to team resources.

• Define team areas and iterations as described in Area and iteration paths.

• Define team alerts, which send email notifications when changes occur to work items, code reviews, source control files, and builds.

• Add or remove tiles from the team home page that link to the work item queries, build definitions, and source control folders.

• Re-sequence the set of tiles on the team home page.

Implementation notes:

• The Assigned To field is designed to only display team members when accessed from the shortcut menus of TWA.

• All team members will see the tiles and sequence that you specify for the team home page. Any team member can change the tile set and sequence.

How you customize:

• To add a team, from TWA, choose the gear icon to open the administrative page. On the Overview tab, choose the New Team link. See Add another team.

• To define team alerts, open the administrative page for Team Web Access and choose the alerts tab. See Set alerts, get notified when changes occur.

• To add a tile to the team home page, choose Add to team favorites from the shortcut menu for each object that you want to appear on the home page. You can only add team favorites to the team home page. You can't add my favorites. See Manage team favorites.

• To re-sequence the tiles, open the team home page and drag tiles to rearrange them to the preferred sequence.

What you can customize for tagging:

• Define tags.

• Enable or disable filtering for a work item list or product backlog page by choosing  Filter.

Implementation notes:

• To view tags assigned to work items in a list, add the Tags field as a column to a backlog page or query.

• You can view tags assigned to work items in Team Explorer, an Excel worksheet or Project plan. However, you cannot modify or create tags using one of these clients.

• You cannot edit or delete tags. However, TFS automatically removes any tag from the system after 3 days of not being referenced by any work item.

How you customize:

• Define and assign tags through a work item form in TWA. See Add tags to work items to categorize and filter work.

What you can customize related to pick lists:

• Define simple pick lists that apply to a single field within a work item type.

• Define global lists that you can use across many work item types and team projects within a project collection.

• Specify allowed, suggested, or prohibited values within either a pick list or a global list.

• Combine lists, restrict to whom a list applies, and set conditions on when a list appears on the work item form.

Implementation notes:

• You can define pick lists only for fields with a data type of Integer or String.

• By using global lists, you can minimize the work that is required to update a list that multiple types of work items share and that are shared by many team projects within a team project collection. Use global lists when you want to enforce common usage across team projects.

• You can define different pick lists for the same field, which appears in different work item types and team projects.

How you customize:

• To define or modify a pick list, modify the field definition for the work item type. See Define Pick Lists.

• To define a global list, modify the definition for the global list maintained for the team project collection. To use the global list, include it within the field definition within the work item type. See Define Global Lists.

What you can customize related to work item fields:

• Add a field to a work item type. You can add a system field, a field defined in another work item type, a custom field, or an integration field.

  For a list of system fields and fields defined within the default process templates TFS provides, see Work Item Field Reference for Visual Studio ALM.

  Integration fields contain information that is generated by automated processes which are managed by Team Foundation Build, Microsoft Test Manager, or Team Foundation version control. See Add Fields to Support Integration with Test, Build, and Version Control.

• Change one of the following field attributes:

  • Friendly name that displays in the work item query. This name may differ from the name that displays on the work item form.

  • Synchronization with Active Directory. You can enable or disable synchronization of fields that are associated with user accounts.

  • Indexing. You can enable/disable indexing of fields, which enhances performance of queries that filter on these fields.

  • Data type. You can change the data type for PlainText or HTML fields to switch from one type to the other.

  • Reporting attributes: You can change the name of the field as it appears in a report, the report reference name, and the reporting type.

    The reporting type determines whether the field's data is written to the relational warehouse database, to both the relational warehouse database and to the cube, or to generate a pre-calculated sum of values when processing the cube. See Perspectives and Measure Groups Provided in the Analysis Services Cube for Team System.

Implementation tips:

• Any field that you want to appear in a report, except system fields, must be defined in the definition file for the types of work items that the field will track.

• To support data entry for a field, you must include the field in both the FIELDS section and the FORM section of the definition of the work item type.

• When you add or modify fields, you should apply systematic naming conventions to make sure that data is logically grouped into folders in the SQL Server Analysis Services cube. See Add and Modify Work Item Fields to Support Reporting.

• All fields defined within work item types are managed at the team project collection level. Errors can result when attributes assigned to a field defined for one team project differs from those assigned to another team project. To manage these errors, see Resolve Schema Conflicts That Are Occurring in the Data Warehouse.

How you customize:

• To add a field, modify the definition for the work item type. See Add a Field and Change the Layout of an Existing Work Item Type.

• To change an attribute of a field, use the witadmin command line tool. See Managing Work Item Fields [witadmin].

Product Backlog Item State Diagram

User Story State Diagram

What you can customize in the workflow for a work item type:

• Add or remove states, transitions, or reasons.

• Change the default reason.

• Restrict the types of modifications that can be made to the work item or a field and by whom, based on the change of state, selection of a reason, or the type of transition being made. See Restrict who can make changes to a work item or to whom a field rule applies.

• Add a custom action during a change of state, transition, or reason. See Automate Field Assignments Based on State, Transition, or Reason.

Implementation notes:

• The drop-down menus for the State and Reason fields display the values assigned in the WORKFLOW section of the work item type.

• If you add a state to a work item type that appears on the backlog or board pages in Team Web Access, and you want that state to appear as a column on the board page, you must also map the state to a metastate.

How you customize:

• To modify the workflow, modify the definition for the work item type. See Design or Customize the Workflow.

• To map workflow states to metastates, modify the definition for the CommonConfiguration.xml file. See Customize Process Configuration.

What you can customize in the Assigned To field :

Limit the list of users who appear in the drop-down menu for the Assigned To field or other custom person-name field.

Implementation notes:

• The most efficient way to apply security restrictions is to create custom groups that you manage either in Windows or in TFS.

• In Team Web Access, the shortcut menus that support assigning work items are limited to members of the team.

How you customize:

1. Create the security group that you want to use and add the accounts to the group. For example, create a new group called Team Contributors. See Change Permissions for a Group or User.

2. Modify the definition file for each work item type that you want to limit the user set. Add the VALIDUSER element to the FIELD element definition for the Assigned To field, and specify the TFS group.

   For example, the following code snippet can be added to the Task definition to limit the set of users for the Assigned To field to only those team members added to the TFS Team Task Group.

   Copy

   <FIELD name="Assigned To" refname="System.AssignedTo" type="String" reportable="dimension" syncnamechanges="true">
      <HELPTEXT>The person currently working on this task</HELPTEXT>
      <ALLOWEXISTINGVALUE />
      <VALIDUSER group="Team Contributors" />
   </FIELD>
   

   By specifying the ALLOWEXISTINGVALUE element, you avoid validation errors that would otherwise occur when members leave the team and are no longer registered as project contributors.

   See Manage Permission to Create or Modify Work Items.

What you can restrict:

• Which field rules are in effect, based on who is modifying the work item. You can apply restrictions to the following rule elements, limiting their applicability to or enforcing them for a group of users. You can specify these rules upon creation or modification of the work item or when changing the state, during a specific transition, or upon selecting a reason:

  • CANNOTLOSEVALUE

  • COPY

  • DEFAULT

  • EMPTY

  • FROZEN

  • MATCH

  • READONLY

  • REQUIRED

  • SERVERDEFAULT

  • VALIDUSER

  For example, with the following code snippet, you can enforce the rule that only members of the Management Team can modify the Stack Rank field once a work item has been created.

  Copy

  <FIELD name="Stack Rank" refname="Microsoft.VSTS.Common.StackRank" type="Double" reportable="dimension">
     <FROZEN not="Management Team" />
     <HELPTEXT>Work first on items with lower-valued stack rank. Set in triage.</HELPTEXT>
  </FIELD>
  

  See All FIELD XML Elements Reference.

• Which field rules are in effect, based on who is modifying the work item and conditional on the value assigned to another field. Conditional rules include WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED. See Assign Conditional-Based Values and Rules.

• Who can modify work items by setting permissions on area paths. See Area and iteration paths.

• Who can modify a field by adding a field rule to the WORKFLOW section. For example, you can restrict all users except those who belong to the Management Team group from making changes to the Story Points field when the work item is set to Resolve by specifying the following syntax:

  Copy

  <STATE value="Resolved">
     <FIELDS>
        <FIELD refname="Microsoft.VSTS.Scheduling.StoryPoints">
           <FROZEN not="Management Team"/>
     </FIELD>
  </STATE>
  

• You can apply field rules and conditional field rules when a user changes the state, makes a specific transition, or selects a reason.

• For the State and Reason fields, you can only apply the READONLY field rule.

• You cannot apply field rules to the Area Path or Iteration Path fields.

Implementation notes:

• The most efficient way to apply security restrictions is to create custom groups that you manage either in Windows or in TFS.

• You can apply restrictions to any system-defined or custom field that you use to assign account names. These fields are referred to as person-name fields. You can enable synchronization between TFS and Active Directory for custom person-name fields. See Managing Work Item Fields [witadmin].

How you customize:

• Modify the definition file for each work item type that you want to place restrictions on. For example, you can limit users who can create a work item by specifying a VALIDUSER group for the Created By field in the WORKFLOW section.

  Copy

  <STATE value="New">
     <FIELDS>
        <FIELD refname="Microsoft.VSTS.Common.CreatedBy">
              <VALIDUSER group="Team Task Group" />
        </FIELD>
             . . .
     </FIELDS>
  </STATE>
  

  In the same way, you can place restrictions on who can resolve, close, or re-activate a work item by adding field rules in the workflow on the following fields: Resolve By, Closed By, or Activated By.

• You can create a global list that specifies which groups are valid and add that to the FIELD definition under ALLOWEDVALUES or PROHIBITEDVALUES.

• You can create custom groups either in TFS or in Windows.

• To place restrictions on which rules apply to a field, specify the for or not attributes within the FIELD child element within the FIELDS section. For example, you can specify that the Required for Release field is READONLY for all users except those in the Team Triage Group.

  Copy

  <FIELD name="Required for Release" refname="MyCompany.ProjectA.RequiredForRelease" type="String" reportable="dimension">
     <READONLY not="Team Triage Group" />
     <HELPTEXT>Specify Yes when true, otherwise leave blank.</HELPTEXT>
  </FIELD>
  

  For more information, see Manage Permission to Create or Modify Work Items.

What you can customize by pattern matching:

• Restrict entries to match a specific pattern.

• Restrict entries to a field to match at least one of a set of patterns.

• Specify users or groups for which the rule applies or does not apply.

Implementation notes:

• You can apply pattern matching to Integer and String fields only.

How you customize:

• Modify the definition file for the work item type with the field that you want to enforce pattern matching. For example, you can enforce entry of a date in the form of month.day.year by specifying the MATCH rule.

  Copy

  <FIELD refname="MyCompany.ProjectA.RequestDate">
     <MATCH pattern="nn.nn.20nn" />
     <HELPTEXT>Enter the date the request was received.</HELPTEXT>
  </FIELD>
  

  See Make a String Field Match a Pattern.