Add or modify a field to support queries, reports, and workflow
There are several reasons why you might want to modify an existing field or add a custom field. For example, you need to change the name of a field, modify the pick list within the drop-down menu, or add a field to track additional data requirements.
Adding a field with a custom pick list is a common task. In the following illustration, an additional field, Resolution, has been added with a custom list of resolutions.
Most modifications require editing the definition for the work item type (WIT). You accomplish other modifications through the user interface (Team Web Access), or a command-line tool.
The method you use to customize a pick list varies depending on the field.
To add values to the Area or Iteration path fields, go here.
To add values to the State or Reason fields, modify the workflow.
To add or change values to the Resolution States or Failure Types used by Test Manager, go here to use the tcm fieldmapping tool.
To modify the pick list for all other string or integer fields within a work item form, edit the WIT definition according to the steps outlined later in this topic. For example, to add the pick list for the Resolution field shown in the illustration at the top of the page, you would add the following XML code:
<FIELD name="Resolution" refname="MyCompany.Resolution" type="String" reportable="Dimension" <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>
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 later 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.
To add a custom field or add rules to a field, you edit the WIT definition according to the steps outlined later in this topic. You apply rules to accomplish the following actions:
Change the tooltip of a field using HELPTEXT.
Qualify the value a field can have by specifying CANNOTLOSEVALUE, EMPTY, FROZEN, NOTSAMEAS, READONLY, and REQUIRED.
Copy a value into a field by using COPY, DEFAULT, and SERVERDEFAULT.
Restrict who can modify a field by specifying the VALIDUSER element.
Enforce pattern matching on a string field by using MATCH.
Conditionally apply rules based on values in other fields using WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED.
Apply a rule only when you change state, specify a reason, or during a workflow transition. For example, by adding the EMPTY rule when the state is set to Active, the Closed Date and Closed By fields are automatically set to null and made read-only. This is useful when reactivating a WIT from a closed state.
<STATE value="Active"> <FIELDS> . . . <FIELD refname="Microsoft.VSTS.Common.ClosedDate"><EMPTY/></FIELD> <FIELD refname="Microsoft.VSTS.Common.ClosedBy"><EMPTY/></FIELD> </FIELDS> </STATE>
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 more information about applying field rules, see All FIELD XML elements reference.
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, you edit the WIT definition to add a FIELD element within the FIELDS section and a Control element within the FORM section.
To add a field to a work item type
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 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.
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>
Elements within the list always appear in alphanumeric order, regardless of how you enter them in the XML definition file.
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&gned To:" LabelPosition="Left" /> <Control FieldName="System.State" Type="FieldControl" Label="&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>
For more information, see Control XML element reference.
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.
The following illustration shows that the work item form for the product backlog item now contains the new field.
You use witadmin changefield to make the following changes to an existing field:
Friendly name: The friendly name appears in work item queries. 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"
To change the label shown on the work item form, customize the work item form.
Reporting attributes: You can assign a value of Detail, Dimension, or Measure to the Reportable attribute to add fields to the data relational warehouse database, to the cube, or both.
Reporting attributes are only valid when for on-premises deployments with SQL Server Analysis Services.
Synchronize a field with Active Directory: String fields that are used to store person names should have the syncnamechanges attribute set to true. This setting indicates that the contents of the field should be updated as changes are made to person names in Active Directory or a workgroup.
Indexing. Enabling indexing for a field may increase the performance of running queries that specify that field in the filter criteria. If you add a custom field that you use in many of your work item queries, you might want to enable indexing for that field.
Data type: You can change the data type for a PlainText or HTML field. If you use Excel to perform bulk updates of text fields, you might want to change an HTML field to PlainText.
For more information, see Manage work item fields [witadmin].
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.
To edit process configuration, you export, edit, and then import the process configuration file.
If you don't have administration 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 file where you want to modify or add a field. Specify the name of the WIT and a name for the file.
witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"
An example of a CollectionURL is http://fabrikamprime:8080/tfs/DefaultCollection.
For more information about using witadmin, see Import, export, and manage work item types [witadmin].
Edit the file. For details, see Work item tracking: Index to XML element definitions.
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.
A: Yes. With witadmin, you can import and export definition files as shown in this topic. Other tools you can use to modify the XML syntax for an object include the Process Editor, available with the download of TFS Power Tools, or TFS Team Project Manager, a community resource project available on CodePlex.
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.
For a description of each attribute, see this post: Work Item Field Attributes - What You Can and Can't Change.
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.
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 How rules are evaluated.
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.
A: To find answers or post a question, visit the forum: Team Foundation Server - Project Management & Work Item.