Customizing Project Tracking Data, Forms, Workflow, and Other Objects

  • Article

You can customize how you track your team project and how you design your workflow, work item forms, and data fields by customizing one or more objects for tracking work items. As the following illustration shows, you can create or customize seven types of objects. You manage categories and work item types for team projects. You manage global lists, link types, and work item fields for team project collections. You can customize global workflow for a team project or a collection.

Work Item Tracking Objects

Note

Before you can define a global workflow, the feature must be enabled on the application-tier server. Therefore, the server must be running a version of Visual Studio Team Foundation Server, such as Team Foundation Server 2010 with Service Pack 1 (SP1), that supports that feature. You can download the service pack from the following page on the Microsoft website: Service Pack 1 of Visual Studio Team Foundation Server 2010, Beta. For more information, see Customizing Global Workflow.

Except for data fields, you can export and import the definitions of each object for tracking work items , from Team Foundation as an XML file. You can create or modify each set of objects to meet your needs.

Note

You can create and modify objects to track work items by using Process Editor, a power tool for Visual Studio. You can use this tool to import and export global lists and types of work item types, modify types of work items, and review the list of fields that are defined for a collection. This tool is not supported. For more information, see the following page on the Microsoft website: Team Foundation Server Power Tools.

Your team members can use work items to track work to be completed on a project. Members can create a work item based on a default work item type such as a bug, a requirement, a risk, or a task. The exact set of default work item types that are available for your team project depends on the process template the team project was created. A work item type is a template from which work items of that type are created. For more information, see Choose a Process Template.

You can add customized types of work items to the default set to make Team Foundation help with the processes that your team uses and the ways in which you communicate. For example, you might want to create work item types for a project-specific bug, a change request, a quality of service requirement, a risk to manage, and a scenario-based task.

After you create a work item, it contains the fields and behavior that were defined in the work item type from which you created it. In addition to creating work item types, you can also modify existing work item types. For example, to better support the processes that your team uses, you can add fields to a work item type or change its workflow behavior.

In this topic

  • Defining and Customizing Objects That Are Used to Track Work

  • Customization Guidelines

  • Related Tasks

Defining and Customizing Objects That Are Used to Track Work

Object

Description

Related topic

Category

A category defines a group of work item types that track similar items of work but are referred to by different names. You can group one or more work item types in the same team project into a category. You define categories to support running queries, generating reports, and setting default work item types in specific instances. You use the In Group operator to find work items that belong to a category. For more information, see Query Fields, Operators, Values, and Variables.

Grouping Work Item Types into Categories

Field

A field defines a type of data that is used to track work. You use work item fields to track data for a work item type, to define the filter criteria for queries, and to generate reports. You must define each data element that is not built in, that the process template does not provide, and that you want to track, use to define the workflow, or appear on the form for a work item type. You define a data element either for a work item type or global workflow by using the FIELD element.

Each field is defined by one or more attributes, which include what type of data it can contain, whether it is used in reporting, and whether it is indexed. You can also specify optional elements that restrict, auto-populate, or specify conditions for the values to which users can set the field by using a work item form.

You can add a field, remove it, or customize how you use it to track data. For information about how to define work items, see Defining and Customizing Data Fields later in this topic.

Defining Work Item Fields

Using System Fields and Fields Defined by the MSF Process Templates

Adding and Modifying Work Item Fields to Support Reporting

Global list

A global list defines a list of values, when is known as a pick list, that you can use across work item types to control the value or values to which users can set a field in a work item. You use global lists to quickly update the contents of pick lists that are used for many types of work items.

You can define global lists within a type of work item type, but this practice is not recommended because the definition of the work item type will overwrite changes that are defined elsewhere if that definition is imported. A best practice is to define and import global lists through a definition file for global lists or global workflow.

Defining Global Lists

Add, Use, and Manage Global Lists

Global workflow

A global workflow defines fields and global lists that are available to all types of work items for either a team project or a collection.

Customizing Global Workflow

Link type

A link type defines the rules and restrictions that control the relationships that users can make between work items. In addition to the built-in types of links, you can create link types to support your project-tracking requirements. Before you start to create links between work items, you should analyze how you might use links to plan your project and track the status of work items.

Customizing How Work Items are Related through Link Types

Choosing Link Types to Effectively Track Your Project

Work item type

