Share via

Things to avoid when customizing TFS work items

  • Article

Recently I have had several customers looking for guidance on what TFS work item customization's are "safe". Not all organizations can quickly upgrade to the newest version of Team Foundation Server when it is released. They need to go through an approval and testing process to ensure that the upgrade does not cause any extended downtime or loss of work. So if certain work item customization's are going to increase the risk of potential problems when doing upgrades, they want to know what to avoid. I reached inside the different groups at Microsoft and was able to come up with a list of things to pay special attention.

General Rules //

  • First, avoid customization in the first place if possible, consider alternative approaches for accomplishing what you want by using things like Tags

  • Avoid customizing the FIELD definitions of system fields (with refNames in System.* namespace)

  • Be careful about process fields (with refNames in Microsoft.VSTS.* namespace) as they might be required by some features. Some examples:

    • Microsoft.VSTS.Common.Activity

    • Microsoft.VSTS.Common.StackRank

    • Microsoft.VSTS.Scheduling.RemainingWork

    • Microsoft.VSTS.Scheduling.StoryPoints

 Adding New Fields //

  • Use the right data type for the FIELD as it’s problematic to change it later; same guidance applies to the display name of the field

  • Use proper namespaces for the refNames of fields to avoid possible conflicts with other custom fields

  • Regarding the form layout, consider putting all your custom fields in a separate TAB. If this is not feasible, try other ways of grouping them all together in the same container such as a COLUMN for better maintainability

  • Think about the reporting story and whether you’d like your custom fields to be available in the reporting warehouse/cube

Field Validation Rules //

If you’re adding more strict validation rules, keep in mind that existing work items might become “invalid” as they wouldn't meet the requirements in the rule. That’s usually OK, but those work items will display validation errors first time someone pens them in the UI, and those validation issues would need to be fixed before the work item can be saved.

Removing Fields //

 If you don’t want a field to show up on the work item form, consider removing the CONTROL instead of the FIELD definition. The field will still be there (and accessible by the API), but it won’t be visible on the form.

 Work Item Types //

Adding work item types is typically a safe customization, as everything is isolated in its own container. Keep in mind that the field definitions are “shared” across work item types; so starting from an existing work item type is a good practice to reuse the definitions, workflow model and layout.

However, removing work item types is usually risky. Some work item types are required by some tools and features, so if you accidentally remove those work item types, it’s likely that you’ll break something. Here’s a few examples:

  • Code Review - Code Review Request, Code Review Response

  • Test Case Management - Test Case, Shared Steps

  • Feedback - Feedback Request, Feedback Response

  • Agile - User Story, Task

Also, be cautious when changing the name of a work item. The biggest concern is the potential to break existing queries that use the name of that type.

Workflows //

In general try to avoid making changes to the workflows . If you absolutely have to and you’d like to enforce your business rules through workflow customization, try to keep it flexible without too rigid of rules. For example, the state transition models work better when you enable transition from any state to any state.

Note that the metastate mappings, defined in the ProcessConfiguration file (for TFS 2013), need to be in place for any workflow customizations you make to a WIT definition.

Default Categories //

Avoid removing any of the default categories, if you do, you can have problems. The Agile Planning tools rely on almost all of the default categories that are defined in the TFS process templates.

Configuration Features Wizard //

The configuration features wizard depends on specific items being available after doing the upgrade. If those elements are changed the Configuration Features wizard will fail. For more information on Configuration Features wizard check out the Configurations feature after TFS upgrade page. Pay particular attention to the second question in the Q&A section (Q: To run successfully, which elements does the Configure Features wizard depend on?)

Final Notes //

There are rumors of Microsoft making additional improvements to the customization story that will help avoid breaking TFS when doing the upgrade. However, for now, these are the general guidance bullets I was able to pull together.

I also recommend taking a look at the Team Foundation Server Process Template Customization Guide developed by the ALM Rangers to help guide your TFS customization experience.

Finally, make sure you check out the TFS Power Tools. The Process Template Editor provides a nice user interface for customizing work items and process templates.

Special thanks to my colleagues Hakan Eskici and Kathryn Elliott who provided the majority of the content in this blog post.