Modify or add a field to support queries, reports, and workflow

Article
04/21/2015

Your team project contains 100 or more data fields, based on the process template used to create the team project. Each field is associated with a pair of names, attributes, and rules. You can modify an existing field or add a custom field to support tracking additional data requirements. For example, you can customize the pick list within a drop-down menu, add a rule to specify a default value or restrict the value it can take, or change a field attribute.

To add field rules, add a custom field, or change the label of a field on a work item form, you edit the XML definition for the work item type (WIT). To change a field attribute or rename a field, use the witadmin command line tool.

Field definition names, attributes, and rules

Customize a pick list

Pick lists are the enumerated values that appear within a drop-down menu in a work item form and the Value column within the query editor. The method you use to customize a pick list varies depending on the field.

Generic string or integer fields

To modify the pick list for most string or integer fields within a work item form, edit the WIT definition. For example, to add a custom Resolution field and pick-list, specify the XML code as shown.

Custom field and pick list

Pick list for a custom field

<FIELD name="Resolution" refname="MyCompany.Resolution" type="String">    
<ALLOWEDVALUES>
   <LISTITEM value="By Design" />
   <LISTITEM value="Duplicate" />
   <LISTITEM value="External" />
   <LISTITEM value="Fixed" />
   <LISTITEM value="Not Repro" />
   <LISTITEM value="Postponed" />
   <LISTITEM value="Won’t Fix" />
</ALLOWEDVALUES>
</FIELD>

Rules support combining lists, restricting to whom a list applies, and setting conditions on when a list appears on the work item form. Rules control whether a distribution list is expanded to show its individual members or a list is filtered by using the optional expanditems and filteritems attributes. Use global lists to minimize the work that is required to update a list that is shared across WITs or team projects.

To learn more, see Define pick lists and Define global lists.

Specific fields whose pick lists are defined by other means

To modify the pick lists for the following fields, see the respective topic:

Area and Iteration: Add and modify area and iteration paths.
State and Reason: Customize the workflow.
Assigned To or other person-named fields: Add the user account to a valid TFS security group.

To add values for fields associated with user accounts such as Assigned To add users to a TFS security group or by restricting access to a group or set of users. By default, the list for the Assigned To field contains the account names for all users and groups that have been added to TFS. These accounts are often synchronized with Active Directory. See Set up groups for use in TFS deployments.
Resolution States or Failure Types (used by Test Manager): tcm fieldmapping tool.

For all other fields that have pick lists associated with them─such as Activity, Automation Status, Discipline, Priority, plus others─you can look up the definitions of these fields from the index of work item fields.

Add rules to a field

To add a custom field or add rules to a field, edit the WIT definition. You can limit rules to apply to specific users or groups. Most rules support the for or not attributes to focus who the rule does and doesn’t apply to.

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

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

You apply rules to accomplish the following actions:

To accomplish this action:	Use this XML element:
Specify a tool-tip.	HELPTEXT
Qualify the value a field can have.	CANNOTLOSEVALUE, EMPTY, FROZEN, NOTSAMEAS, READONLY, and REQUIRED
Copy a value or specify a default.	COPY, DEFAULT, and SERVERDEFAULT
Restrict who can modify a field.	VALIDUSER, for and not field rule attributes
Enforce pattern matching on a string field.	MATCH
Conditionally apply rules based on values in other fields.	WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED

For more information about applying field rules, see All FIELD XML elements reference.

Edit the WIT XML definition file to add rules or add a custom field

To add rules or add a custom field, export, edit, and then import the WIT definition file.

Process for customizing a WIT object

With witadmin, you can import and export definition files. Other tools you can use include the Process Editor, available with the download of TFS Power Tools, or TFS Team Project Manager, a community resource project available on CodePlex.

Any field that you want to use to track data must be added to the WIT definition file. This is true for all but system fields (fields whose reference name start with System.) which are automatically defined for every WIT.

To add a custom field, edit the WIT definition to add a FIELD element within the FIELDS section and a Control element within the FORM section.

To add a custom field

If you don't have project administrator permissions for your team project, get them.
Open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:

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

On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%. You can download Team Explorer for free.
Export the WIT definition.

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

An example of a CollectionURL is http://fabrikamprime:8080/tfs/DefaultCollection.
Locate the section of the XML file that defines the fields for the type and that begins with FIELDS.
Add the FIELD element that specifies the name of the custom field to add. You must specify the following required attributes: friendly name, refname (reference name), and type. For more information, see FIELD (Definition) element reference.

The following code specifies the custom field, Requestor, with a reference name of FabrikamFiber.MyTeam.Requestor and a pick list of allowed values, with the default value of Customer.
```
<FIELD name="Requestor" refname="FabrikamFiber.MyTeam.Requestor" type="String" reportable="Dimension">
   <ALLOWEDVALUES>
      <LISTITEM value="Customer" />
      <LISTITEM value="Executive Management" />
      <LISTITEM value="Other" />
      <LISTITEM value="Support" />
      <LISTITEM value="Team" />
      <LISTITEM value="Technicians" />
      <DEFAULTVALUE value="Customer" />
    </ALLOWEDVALUES>
</FIELD>
```
Tip