A type of work item defines an object, such as a bug, a requirement, or a risk, that is used to track work for a team project. The following components define a type of work item:

  • Fields define the types of data that the work item contains. You can define fields by including a FIELDS (Definition) section in the definition of a type of work item or a global workflow.

  • Workflow defines how a work item progresses from an open or active state to a closed or completed state. You control the workflow by defining its initial state, its valid states, the valid transitions between those states, and the users or groups who have permission to initiate those transitions. The WORKFLOW section of the work item type controls how a work item is tracked.

  • Form defines the layout and contents that appear on the form that team members interact with to track work item data. You can control how user-interface elements appear by updating the FORM section of the definition for the work item type. Each work item type must have only one form. However, you can define one or more layouts for a form to target different clients. You describe the whole form, which includes how all data fields are grouped.

All WITD XML Elements Reference

Defining and Customizing Work Item Workflow

Designing and Customizing a Work Item Form

Add and Customize a Type of Work Item

Create a Work Item Type

Back to top

Planning Your Customization Requirements

You can review the following sections for guidance to inform your planning before you define and customize objects for tracking work.

  • Customization Process Principles

  • System Fields

  • Defining Data Fields and Customizing Types of Work Items

  • Person Named Fields

  • Mapping Fields Between Team Foundation and Microsoft Project

  • Changing Existing Fields

  • Using Global Lists and Global Workflow

Customization Process Principles

When you plan to create or customize objects for tracking work, you should consider incorporating the following processes as much as possible:

  • Establish clear roles and responsibilities, both for those who do the work and those who are present in the workflow of tracking work items.

  • Automate and document changes that you make as you customize objects and modify your deployment.

  • Test your customized objects just as you would test your software.

  • Put process templates and objects under version control. Do not deploy objects that you define but have not stored in a repository.

  • Always introduce changes to a test environment first. Make sure that the objects for tracking work in your test environment are similar or identical to those in your production environment.

Back to top

System Fields

Several system fields are available for reference by all types of work items, even if those fields are not defined explicitly with a FIELD (Definition) element in the definition of every type. Names of system fields all start with the "System" prefix (for example, System.ID). Most of these fields are used for tracking purposes, and users can modify only a few through the user interface. By default, you can use all of the following kinds of fields:

  • Identification fields: Title, Description, and Assigned To. These fields help identify each work item, and users can modify their values through the user interface. These fields are usually included on the form of each type of work item.

  • Tracking fields: ID, Work Item Type, Team Project, Rev, and the fields that provide the number of artifacts that are linked to a work item, such as Attached File Count, External Link Count, Hyper Link Count, and Related Link Count. If you include these fields on a work item form, you should make them read-only. These fields are useful for finding a work item or a set of work items and for generating reports.

  • Audit fields: Created By, Created Date, Changed By, Changed Date, and History. These fields track who created or changed a work item and the date on which it was created or changed. The History field is automatically updated when any field in the work item is modified.

  • Special behavior fields: State, Reason, Area, and Iteration. A specific behavior is associated with each of these fields. The behavior of the State and Reason fields are governed by the workflow mechanism and rules. The Area and Iteration paths are the only TreePath fields that are defined. You define the valid values in the Area and Iterations dialog box for the team project. For more information, see Create and Modify Areas and Iterations.

For more information, see Using System Fields and Fields Defined by the MSF Process Templates.

Back to top

Defining Data Fields and Customizing Types of Work Items

You should consider the following guidelines when you define a data field or a type of work item.

  • Determine the data fields that you require in addition to those that are built in and those that are already defined. For more information about existing fields, see Using System Fields and Fields Defined by the MSF Process Templates. Also, you can export a list of fields that are defined for a project collection by using the witadmin listfields command. For more information, see Managing Work Item Fields [witadmin].

  • Determine whether you must modify existing field rules.

  • Compare the workflow of existing work item types with what your team process needs. First consider the workflow and then the state labels.

  • When you add or customize a field, determine whether you must implement any special logic.

    • Do you need to restrict a field rule to apply only to one or more users or groups?

    • Do you need to restrict a field rule based on a state, transition, or a reason for a transition?

    • Does a field need to be associated with a static or dynamic list of values? What enumerated lists do you need, and how are these shared across work item types and team projects?

      Static lists rarely require updates. Dynamic lists may be based on a set of user names or customer names. Can you use global lists to minimize the time spent updating lists? Can you synchronize a list by using Active Directory and person-named fields?

    • Do you want to define a set of fields that will be used consistently across multiple team projects or types of work items?

      If your team must track fields across multiple types of work items, can you define those fields in a global workflow instead of in each type of work item?

