Navigating Team Foundation Server 2015: Key Known Issues in Azure DevOps

Table of Contents

Team Foundation Server (TFS) 2015 represented a pivotal release in Microsoft’s Application Lifecycle Management (ALM) suite, offering enhanced capabilities for software development teams. As organizations transitioned and adapted to its features, certain known issues emerged, particularly concerning process customization and identity management. Understanding these challenges is crucial for teams still operating on this version or those migrating to more contemporary platforms like Azure DevOps. This article delves into key known issues from TFS 2015, offering insights and highlighting the nuances of managing a complex ALM environment.

The Evolution of ALM with TFS 2015¶

TFS 2015 was a significant step in the evolution of Microsoft’s ALM offerings, introducing a more modern web interface and deeper integration capabilities. It served as the on-premises counterpart to Visual Studio Team Services (VSTS), which would later become Azure DevOps Services. This version aimed to streamline developer workflows, enhance collaboration, and provide more robust tools for project management, source control, build automation, and testing. However, with the introduction of new features and architectural changes, certain complexities arose, particularly in how customizations interacted with core functionalities.

Managing ALM platforms like TFS requires a deep understanding of their underlying mechanics, especially when customizing them to fit specific organizational needs. Even minor changes to process templates or field definitions can have far-reaching implications across projects and collections. The known issues discussed here underscore the importance of careful planning, thorough testing, and a methodical approach to system administration and customization within the TFS ecosystem. These challenges often illuminate the intricacies of maintaining data integrity and system consistency in a dynamic development environment.

Critical Issue 1: The syncnamechanges Property and Its Impact on Customization¶

One of the prominent issues in Team Foundation Server 2015 revolved around the syncnamechanges property, a crucial attribute for fields within work item type definitions. This property dictates whether changes to a field’s display name are automatically synchronized across the system, impacting how data is stored and displayed. Its deprecation in TFS 2015 led to unexpected challenges, particularly for organizations relying on custom process templates.

Understanding syncnamechanges¶

The syncnamechanges property is a boolean attribute that can be set for a field within a work item type definition. When syncnamechanges is set to true, the system stores a Constant ID for the field’s value rather than the actual string value. This ensures that if the display name associated with that ID changes, all work items referencing that ID automatically reflect the new name. Conversely, when syncnamechanges is false, the actual string value of the field is stored directly on the work item, meaning any display name changes require manual updates or could lead to inconsistencies if not handled carefully.

This property is particularly vital for fields that represent entities with potentially changing names, such as user names, area paths, or iteration paths. Proper management of syncnamechanges ensures data integrity and consistency across the entire TFS collection. Misconfiguring this property can lead to stale data, incorrect reporting, and a frustrating user experience, especially in large, collaborative environments. Therefore, understanding its behavior is fundamental to effective TFS administration.

The Deprecation and Its Consequences¶

In Team Foundation Server 2015, Microsoft made the decision to deprecate the ability to change the syncnamechanges property on a field. This change, while seemingly minor, had significant repercussions for specific customization scenarios. The immediate consequence was that users could no longer create new project collections that would successfully integrate certain types of custom process templates. This restriction fundamentally impacted the flexibility of project creation for organizations with established custom processes.

The deprecation created a conflict point when custom processes tried to coexist with Out-Of-The-Box (OOB) templates in new collections. It essentially limited the ability to deviate from the syncnamechanges property settings dictated by the OOB templates. This situation often led to errors during project creation, halting the process and requiring administrators to seek workarounds. The decision aimed at streamlining field management but inadvertently introduced a new set of challenges for advanced users.

The Conflict Scenario: Custom vs. OOB Templates¶

The core of the problem manifested when specific conditions were met during project creation. Consider a scenario where an organization had uploaded a custom process template to a new collection. This custom template might have defined a field that shared the exact same reference name as a field in an OOB template, but with a critical difference: the syncnamechanges property for that shared field was set to false in the custom template, while the OOB template implicitly expected it to be true.

When an attempt was made to create a new project using this custom process template, TFS 2015 would encounter a conflict. The system, unable to reconcile the differing syncnamechanges settings for the identically named reference field, would prevent project creation. This created a significant hurdle for teams attempting to standardize their processes while maintaining legacy customizations from previous TFS versions. Such conflicts often required deep investigation into the XML definitions of process templates.

Table: syncnamechanges Property Behavior¶