Elements within the list always appear in alphanumeric order, regardless of how you enter them in the XML definition file.

The Reference Name, or refname, is the programmatic name for the field. All other rules should refer to this refname. For more information, see Naming conventions for work item tracking objects.
Add the Control element within the FORM section so that the custom field appears on the form within the group of elements where you want it to appear.

For example, the following code snippet adds the Requestor field to appear below the Reason field on the work item form.
```
<Column PercentWidth="50">
   <Group Label="Status">
      <Column PercentWidth="100">
         <Control FieldName="System.AssignedTo" Type="FieldControl" Label="Assi&amp;gned To:" LabelPosition="Left" />
         <Control FieldName="System.State" Type="FieldControl" Label="&amp;State:" LabelPosition="Left" />
         <Control FieldName="System.Reason" Type="FieldControl" Label="Reason:" LabelPosition="Left" ReadOnly="True" />
         <Control FieldName="FabrikamFiber.MyTeam.Requestor" Type="FieldControl" Label="Requestor:" LabelPosition="Left" ReadOnly="True" />
      </Column>
   </Group>
</Column>
```
Tip

The schema definition for work item tracking defines all child elements of the FORM element as camel case and all other elements as all capitalized. If you encounter errors when validating your type definition files, check the case structure of your elements. Also, the case structure of opening and closing tags must match according to the rules for XML syntax.

For more information, see Control XML element reference.
Import the WIT definition file.

witadmin importwitd /collection:CollectionURL /p:ProjectName /f:"DirectoryPath/FileName.xml"
Open either TWA or Team Explorer to view the changes. If the client is already open, refresh the page.

The following illustration shows that the work item form for the product backlog item now contains the new field.

For more information about using witadmin, see Import, export, and manage work item types [witadmin].

To change the field label on a work item form

Export the WIT definition file.

witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"
In the FORM and Layout sections, find the definition of the field you want to modify. This example modifies the label for the Title field:
```
<Column PercentWidth="70">
  <Control Type="FieldControl" FieldName="System.Title" Label="Title" LabelPosition="Left" />
</Column>
```
Change the label for the field so that the Portuguese branch office working on this particular team project can read the name of the Title field when they work with the work item form. Include the Portuguese word for title (Titulo) in the Title field.
```
<Column PercentWidth="70">
  <Control Type="FieldControl" FieldName="System.Title" Label="Title (Título):" LabelPosition="Left" />
</Column>
```
Import the WIT definition file.

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

Change an attribute of an existing field

You use witadmin changefield to change the attributes of an existing field. For example, the following command changes the friendly name defined for MyCompany.Type to Evaluation Method.

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.Type /name:"Evaluation Method"

The following table summarizes the attributes you can change using witadmin changefield.

Attribute	Description
Data type	Specifies the type of data that the field accepts. In general, you cannot change the field data type once it is defined. You can switch the field data type only for fields of type HTML or PlainText.
Friendly name	The friendly name appears in the drop-down menus of work item queries and it must be unique across all fields that are defined within a team project collection. The friendly name may differ from the form label that appears on the work item form.
Indexable	You can enable indexing for a field to improve query response times when filtering on the field. By default, the following fields are indexed: Assigned To, Created Date, Changed By, State, Reason, Area ID, Iteration ID, and Work Item Type.
Reporting attributes	You can change the name of the field as it appears in a report, the report reference name, and the reporting type. You can localize the reporting friendly name. 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 OLAP cube, or to generate a pre-calculated sum of values when processing the OLAP cube. For a complete list of the default reportable fields, see Reportable fields reference for Visual Studio ALM. For more information about the OLAP cube, see Perspectives and measure groups provided in the Analysis Services cube for Visual Studio.
Synchronization	You can enable or disable synchronization with Active Directory for fields that are associated with user accounts.

Q & A

Q: What customizations can I make and still use the Configure Features Wizard to update my team project after a TFS upgrade?

A: You can add custom fields, customize a pick list, add or modify area and iteration paths, and add rules to a field. The Configure Features Wizard will update your team projects and you’ll get access to the latest features.

To learn about other customizations that you can safely make and which you should avoid, see Customize the work tracking experience: Before you customize, understand the maintenance and upgrade implications.

Q: Where can I learn about all the fields and field attributes already defined for my team project?

A: For an index of fields defined within the default TFS process templates, see Work item field reference for Visual Studio ALM.

In addition to the attributes that you can change for a work item field, there are several non-changeable and virtually hidden attributes for each field. You can look up the assignments of these fields using the Work Item Field Explorer tool. You access this tool from the Process Editor power tool after installing TFS Power Tools.