Note

You cannot define a field that calculates data that is contained in more than one field.

For more information, see Defining Work Item Fields.

Back to top

Person Named Fields

You use the String data type to define a field that you use to store person names. If you want to synchronize the list of valid names for this field with those that are stored in Active Directory, you can set the syncnamechanges attribute to true. Also, you can change the attribute of an existing String field to support synchronization of person names. For more information, see Enable Synchronization of Person-Name Custom Fields.

Back to top

Mapping Fields Between Team Foundation and Microsoft Project

If you use Microsoft Project to manage your project schedule, you can define fields and add them to a work item form that you can view or modify from your project plan. If your team project is based on a Microsoft Solutions Framework (MSF) process template, a default mapping file was uploaded when your team project was created.

The Microsoft Project field mapping file determines the mapping of fields between Team Foundation and Microsoft Project. For more information, see Customizing Microsoft Project Field Mappings and Scheduling Tasks and Assigning Resources Using Microsoft Project.

Back to top

Changing Existing Fields

You incur certain expenses when you change data fields after you define them.

All fields that you define, either through a type of work item or a global workflow, are defined for a team project collection. Defining a field is similar to adding a new record to a global database table that contains the friendly name, reference name, and other field attributes for each record. All types of work items in the collection reference this table. Therefore, if you decide to rename a field, modifying an attribute, or delete a field, you affect all types of work items that reference the field.

Also, all reportable data from all team projects in all collections for a deployment of Team Foundation Server is written to a single relational data warehouse. Data from that warehouse is then processed and written to a SQL Server Analysis Services cube. Collecting data into a single data warehouse supports reporting across collections. However, because fields are managed distinctly for each collection, schema conflicts can occur when different definitions are assigned to one or more attributes of a field that is assigned the same reporting reference name.

Moreover, when you add a field to a type of work item and another type has already used the same reference name, you cannot override either the data type or the field name. In addition, the following constraints apply:

  • 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 type of work item. To remove a field, you must explicitly delete it from the collection by using the witadmin deletefield command.

  • Before you delete a field, you should first remove it from the definitions of all types of work items that reference it and any global workflows that reference it.

  • If the deleted field was used for reporting, you will must rebuild the data warehouse to purge the old field and its values.

Back to top

Using Global Lists and Global Workflow

You can simplify your maintenance and customization activities of types of work items by defining some objects as global. Global objects are available to either a team project or project collection. You can add them to process templates to make them available to new team projects or to upload them to other project collections. When you plan, determine how your team projects and types of work items will use global lists and fields.

You can define a global list in the following ways: as part of the definition for a type of work item, as part of a global workflow, or as its own definition file of global lists that you import into a collection. The latter two methods are recommended because you maintain all global lists in one place and avoid inadvertently modifying them when you change an existing type of work item.

You can define a global workflow through an XML definition file and import it for a team project or a collection. Your global workflow can contain field definitions and global lists.

For more information, see Defining Global Lists and Customizing Global Workflow.

Back to top

Tasks

Related content

Understand how to name fields and other objects for tracking work items. You can specify a friendly name for each object with which you track work item. For some objects, you must also specify a reference name. Both types of names must meet the requirements that are defined based on the type of object.

Look up the schema definition for an element of a work item type. You can view the syntax for each schema element that is associated with types of work items.

Identify the best options for customizing work items that support your tracking requirements. When you change objects that track work items, you should identify how these changes will affect existing and future team projects.

Identify what can be localized in the definition of a type of work item. You can localize parts of the definition of a type of work item so that they appear in the user's native language.

Import, export, and manage objects for tracking work items. With the witadmin command-line tool, you can create, delete, import, and export categories, global lists, types of links, types of work items, and work item fields. You manage these objects for each collection or each team project.

See Also

Concepts

What's New in Tracking Work Items

Defining and Customizing Objects for Tracking Work Items By Using the Work Item Tracking Plug-in

Customizing Process Templates

Tracking Bugs, Tasks, and Other Work Items

Customizing Team Projects and Processes

Change History

Date

History

Reason

January 2011

Added illustration to show which objects are defined for a team project as opposed to a collection. Added section about how to plan customization requirements and information about global workflow. Consolidated and reformatted content.

Information enhancement.