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.
In the following illustration, an additional field, Resolution, has been added with a custom list of resolutions.
In this topic
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.
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.
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 values to 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.
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. For example, you can enforce entry of a date in the form of month.day.year by specifying the MATCH rule.
<FIELD refname="MyCompany.ProjectA.RequestDate"> <MATCH pattern="nn.nn.20nn" /> <HELPTEXT>Enter the date the request was received.</HELPTEXT> </FIELD>
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 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.
<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>
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
Export the WIT definition file using witadmin exportwitd.
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.
To customize a field label on a form, export the WIT XML file and modify the CONTROL element for the field.
Export the WIT definition file using witadmin exportwitd.
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 using witadmin importwitd.
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.
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.
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.
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.
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 felds 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.
You can enable or disable synchronization with Active Directory for fields that are associated with user accounts.
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.
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 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: 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.
A: To find answers or post a question, visit the forum: Team Foundation Server - Project Management & Work Item.