Add or modify a field
Team Services | TFS "15" | TFS 2015 | Previous versions
Your team project contains 100 or more data fields, based on the process --Agile, Scrum, or CMMI-- used to create the team project. You update data by modifying the data field within a work item. Each work item is associated with a work item type (WIT), and the data you can track corresponds to the fields assigned to the WIT.
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.
Feature availability: Feature availability: Platform-dependent tasks are noted as follows:
- Team Services - Visual Studio Team Services (cloud service)
- TFS - Team Foundation Server (on-premises)
Not all pick lists are defined in the same way. Some lists are defined through the user interface, the workflow for a WIT, or by adding user accounts to a team project as indicated in the following table.
|Add a custom field: Date/Time, Decimal, Integer, Text String|| - Customize a field|| - Add a field...|
|Add a custom pick list field: Integer or Text String|| - Customize a field|| - Customize a pick list|
|Customize the pick list for area and iteration paths||- Modify areas, iterations||- Modify areas, iterations|
|Customize the pick list for the State or Reason fields||- Customize the workflow||- Customize workflow|
|Customize the pick list of a person-name field 1||- Add team members||- Add users|
|Customize the pick list of the Resolution State or Failure Type 2||- TCM field mapping tool|
|Customize the pick list for all other fields 3|| - Customize a field, pick list||- Customize a pick list|
|Add a checkbox (boolean) field||- Customize a field|
|Add a custom rich-text, HTML-formatted field 3||- Customize a field|| - Add a field...|
|Specify a field as required or specify a default||- Customize a field||- Add rules|
|Add rules to a field||- Add rules|
|Change a field label or remove a field from a work item form||- Customize a field||- Change a field label|
|Change a field attribute||- Change an attribute|
|Add fields that integrate with test, build, and version control||- Test, build, ...|
|Add a custom control||- Custom controls||- Custom controls|
|Delete a field||- Customize a field, delete||- Delete a field|
- 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 limit the names of accounts in a list, see Limit the number of names that appear in the Assigned To field.
- Resolution State and Failure Type fields are used by Test Manager and the test case WIT.
- Look up the definition of other fields and their default pick lists--such as Activity, Automation Status, Discipline, Priority, plus others--from the index of work item fields.
Add a field, or apply a rule, or change an attribute (TFS)
To add a custom field, add field rules, or change the label of a field on a work item form, you export, edit, and then import the XML definition file for the work item type (WIT).
To change a field attribute or rename a field, use the witadmin command line tool. Otherwise, to modify a field, you add or modify the rules associated with the field within a WIT definition.
To edit a WIT definition file
To add rules or add a custom field, export, edit, and then import the WIT definition file.
Tip: 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.). 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 index.
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.
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|
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.
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 see Define pick lists and Define global lists.
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|
System fields, whose names all start with the "System" prefix (for example, System.ID), are limited in terms of the rules you can apply to them. 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.
For more information about applying field rules and restrictions, see Apply a rule to a work item field.
To add a custom field
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.
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 14.0\Common7\IDE
On a 64-bit edition of Windows, replace
%programfiles(x86)%. You can get access to Team Explorer by downloading Visual Studio Community 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
FIELDelement that specifies the name of the custom field to add. You must specify the following required attributes: friendly
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.Requestorand 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 restrictions and conventions.
Controlelement within the
FORMsection 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>
Tip: The schema definition for work item tracking defines all child elements of the
FORMelement 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 the web portal 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
To modify the field label, change the value assigned to the
Label attribute. To remove a field from the work item form, delete the
Control element associated with the field.
Export the WIT definition file.
witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"
Layoutsections, 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 (TFS)
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.
|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 more information about the OLAP cube, see Perspectives and measure groups.
|Synchronization||You can enable or disable synchronization with Active Directory for fields that are associated with user accounts.|
- Customize the work tracking experience
- Customize cards on boards
- Show bugs on backlogs and boards
- Team Foundation Server - Project Management & Work Item forum
What is a field? How are field names used?
Each work item type is associated with 31 system fields and several more type-specific fields. You use work items to plan and track your project.
Each field supports tracking a piece of information about the work to perform. Values you assign to a field are stored in the work tracking data store which you can create queries to determine status and trends.
A work item field name uniquely identifies each work item field. Make sure your field names fall within these guidelines:
- Field names must be unique within the account/project collection
- Field names must be 128 or fewer Unicode characters
- Field names can't contain any leading or trailing spaces, nor two or more consecutive spaces
- Field names must contain at least one alphabetic character
- Field names can't contain the following characters:
Because custom fields are defined for the account collection, you can't add a custom field to a process with the same field name that you add to another inherited process.
When adding custom fields, note the following limits:
- A maximum of 256 fields can be defined for each WIT
- A maximum of 512 fields can be defined per process
List or review fields
To list or review fields, you can use one of the following tools, depending on the platform you connect to.
|Web portal: List inherited and custom-defined fields|
|Work item field explorer1|
|witadmin listfields command line tool|
- You access this tool from the Process Editor power tool after installing TFS Power Tools.
For an index of fields defined within the default processes, see Work item field index.
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.
For a description of each attribute, see this post: Work Item Field Attributes - What You Can and Can't Change.
Test, build, and version control fields
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.
Field names and reporting
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.
Limit the Assigned To field list of names
By default, the drop-down menu for the Assigned To field displays all users who have been granted access to the team project. This is the default valid users group. The exception to this rule is the list that appears in the web portal--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 a collection or team project group.
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.
See also Restrict access.
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 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.
Delete a field
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.
FIELDdefinition 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.