Property Value	Storage Mechanism	Impact on Name Changes	Use Case
syncnamechanges=true	Stores Constant ID	Automatic synchronization of display names	Users, Area Paths, Iteration Paths, System Fields
syncnamechanges=false	Stores Direct String Value	Manual updates required; potential inconsistencies	Custom fields where historical string value is paramount

Workarounds and Resolution¶

Before the full resolution arrived, teams facing this syncnamechanges conflict had a couple of viable workarounds. One direct approach involved updating the custom process template itself. This required modifying the XML definition of the conflicting field within the custom template to match the syncnamechanges property of the OOB template. Once updated, the revised custom template could then be uploaded to the new collection, resolving the conflict during project creation.

Alternatively, for situations where direct template modification was not feasible or too complex, contacting Customer Support was an option. Microsoft support teams could provide a script specifically designed to fix the conflicting fields within the collection. This script-based solution offered a more hands-off approach for administrators, leveraging internal tools to align the problematic field properties. Both workarounds aimed at achieving consistency in the syncnamechanges property, allowing project creation to proceed.

Restoration in Update 1¶

Recognizing the impact and the challenges faced by users, Microsoft restored the ability to change the syncnamechanges property in TFS 2015 Update 1. This restoration was a welcome relief for many organizations, providing renewed flexibility in customizing process templates without encountering the earlier conflicts. It allowed administrators to once again define their custom processes with confidence, knowing that the field property management was back to its original behavior.

The reintroduction of this capability highlighted Microsoft’s responsiveness to user feedback and their commitment to supporting diverse ALM strategies. It also underscored the delicate balance between introducing new features and maintaining backward compatibility with existing customization practices. For teams using TFS 2015, upgrading to Update 1 or later was essential to mitigate this specific issue and ensure smoother process template management.

Mermaid Diagram: syncnamechanges Conflict Flow¶

mermaid graph TD A[Upload Custom Process Template] --> B{Field with Shared Reference Name?}; B -- Yes --> C{Custom Template: syncnamechanges=false?}; C -- Yes --> D{OOB Template: syncnamechanges=true?}; D -- Yes --> E[Conflict Detected]; E --> F[Project Creation Fails]; F --> G[Workaround 1: Update Custom Template]; F --> H[Workaround 2: Contact Customer Support]; G --> I[Re-upload Template & Create Project]; H --> I; B -- No --> I; C -- No --> I; D -- No --> I; I[Project Created Successfully];

Critical Issue 2: Identity Fields and Client Object Model Challenges¶

Another significant area of known issues in Team Foundation Server 2015 revolved around the introduction of “identity fields” and their interaction with the client object model. This change aimed to resolve long-standing problems with ambiguous user display names but inadvertently created new challenges for client-side applications and integrations.

Introducing Identity Fields¶

TFS 2015 brought about the concept of an identity field, a crucial enhancement designed to improve how user identities are managed within work items. A field is designated as an identity field if it contains any rules that relate to identities, such as the <ValidUser /> rule. This innovation was primarily driven by the need to accurately differentiate between users who might share identical display names, a common issue in larger enterprises. Previously, if two users named “Sean Contoso” existed in the system, it was difficult to distinguish them based solely on their display name in work items.

The introduction of identity fields provided a more robust mechanism for unique user identification. By treating these fields specially, TFS could store more precise identity information, moving beyond just display names. This change was a fundamental improvement for data accuracy and auditing, ensuring that actions and assignments within work items could be definitively traced back to a unique user entity. It represented a foundational step towards more reliable identity management within the ALM ecosystem.

Resolving Duplicate Display Names¶

The primary motivation behind identity fields was to overcome the problem of duplicate display names. In earlier TFS versions, if multiple users shared the same first and last name, work items referencing these users would display an ambiguous name, leading to confusion. With identity fields, the system adopted a new strategy for storing and displaying identity-related information. Instead of just storing “Sean Contoso,” the DisplayPart for an identity field would now include more context, such as ‘Sean Contoso scontoso@microsoft.com’ or ‘Sean Contoso ‘.

This new format ensures that each identity is uniquely identifiable, even if display names are similar. For example, ‘Sean Contoso scontoso@microsoft.com’ clearly distinguishes from ‘Sean Contoso scontoso@contoso.com’ or ‘Sean Contoso ‘. This enhanced specificity significantly improves the clarity and reliability of user assignments and historical tracking within work items. It also helps in scenarios where users might change their display names, as the underlying unique identifier remains consistent.