Work Item Field Explorer

Work item field explorer

For a description of each attribute, see this post: Work Item Field Attributes - What You Can and Can't Change.

Q: How do I add a field that supports integration with test, build, and version control?

A: Several WITs contain fields that provide information that is generated by automated processes that integrate with Team Foundation Build, Microsoft Test Manager, and Team Foundation version control. To add one of these fields to your custom WITs, you edit the WIT definition according to the steps outlined previously in this topic.

For example, you can add the Found In and Integrated in Build fields that appear in the type definitions for bugs. These fields associate bugs with the builds where they were found or fixed. You can use the following code snippet to add these fields to a work item type definition.

<FIELD name="Found In" refname="Microsoft.VSTS.Build.FoundIn" type="String" reportable="dimension">
    <HELPTEXT>Product build number (revision) in which this item was found</HELPTEXT>
</FIELD>
<FIELD name="Integration Build" refname="Microsoft.VSTS.Build.IntegrationBuild" type="String" reportable="dimension">
    <HELPTEXT>Product build number this bug was fixed in</HELPTEXT>
</FIELD>

For more information, see Fields that support integration with test, build, and version control.

Q: When should I use a global list instead of a simple pick list?

A: When you use a list in several WITs or across several team projects, maintaining it as a global list minimizes your maintenance requirements. Also, if you need to have parts of lists show up as different across WITs or team projects, you can define a global list for part of a pick list. See Define pick lists and Define global lists.

Q: Are their restrictions on modifying System fields?

A: Yes. You can’t rename System fields, and you can’t apply some rules to System fields. For example, you can’t copy or set to empty fields used to track who created, changed, or closed a work item, or date-time fields used by the system.

System field names all start with the "System" prefix (for example, System.ID). All System fields are defined for all WITs, whether or not you include them in WIT definition. To learn more about each field, see Work item field reference for Visual Studio ALM.

Q: Is there a sequence in which rules are evaluated?

A: Yes, however, several factors impact how the system evaluates multiple rules in such a way that the end result cannot always be fully known at the outset. To gain some idea of expected behavior and interactions, see Apply a rule to a work item field.

Q: How should I name fields to support reporting?

A: You can add fields or change the attributes of existing fields to support reporting. When you add or change fields, you should name them systematically so that you can find the field in the Analysis Services cube because the fields are logically grouped into folders. To learn more, see Add or modify work item fields to support reporting.

Q: Is there a way to limit the number of names that appear in the Assigned To field?

A: Yes. By default, the drop-down menu for the Assigned To field displays all users who have been granted access to TFS. This is the default valid users group. The exception to this rule is that in Team Web Access, the context menus that support assigning work items are limited to members of the team.

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

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 Add users to team projects.
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.
```
<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.

Q: How do I add custom controls to a field?

A: Using the object model for tracking work items, you can programmatically create, change, and find bugs, tasks, and other WITs. You can also create your own custom controls that add functionality to a work item form.

For example, you can add the following custom controls which are available through the Custom Controls for TFS Work Item Tracking CodePlex project:

Screenshot control that allows a cut-and-paste operation of images into an HTML field.
Web browser control that allows a user to host a web page and pass field values to that webpage.
Multi-value control that supports input multiple values for a field by showing a list of check boxes.

Q: How do I change the field mappings that support Project-TFS integration?

A: Team projects created from a default TFS process template include a default Microsoft project mapping file. If you use Project to plan and track work items stored in TFS, you might need to map additional Project fields or change the way a TFS field is published and refreshed. You can do this by customizing the Microsoft Project Mapping file.

To learn about using Project with TFS work items, see Create your backlog and tasks using Project.

Q: What’s the best way to manage a large number of custom fields?

A: If you need to add a large number of custom fields that will be used in several WITs or across several team projects, use global workflow. You can simplify maintenance operations by maintaining your global set of fields and pick lists using global workflow. See Global Workflow XML Element Reference.

Q: How do I delete a field?

A: When you remove a field from a specific type of work item, that field is not removed from the collection or the database server, even if it is no longer referenced by any WIT. To remove a field, follow these steps.

Remove the FIELD definition from all WIT definitions and any global workflows that reference it.

Verify the field is not in use. For example:

witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomContact

Field: MyCompany.CustomContact
Name: Custom Contact
Type: String
Reportable As: dimension
Use: Not In Use
Indexed: False

Delete the field. For example:

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomContact

If the deleted field was reportable, rebuild the data warehouse to purge the old field and its values.

For more information, see Manage work item fields [witadmin].

Q: What other areas can I customize?

A: See An end-to-end view of what you can configure and customize in Visual Studio TFS.

Q: Where can I go if I have more questions?

A: To find answers or post a question, visit the forum: Team Foundation Server - Project Management & Work Item.