syncnamechanges and Identity Field Storage¶

The way identity fields store their values is also intricately linked with the syncnamechanges property. If syncnamechanges=true is set for an identity field, TFS stores the Constant ID of the user’s value, not the actual string representation. This means that if a user’s display name changes, all work items referencing that user via the Constant ID will automatically reflect the new name without any manual intervention. This behavior aligns with the goal of maintaining data consistency for system-managed entities.

However, if syncnamechanges=false is set for an identity field, the system directly stores the string value on the work item. In the context of identity fields, this string value would be the new, expanded DisplayPart format, such as ‘Sean Contoso scontoso@microsoft.com’. While this might seem straightforward, it creates a specific challenge when interacting with the client object model. The direct storage of the detailed string value becomes the root cause of the client-side issues, as the client expects a different format.

The Client Object Model Impasse¶

The issue primarily arises because the client object model, responsible for interpreting and displaying work item data in various client applications (like Visual Studio or custom tools), is not always prepared for the new DisplayPart format. When syncnamechanges=false is set for an identity field, the system returns the raw string value (e.g., ‘Sean Contoso scontoso@microsoft.com’) directly to the client. The client-side rule engine, which validates field values based on predefined rules, often expects a simpler display name or a specific ID format.

Consequently, when the client receives ‘Sean Contoso scontoso@microsoft.com’ for a field where it expects just ‘Sean Contoso’ or a GUID, it treats the value as invalid. This mismatch can lead to a variety of problems, including validation errors in the UI, inability to save work items, or incorrect display of user information. Developers building custom applications or integrations using the TFS client object model must be aware of this behavior and implement specific parsing logic to handle the expanded identity format gracefully, ensuring their applications remain functional and robust.

Best Practices for Managing TFS 2015 Customizations¶

Navigating these known issues in TFS 2015 underscores the importance of robust ALM practices. To mitigate such challenges and ensure a smooth operational environment, consider the following best practices:

1. Thoroughly Test Customizations: Before deploying any custom process templates or making significant changes to field definitions, thoroughly test them in a non-production environment. This includes testing project creation, work item creation, and various user scenarios to identify potential conflicts.
2. Version Control Process Templates: Treat your custom process templates as code and store them in version control. This allows for tracking changes, reverting to previous versions, and collaborating on template modifications. Having a robust history can be invaluable when troubleshooting issues.
3. Understand Reference Names: Pay close attention to field reference names, as they are central to TFS’s internal data model. Avoid creating custom fields with reference names that might conflict with existing OOB fields, even if display names differ. Always use unique and descriptive reference names.
4. Stay Updated with Service Packs and Updates: Microsoft frequently releases updates and service packs that address known issues and introduce improvements. Ensure your TFS 2015 instance is running the latest available update (e.g., Update 1 or later) to benefit from crucial bug fixes like the syncnamechanges restoration.
5. Leverage Official Documentation and Community Forums: Microsoft’s official documentation and community forums are excellent resources for understanding TFS behavior and troubleshooting common issues. Engaging with the community can provide insights and solutions from other experienced administrators.
6. Plan for Upgrades: TFS 2015 is an older version, and while these issues have workarounds or fixes, the platform itself is no longer actively developed. Plan for a migration path to Azure DevOps Server or Azure DevOps Services to leverage the latest features, security updates, and a more stable, modern ALM experience.

The Path Forward: From TFS 2015 to Azure DevOps¶

While TFS 2015 provided essential ALM capabilities, the platform has evolved significantly into Azure DevOps. Many of the intricacies and challenges faced in older TFS versions, such as the syncnamechanges property and identity field handling, have been streamlined or re-architected in modern Azure DevOps releases. The continuous development and cloud-first approach of Azure DevOps services offer greater flexibility, scalability, and simplified management.

Organizations still relying on TFS 2015 should actively plan their migration to Azure DevOps Server or Azure DevOps Services. This transition not only provides access to a wealth of new features, improved performance, and enhanced security but also alleviates many of the legacy issues that required complex workarounds. The lessons learned from TFS 2015, particularly concerning the delicate balance of customization and system integrity, have undoubtedly informed the design and robustness of the Azure DevOps platform.

If you are encountering these or other issues with your TFS 2015 instance, or if you are considering migrating to a newer platform, don’t hesitate to share your experiences. What challenges have you faced, and how have you overcome them? Your insights can be invaluable to the broader community navigating the complexities of ALM systems.