Home
Planview Hub
Connector Documentation
Microsoft Azure DevOps Server

Microsoft Azure DevOps Server

Last updated
Save as PDF

Overview

Microsoft Azure DevOps Server (formerly TFS) provides work item tracking, source control and Agile project management for the software delivery lifecycle.

Many organizations, particularly those building for Microsoft platforms, use Azure DevOps Server as their planning and reporting center. However, when members of the extended software development and delivery tool adopt specialist tools, the reports from Azure DevOps Server no longer reflect up-to-the-minute data.

For example, if the testing team chooses to use Micro Focus ALM/Quality Center as their test and defect tracking solution, the development team needs access to the information in the defect tracker to triage bug reports. Or, if the business analysts use a purpose-built requirements management tool such as IBM DOORS, DOORS Next Generation or Jama, the developers using Azure DevOps Server would prefer to see these reflected as stories in Azure DevOps Server. And if one development team uses Jira to manage their work, the collaboration between the teams using Azure DevOps Server and these other tools is fractured.

Planview Hub addresses this by synchronizing work items in Azure DevOps Server to defects, tasks, stories, work items and other artifacts in other lifecycle tools.

Key Features and Benefits

Synchronizes artifacts across the lifecycle, allowing information to flow freely between Azure DevOps Server and other tools
Improve team collaboration by connecting Azure DevOps Server to third party tools and allow artifacts to be synchronized across the lifecycle.
Support cross-tool traceability and reporting, removing the need for manual processes and spreadsheets.
Enriches the reports in Azure DevOps Server to include up-the-minute status from other tools.

Common Integration Patterns

Demo Videos

Supported Extensions

Microsoft Test Manager

Microsoft Test Manager is a pure client-based application used to access Azure DevOps Server. As such, the Azure DevOps Server connector can be used to access Azure DevOps Server artifacts that were created or updated by Microsoft Test Manager.

Modern Requirements4DevOps

Built into Azure DevOps, Modern Requirements4DevOps (formerly Modern Requirements4TFS) provides requirements management by extending the visualization, reuse, and reporting capabilities of Azure DevOps.

Modern Requirements4DevOps works with supported Azure artifact types. Therefore, once artifacts from Modern Requirements4DevOps are published to Azure, those artifacts will be supported by the Azure DevOps connector within Hub. No additional Azure configuration is needed for Modern Requirements4DevOps, and artifacts created and modified by Modern Requirements4DevOps can be synced by Hub as easily as other supported Azure types.

Connector Setup Details

This section describes the basic steps needed to prepare your Azure instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.

Minimal User Permissions & Hub User

We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization.

In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.

Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'

Create an Azure user account to be used by Hub and ensure that it has sufficient permissions to create, read, and update artifacts in the Azure projects to be used, and view project-level information as well as the information of the enclosing collection. Making the user account a member of the default Azure Contributor group of all the necessary projects is sufficient in most cases.

If you are on Azure DevOps Services (formerly VSTS) and require the user to interact with Test Management the user used needs to either have an Access Level of VS Enterprise, or be a Basic User with the Test Manager extension.

Note: When connecting to Azure DevOps Services, you need to configure the Hub user to use secondary credentials as this is required for integrations. Once configured, use the user name and password configured to connect from Hub. Below is a page that has some information on configuring secondary credentials: https://support.microsoft.com/en-us/kb/2991274

Please see the functional limitations table for large or complex Azure DevOps installations.

Connecting to the Microsoft Azure DevOps Repository

To connect to Azure DevOps Server, you must first provide the following files. Details can be found in the Requirement Details section of the Azure DevOps Server Repository Connection screen.

TFS SDK
TEE CLC

For instructions on how to upload these files see here.

Standard Authentication

Beginning on March 2, 2020, Azure DevOps Services (formerly VSTS) users must use Personal Access Token authentication, as standard authentication will no longer be supported by Microsoft. Azure DevOps Server (on-prem) users can continue to use standard authentication.

Required Fields:

Location/Connection URL
- Example Format: https://server.com/tfs
Username
- Note: Do not include the domain in the username (i.e., TASKTOPDEMO/Administrator)
Password
Domain: The authentication domain
- Only required if the Azure DevOps server requires a domain (for example, for Windows Authentication [NTLM or Kerberos])
- Not required for local accounts that have Basic Authentication enabled on the server

Optional Fields:

Enable Legacy NTLM Authentication: If checked, NTLM authentication scheme support will be enabled when authenticating to the repository.
- When unchecked, the NTLM authentication scheme support will be disabled and the connector will use basic authentication against the repository. See details here for configuring IIS to support basic authentication.
- Note: This field only applies to on-premise instances of Azure DevOps.
Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Learn more about how to set up your repository in Planview Hub here.

Screenshot 2023-08-16 at 9.20.57 AM.png

Personal Access Token

Planview Hub: 18.2 and later

Tasktop Sync: 4.14 and later

Azure DevOps Server 2017 and later, Azure DevOps Services

Required Fields

Location/Connection URL
- Example Format: https://server.com/ado
Personal Access Token (generated in Azure)
- To find the token, see Microsoft PAT docs
- Azure DevOps Server 2019 and earlier users
  - When creating a Personal Access Token to use with Hub, the All Scopes Authorized Scope must be selected for Azure DevOps Server (on-prem) users.
- Azure DevOps Server 2020 and above users
  - The following permissions are required for Azure DevOps Server users for “all accessible organizations”:
    - READ access for Projects, Teams, and Identity
    - READ/WRITE access for Work Items
    - READ/WRITE access for Test Items (if synchronizing Test Items [i.e., Test Plans, Test Suites, etc.])
    - READ & MANAGE access for token administration
    - For Hub versions 22.1 and earlier, READ access for Graph API is required for person reconciliation
  - User must be an administrator in the ADO Administration Console. Only the PAT created from the admin user will work.
  - The following document can be used to add the User to the administrators group add administrators - Azure DevOps.
Azure DevOps Services (cloud) users
- The following permissions are required for Azure DevOps Services users:
  - READ access for Projects, Teams, and Identity
  - READ/WRITE access for Work Items
  - READ/WRITE access for Test Items (if synchronizing Test Items [i.e., Test Plans, Test Suites, etc.])
  - For Hub versions 22.1 and earlier, READ access for Graph API is required for person reconciliation

Optional Fields

Domain (This field should be ignored for Personal Access Token Authentication)
Enable Legacy NTLM Authentication: If checked, NTLM authentication scheme support will be enabled when authenticating to the repository.
- When unchecked, the NTLM authentication scheme support will be disabled and the connector will use basic authentication against the repository.
- Note: This field only applies to on-premise instances of Azure DevOps.
Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Screenshot 2023-08-16 at 9.23.23 AM.png

OAuth 2.0 Client Credentials Proxy Authentication (For Microsoft Azure DevOps Server on-prem only)

Planview Hub: 24.4 and later

This authentication method enables secure, token-based access via a proxy, using the client credentials. Refer here for full details.

Note: Microsoft Azure DevOps Server does not currently support OAuth 2.0 Client Credentials authentication. As a result, the Microsoft Azure DevOps Server connector cannot connect directly with the Microsoft Azure DevOps Server repository using the OAuth 2.0 Client Credentials authentication method.

Prerequisites

The authenticated user should have ADO instance-level permissions.

Set teeNotRequired system property.

Find the property tomcat.custom.system.properties

If it is commented out, uncomment it

Add -Dcom.tasktop.connector.microsoft.tfs.teeNotRequired=true to the end of this property

For example:

Or, if there are other existing values in that property, add it after a comma at the end:

SSO Authentication

Additionally, Azure DevOps supports the following SSO implementations:

Script (HTTP cookies)
X.509 Certificate

Learn more about how to set up your repository in Planview Hub here.

Upgrading Planview Hub

When upgrading Planview Hub, please note important steps that must be taken for the Azure DevOps Server repository here.

Creating a Proxy Association Attribute (Tasktop Sync)

What is Proxy Association Attribute?

A custom string attribute is recommended to be used as the proxy association storage. Tasktop Sync needs to keep track of the association between a task and its proxy task. The association is persisted in a proxy store allowing the synchronization to be restored if there is any catastrophic failure of Tasktop Sync.

A proxy association attribute must be created for each artifact type to be synchronized.

The Proxy Association Attribute field must be a text/string type field in your ALM repository. We recommend creating this field with the name "Tasktop Sync Proxy."

To create a custom string field in Azure DevOps Server, see instructions on how to edit the xml file or follow the steps below:

You can use Azure DevOps Services to connect to your project
Open your work Item Types from the Tools > Process Editor menu and then select open WIT from server.
Select your Azure DevOps Server and choose your collection and connect
Select your Work Item Type
In Fields Tab create a new String custom field with the name Tasktop Sync proxy
Add your Tasktop Sync Proxy field into your layout and make it visible.

Note: If setting up the proxy field for multiple types, it is recommended to use the same Reference Name and Name for each of the types. It is required by Microsoft Azure DevOps Server that the name must be the same if the reference name is the same.

Initialization and Changes Queries (Tasktop Sync)

Tasktop Sync uses queries in the ALM systems to determine the artifacts to synchronize and detect changes in the system.

The initialization query represents the full set of artifacts to synchronize and is only run on initial configuration or manually.

The changes query should be defined the same as the initialization query but include some time scoping information (e.g. last 7 days) as this is the query that is executed on the defined schedule to detect changes. In many cases, these queries can be defined in the ALM system, providing the power of the built-in filters to properly scope the synchronization. If this is not possible, Tasktop Sync provides other mechanisms for filtering items in scope.

Normally, the initialization and changes query for Azure DevOps Server be created through the Azure DevOps Server Web Client or Azure DevOps Services as saved queries. These will be used in Tasktop Sync as a part of the configuration.

Note: You must login with your Tasktop Sync user account in Microsoft Azure DevOps Server and create your queries as they should be created as private to the user.

Query	Instruction
Initialization Query	For the initialization query in Azure DevOps Server you only need to select your work item type and the project unless there are any other conditions that you would like to have as your condition (e.g., specific team or Area Path). Once the conditions are added, give the filter a name and click Save to have it stored as a saved query.
Changes Query	For the changes query in Azure DevOps Server, start with the filter defined for the initialization query and add “Changed Date” as your condition. Note: Please note that you need to select greater equal (>=) option and then select @Today -7 as your condition for items modified in the last week. This will scope the query to only include items modified since yesterday. This could be changed to @Today -1 to have a smaller change window. Once the conditions are filled out, give the filter a name and click “Save” to have it stored as a saved query.

Query

Instruction

Initialization Query

For the initialization query in Azure DevOps Server you only need to select your work item type and the project unless there are any other conditions that you would like to have as your condition (e.g., specific team or Area Path). Once the conditions are added, give the filter a name and click Save to have it stored as a saved query.

Initialization Query

Changes Query

For the changes query in Azure DevOps Server, start with the filter defined for the initialization query and add “Changed Date” as your condition.

Note: Please note that you need to select greater equal (>=) option and then select @Today -7 as your condition for items modified in the last week.

This will scope the query to only include items modified since yesterday. This could be changed to @Today -1 to have a smaller change window. Once the conditions are filled out, give the filter a name and click “Save” to have it stored as a saved query.

Changes Query

Other Configuration Settings

Rich Text

At present, the connector supports the following rich text elements:

Bulleted list
Div
Numeric list
Paragraph
Quote
Emphasis
Link
Span
Strong
Underlined

In Planview Hub 18.2 and later/Tasktop Sync 4.14 and later:

Table
Table Cell Header
Table Cell
Table Row

Person Reconciliation

For person reconciliation, the following fields are available:

Fields Used for Hub’s Default Person Reconciliation Algorithm	Field Names for Person Reconciliation Extensions (Note that these are case sensitive)	Label in Azure DevOps Server
ID	account-name	Username (see image below)
Username	N/A	N/A
Email (Planview Hub: 22.2 and later)	person-email	Mail Address
N/A	person-display-name	Display Name
N/A	display-name	Full Name

Learn more about how to configure person reconciliation in Planview Hub here.

Full Scan

Due to third party API limitations, updates to the following fields may not trigger change detection or cause a synchronization immediately. To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:

Relationship and Relationships of non-test management artifacts (i.e., everything except Test Point, Test Results, Test Suites)

Learn more about how to configure change detection and full scan intervals in Planview Hub here.

Important note about installing Tasktop Sync

When installing Tasktop Sync, please leave “Install Microsoft Team Foundation Server Sync Connector” unchecked. This option only needs to be checked when working with the legacy TFS connector.

Test Execution Support

Planview Hub: 23.3 and later

Externalized Configuration

Cloud Installations

Please contact customer care to apply this system properly.

This section is only applicable for on-premise installations.

Microsoft Azure DevOps Test Execution Support must be enabled with an edit to the tasktop-hub.properties file. See here for details on how to edit this file.

To enable Microsoft Azure DevOps Test Execution Support:

Find the property tomcat.custom.system.properties
If it is commented out, uncomment it
Add -Dcom.tasktop.connector.microsoft.tfs.enableTestManagementTypes=true to the end of this property

For example:

tomcat.custom.system.properties=-Dcom.tasktop.connector.microsoft.tfs.enableTestManagementTypes=true

or, if there are other existing values in that property, add it after a comma at the end

For example:

tomcat.custom.system.properties=-Dexisting.custom.property=123, 
-Dcom.tasktop.connector.microsoft.tfs.enableTestManagementTypes=true

Change Detection

Microsoft Azure DevOps Server has an API limitation that results in change detection for Test Execution artifacts to be non-performant and create a high volume of network traffic. Therefore, it is recommended that the user does not detect changes for Test Execution artifacts in Microsoft Azure DevOps.

Note: If you do not disable change detection for Test Execution artifacts, Hub will be unable to process any other event until change detection is complete which may take a significant amount of time. Disabling change detection on the Test Execution artifacts is highly recommended to prevent any impacts on the Azure DevOps server and Hub.

Change detection must be disabled for the following artifacts:

Test Runs
Test Results

To configure change detection for your integration(s), please see the following instructions:

In Planview Hub, navigate to the integration page and select the integration that you want to set a change detection configuration to
It is recommended that the integration is set to a one-way creation into the Microsoft Azure DevOps connector
Under the Overview section, select “Change Detection”
Navigate to the Microsoft Azure DevOps section and select “Override”
Under Change Detection, set Repeat Method to “Advanced Scheduling”
Set Cron to a setting that will not trigger
Example of a Cron setting that will not trigger: 0 0 12 ? * * 2000
Click Save and Done
Repeat for all Microsoft Azure DevOps test execution integrations

See supported artifacts and functional limitations in the sections below.

Learn more about supported test integration scenarios using Azure DevOps here.

Frequently Asked Questions

See Microsoft Azure DevOps Server connector FAQs here.

Supported Features

Special Features Supported

You can learn more about special features in Planview Hub here.

Feature	Custom Type Supported?	Applicable Hub Versions	Applicable Repository Versions	Default Maximum Size in Repository
Time Worked (Worklogs) Impersonation
Comments Impersonation (not in Azure DevOps 2015+ and VSO) Public/Private (Tasktop Sync & Planview Hub 20.1 and later)	N/A	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync	N/A
Attachments Impersonation	N/A	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync	60MB Learn more about maximum attachment size here.
State Transitions	N/A	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync	N/A

Supported Artifacts

Supported Work Items

Learn about the difference between containers and work items in Planview Hub here.

Supported Work Item Type	Applicable Hub Versions	Applicable Repository Versions	Unique URL?
All out-of-the-box work items (such as Bug, Feature, Issue, Task, User Story, etc.) Note: Changesets and Test Points are not supported.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
All custom work items Note: Changesets and Test Points are not supported.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync	Yes
Test Runs Learn more about supported test integration scenarios using Azure DevOps here.	Planview Hub: 23.3 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud Version	Yes
Test Results Learn more about supported test integration scenarios using Azure DevOps here.	Planview Hub: 23.3 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud Version	Yes

Supported Containers

Learn more about containment in Planview Hub here.

Containers that can synchronize between repositories	Applicable Hub Versions	Applicable Repository Versions	Unique URL?
Test Plans Learn more about supported test integration scenarios using Azure DevOps here.	Planview Hub: 23.2 and later	Azure DevOps 2020 and later	Yes
Test Suites Learn more about supported test integration scenarios using Azure DevOps here.	Planview Hub: 23.2 and later	Azure DevOps 2020 and later	Yes
Containers used to define the boundary of a collection (When clicking 'Manage Projects' on a Collection)
Projects	Planview Hub: All	Any supported repository version: Planview Hub	N/A
Containers used for artifact routing
Projects	Planview Hub: All	Any supported repository version: Planview Hub	N/A

Supported Field Types

Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.

Standard Field Type	Does Hub support custom fields of this type?	How is field type referenced in the repository?	Sample Repository Fields Supported	Particular Repository Fields NOT Supported
String		String Plain text	Revision Title	Fields related to "Associated Automation" on Test Cases: Microsoft.VSTS.TCM.AutomatedTestId Microsoft.VSTS.TCM.AutomatedTestName Microsoft.VSTS.TCM.AutomatedTestStorage Microsoft.VSTS.TCM.AutomatedTestType Microsoft.VSTS.TCM.AutomationStatus
Single Select		String with allowed values	Iteration path* Area path* Severity Priority Reason *Note limitations below
Multi Select	N/A	Tags	System.Tags (Microsoft Azure DevOps Server 2020 and later)
Boolean Supported in Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later	(Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later)	Boolean	Board Column Done Is Automated
Date	N/A	Date	Created Date
Date Time		Date Time	Activated Date Resolved Date Revised Date Changed Date
Duration
Double		Double	Story Points Remaining Work Stack Rank
Long		Integer	ID
Person	(Planview Hub 18.1 and later; Tasktop Sync 4.13 and later and Microsoft Azure DevOps Server 2017 and later)	User	Assigned to Changed by (r/o) Created by (r/o)
Persons
Relationship(s) Learn how to configure relationships in Planview Hub here.
Rich Text		HTML	Repro Steps System info Description
Web Links	N/A	Hyperlink	Hyperlinks Links to Changesets (Read only)
Other

Functional Limitations

Category	Limitation	Applicable Hub Versions	Applicable Repository Versions
Good to Know	Test Results Formatted ID includes Test Run ID in the following format: <testRunId>/<testResultId> (e.g., 102/1000)	Planview Hub: 23.3 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud) Version
Third Party API Limitation	Test Runs State cannot be set to "Aborted" or "Unspecified" “Aborted” “Unspecified”	Planview Hub: 23.3 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud) Version
Good to Know	Test Runs and Test Results Test Results cannot be added to a Test Run in the “Completed” state. We recommend not mapping to this state if you are planning to synchronize Test Results.	Planview Hub: 23.3 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud) Version
Third Party API Limitation	Test Results Test Results can only be created on Automated Test Runs. The connector only creates Automated Test Runs but may retrieve Manual Test Runs created by ADO users.	Planview Hub: 23.3 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud) Version
Good to Know	Test Results Test Result creation requires a Test Case link, a Test Suite link, and a Test Plan link. The provided Test Case must be included in the provided Test Suite and the provided Test Suite must reside in the Test Plan. The Test Plan must be the same one that was provided for the Test Run that the Test Result is linked to.	Planview Hub: 23.3 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud) Version
Third Party API Limitation	Associated Bugs Field The Associated Bugs field on the Test Result artifact is a read-only field.	Planview Hub: 23.2 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud) Version
Third Party API Limitation	Test Suites Nested Test Suites are represented in a flat hierarchy. Due to an API limitation where Test Suites can only be queried by their originating Test Plan, nested Test Suites will be represented flatly under their Test Plan.	Planview Hub: 23.2 and later	Azure DevOps Server 2020+ and Current On Demand (Cloud) Version
Third Party API Limitation	Board Column Field (i.e., Board Column Name, Board Column Done, etc.) The Board Column field is read-only and the options listed are not board-specific. For example, if separate boards have multiple "In Progress" columns, only one "In Progress" option would be listed. These fields should only be used for items that appear on a single board. If an item is on multiple boards, a single Board Column value from one of the boards will be selected as that item's Board Column value. If more than one team shares the area path for the work item (including a team for parent area path with “include sub-areas”), the board column name may take on the same value as the state.	Planview Hub: 22.2 and later Tasktop Sync: 4.30 and later	Azure DevOps Server 2015 Update 3 and later
Third Party API Limitation	Picklists with Conditional Options Hub will return all allowed and suggested values for a given picklist field, even if only a subset of the values are appropriate based on the work item rules that have been defined in Microsoft Azure DevOps Server. Users must be aware of the rules configured in Microsoft when mapping field values in Hub.	Planview Hub: All Tasktop Sync: 4.8 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Web Link Fields The label for an existing web link cannot be updated. We recommend that customers update their Azure DevOps Server 2015 server to Update 3 or higher if update abilities are required.	Planview Hub: All Tasktop Sync: All	Azure DevOps Server 2015 RTM Azure DevOps Server 2015 Update 1 Azure DevOps Server 2015 Update 2
Third Party API Limitation	Work Item Person Fields If multiple users exist in Azure DevOps Server with the same display name (full name) within the same team project collection and a work item person field references one of those users, the Azure DevOps Server SDK will be unable to identify the correct user. To resolve this issue, we recommend removing the duplicate user(s) from the Azure DevOps Server instance or upgrading to Azure DevOps Server 2015 Update 3 or later. If unable to move forward with either of those solutions, note that in this scenario, Hub will build a "fake" person handle with the correct display name, but a made up person ID. To correctly map the user to a legitimate user, a person reconciliation script must be provided.	Planview Hub: 19.1.11+, 19.2.1 and later Tasktop Sync: 4.18 and later	Supported versions 2015 Update 2 and earlier: Planview Hub Tasktop Sync
Third Party API Limitation	Comments Person Fields If multiple users exist in Azure DevOps Server with the same display name (full name) within the same team project collection and a person field from a work item comment references one of those users, the Azure DevOps Server SDK will be unable to identify the correct user. To resolve this issue, we recommend removing the duplicate user(s) from the Azure DevOps Server instance or upgrading to Azure DevOps Server 2017+. If unable to move forward with either of those solutions, note that in this scenario, Hub will build a "fake" person handle with the correct display name, but a made up person ID. To correctly map the user to a legitimate user, a person reconciliation script must be provided.	Planview Hub: 19.1.11+, 19.2.1 and later Tasktop Sync: 4.18 and later	Supported versions 2015 and earlier: Planview Hub Tasktop Sync
Third Party API Limitation	Area Path and Iteration Path Area and iteration paths enable a customer to define a hierarchy (of arbitrary breadth and depth) that is used to categorize their work items. Due to limitations in the TEE SDK, Hub can only support up to 7 levels for the area path and iteration path fields.	Planview Hub: All Tasktop Sync: All	Any supported repository version: Planview Hub Tasktop Sync
Third Party Functional Limitation	Connectivity Issue In large or complex Azure DevOps Services installations (e.g., installations with a large number of projects in the server's collection and/or a high number of customizations) Hub may encounter connectivity issues. This could block integrations from running as well as prevent configuration changes. Please contact customer care if this occurs.	Planview Hub: All Tasktop Sync: All	Any Azure DevOps Services supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	State Transitions Hub supports two fields when setting state transition parameters (optional) in Planview Hub: Reason Completed	Planview Hub: All	Any supported repository version: Planview Hub
Third Party API Limitation	Kerberos Authentication Planview Hub instances installed onto Unix (as well as Linux and Mac) cannot integrate with an Azure DevOps Server instance that is running on a Windows server configured with Kerberos-only authentication.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Squid Proxy Connector does not work with out of the box Squid proxy.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Person Fields Person fields cannot be distinguished from String or single-select fields via API.	Planview Hub: All Tasktop Sync: 4.2 and later	For Planview Hub 18.1 and later and Sync 4.13 and later: Azure DevOps Server 2012-2015 For Planview Hub 17.1 - 17.3 and Sync 4.2 - 4.13: Planview Hub Tasktop Sync
Third Party API Limitation	System Tags Field The System.Tags field is read-only for Azure DevOps Server versions earlier than 2020. Labels/tags can be synchronized out of Azure DevOps Server but not into Azure DevOps Server. The API declares this field as read-only.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Unicode Characters Microsoft Azure DevOps Server (and thus the connector) does not support unicode characters in collections and projects https://msdn.microsoft.com/en-us/library/aa980550.aspx#ProjectCollectionNames	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Web Links Azure DevOps Server servers do not allow external web links pointing to the same URL. If multiple web links to the same URL are flowed into Azure DevOps Server, only one will succeed. The rest will be ignored.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Person Fields Projects which have multiple users with the same user name on separate domains are not supported.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Per-User Field Access Rules Hub does not support per-user field access rules. For example, a field configured to be read-only for all but one specific user will appear in Hub as read-only for all users.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third party API Limitation	Person Fields The Azure DevOps Server connector does not support groups as values for Person Fields. In some occasions (e.g., Kanban Board) it is possible for a group to appear as the value of a person field. But due to API limitations the connector cannot handle this and will ignore that person field value on retrieve.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Attachments If using a version of Azure DevOps Server earlier than 2017.3, you may receive a 'NullPointerException' error when attempting to flow an attachment to TFS, when a workflow clearing a field is involved ("EMPTY" workflow directive).	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported version before Azure DevOps Server 2017.3 (issue is fixed in Azure DevOps Server 2017.3) Planview Hub Tasktop Sync
Third Party API Limitation	Attachments The Azure DevOps Server SDK does not save attachment description for VSO and Azure DevOps Server 2015. However, if there is an existing attachment with comment, the connector can retrieve it.	Planview Hub: All Tasktop Sync: 4.2 and later	VSO, Azure DevOps Server 2015
Third party API Limitation	Web Links Azure DevOps Server Hyperlinks (web links) allow for some characters to be entered that are not valid URIs (RFC 2396). The connector will encode those to RFC 2396 compliant URI. However, the % character will not be encoded (because it could lead to double encoding), which means Hyperlinks containing "%" might cause an Artifact to not be retrieved by the connector.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Comments Azure DevOps Server versions 2015 and later do not support comment impersonation.	Planview Hub: All Tasktop Sync: 4.2 and later	Azure DevOps Server 2015, Azure DevOps Server 2017, VSO
Third Party API Limitation	Resolution Field The resolution field does not provide options for creating transition mappings.	Planview Hub: All Tasktop Sync: 4.5 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Web Links Web-Links to Azure DevOps Server Changesets are read-only from the Azure DevOps Server SDK, so those links can be read, but not written by Hub.	Planview Hub: All Tasktop Sync: 4.6 and later	Any supported repository version: Planview Tasktop Hub Tasktop Sync
Third Party API Limitation	Queries Certain queries cannot be executed because of an "unknown MODE parameter" (ReturnMatchingChildren). Those queries will not show up in the Hub UI. An example is a "Tree of Work Items" query with Filter options set to "Match linked work items first".	Planview Hub: All Tasktop Sync: 4.6 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Temporary File Microsoft Java SDK contains a defect that leaves temporary files in the system temp folder. To prevent the servers from running out of disk space, the temporary folder should be cleaned up periodically.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Changeset Links Azure DevOps Services introduced a regression in their July 7th update that broke Azure DevOps Server SDK functionality for fetching the URL from a changeset link associated with a work item. All known versions of Microsoft Java Azure DevOps Server SDK (including the 12.0.2 version we are using) are affected. This regression will cause the connector to fail during work item search and CRUD operations if a work item has a changeset link.	Planview Hub: All Tasktop Sync: 4.2 and later	Azure DevOps Services
Third Party API Limitation	Field Management Microsoft Java SDK does not expose rules defined on a field except `ALLOWEDVALUE` and `SUGGESTEDVALUE`.	Planview Hub: All Tasktop Sync: 4.2 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Field Management There is no way to separate the `ALLOWEDVALUE` and `SUGGESTEDVALUE` list using the Microsoft Java SDK. The two lists are returned together. Whenever a field (that is not of type boolean, date, double or integer) has these rules defined, the field is interpreted as a single select field with options from both ALLOWEDVALUE and SUGGESTEDVALUE lists. When a field has any SUGGESTEDVALUE options, the field is configured to accept new values.	Planview Hub: All Tasktop Sync: 4.8 and later	Any supported repository version: Planview Hub Tasktop Sync
Limited Connector Set Support	Rich Text Rich text formatting of text inside table cells may not be preserved when synchronized to Atlassian Jira.	Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Git Link Fields Git link fields (Branches, Commits, Pull Requests, and Tags) are only supported for Azure DevOps Server 2015 and later.	Planview Hub: 17.4 and later* Tasktop Sync: 4.12 and later* *Git link fields not supported in earlier Sync versions	Any supported repository version before Azure DevOps Server 2015: Planview Hub Tasktop Sync
Third Party API Limitation	Performance Azure DevOps Services will throttle requests if it detects that a client has submitted too many queries or other requests. This is much more likely to happen with test management artifacts because the connector has to submit many separate requests to fulfill collection search and artifact retrieval.	Planview Hub: 17.2 and later Tasktop Sync: 4.10 and later	Azure DevOps Services
Third Party API Limitation	Comments The Azure DevOps Server SDK may not correctly identify the user associated with a comment if that user shares the the same display name (full name) as another user in the same team project collection. The Azure DevOps Server SDK only supports the display name for work item comments; it does not have access to the user's unique account name.	Planview Hub: 17.1 - 19.1 Tasktop Sync: 4.2 - 4.17	Any supported repository version: Planview Hub Tasktop Sync
Third Party API Limitation	Person Fields The Azure DevOps Server SDK may not correctly identify the user associated with a work item if that user shares the the same display name (full name) as another user in the same team project collection. The Azure DevOps Server SDK only supports the display name for work item CRUD; it does not have access to the user's unique account name.	Planview Hub: 17.1 - 19.1 Tasktop Sync: 4.2 - 4.17	For Planview Hub 17.4 and later and Sync 4.12 and later: Azure DevOps Server 2012, 2013 For Planview Hub 17.1 - 17.3 and Sync 4.2 - 4.13: Any supported repository version: Planview Hub Tasktop Sync
Known Defect	Tasktop Sync The Azure DevOps Server SDK connector cannot migrate Azure DevOps Server (Mylyn) Tasktop Sync configurations using a "Limited Scope Mapping".	Tasktop Sync: 4.2 and later	Any supported repository version: Tasktop Sync
Configuration Requirement	Tasktop Sync Tasktop Sync must use database proxy to integrate with Microsoft Azure DevOps Server.	Tasktop Sync: 4.10 and later	Any supported repository version: Tasktop Sync
Third Party API Limitation	Test Steps Test Steps are not supported.	Planview Hub: All	Azure DevOps Services

Category

Limitation

Applicable Hub Versions

Applicable Repository Versions

Good to Know

Test Results

Formatted ID includes Test Run ID in the following format:

(e.g., 102/1000)

Planview Hub: 23.3 and later

Azure DevOps Server 2020+ and Current On Demand (Cloud) Version

Third Party API Limitation

Test Runs

State cannot be set to "Aborted" or "Unspecified"

“Aborted” “Unspecified”

Planview Hub: 23.3 and later

Azure DevOps Server 2020+ and Current On Demand (Cloud) Version

Good to Know

Test Runs and Test Results

Test Results cannot be added to a Test Run in the “Completed” state. We recommend not mapping to this state if you are planning to synchronize Test Results.

Planview Hub: 23.3 and later

Azure DevOps Server 2020+ and Current On Demand (Cloud) Version

Third Party API Limitation

Test Results

Test Results can only be created on Automated Test Runs.

The connector only creates Automated Test Runs but may retrieve Manual Test Runs created by ADO users.

Planview Hub: 23.3 and later

Azure DevOps Server 2020+ and Current On Demand (Cloud) Version

Good to Know

Test Results

Test Result creation requires a Test Case link, a Test Suite link, and a Test Plan link. The provided Test Case must be included in the provided Test Suite and the provided Test Suite must reside in the Test Plan.

The Test Plan must be the same one that was provided for the Test Run that the Test Result is linked to.

Planview Hub: 23.3 and later

Azure DevOps Server 2020+ and Current On Demand (Cloud) Version

Third Party API Limitation

Associated Bugs Field

The Associated Bugs field on the Test Result artifact is a read-only field.

Planview Hub: 23.2 and later

Azure DevOps Server 2020+ and Current On Demand (Cloud) Version

Third Party API Limitation

Test Suites

Nested Test Suites are represented in a flat hierarchy.

Due to an API limitation where Test Suites can only be queried by their originating Test Plan, nested Test Suites will be represented flatly under their Test Plan.

Planview Hub: 23.2 and later

Azure DevOps Server 2020+ and Current On Demand (Cloud) Version

Third Party API Limitation

Board Column Field (i.e., Board Column Name, Board Column Done, etc.)

The Board Column field is read-only and the options listed are not board-specific. For example, if separate boards have multiple "In Progress" columns, only one "In Progress" option would be listed.

These fields should only be used for items that appear on a single board. If an item is on multiple boards, a single Board Column value from one of the boards will be selected as that item's Board Column value. If more than one team shares the area path for the work item (including a team for parent area path with “include sub-areas”), the board column name may take on the same value as the state.

Planview Hub: 22.2 and later

Tasktop Sync: 4.30 and later

Azure DevOps Server 2015 Update 3 and later

Third Party API Limitation

Picklists with Conditional Options

Hub will return all allowed and suggested values for a given picklist field, even if only a subset of the values are appropriate based on the work item rules that have been defined in Microsoft Azure DevOps Server. Users must be aware of the rules configured in Microsoft when mapping field values in Hub.

Planview Hub: All

Tasktop Sync: 4.8 and later

Any supported repository version:

Third Party API Limitation

Web Link Fields

The label for an existing web link cannot be updated.

We recommend that customers update their Azure DevOps Server 2015 server to Update 3 or higher if update abilities are required.

Planview Hub: All

Tasktop Sync: All

Azure DevOps Server 2015 RTM

Azure DevOps Server 2015 Update 1

Azure DevOps Server 2015 Update 2

Third Party API Limitation

Work Item Person Fields

If multiple users exist in Azure DevOps Server with the same display name (full name) within the same team project collection and a work item person field references one of those users, the Azure DevOps Server SDK will be unable to identify the correct user. To resolve this issue, we recommend removing the duplicate user(s) from the Azure DevOps Server instance or upgrading to Azure DevOps Server 2015 Update 3 or later.
If unable to move forward with either of those solutions, note that in this scenario, Hub will build a "fake" person handle with the correct display name, but a made up person ID. To correctly map the user to a legitimate user, a person reconciliation script must be provided.

Planview Hub: 19.1.11+, 19.2.1 and later

Tasktop Sync: 4.18 and later

Supported versions 2015 Update 2 and earlier:

Third Party API Limitation

Comments Person Fields

If multiple users exist in Azure DevOps Server with the same display name (full name) within the same team project collection and a person field from a work item comment references one of those users, the Azure DevOps Server SDK will be unable to identify the correct user. To resolve this issue, we recommend removing the duplicate user(s) from the Azure DevOps Server instance or upgrading to Azure DevOps Server 2017+.
If unable to move forward with either of those solutions, note that in this scenario, Hub will build a "fake" person handle with the correct display name, but a made up person ID. To correctly map the user to a legitimate user, a person reconciliation script must be provided.

Planview Hub: 19.1.11+, 19.2.1 and later

Tasktop Sync: 4.18 and later

Supported versions 2015 and earlier:

Third Party API Limitation

Area Path and Iteration Path

Area and iteration paths enable a customer to define a hierarchy (of arbitrary breadth and depth) that is used to categorize their work items.

Due to limitations in the TEE SDK, Hub can only support up to 7 levels for the area path and iteration path fields.

Planview Hub: All

Tasktop Sync: All

Any supported repository version:

Third Party Functional Limitation

Connectivity Issue

In large or complex Azure DevOps Services installations (e.g., installations with a large number of projects in the server's collection and/or a high number of customizations) Hub may encounter connectivity issues. This could block integrations from running as well as prevent configuration changes. Please contact customer care if this occurs.

Planview Hub: All

Tasktop Sync: All

Any Azure DevOps Services supported repository version:

Third Party API Limitation

State Transitions

Hub supports two fields when setting state transition parameters (optional) in Planview Hub:

Reason
Completed

Planview Hub: All

Any supported repository version:

Planview Hub

Third Party API Limitation

Kerberos Authentication

Planview Hub instances installed onto Unix (as well as Linux and Mac) cannot integrate with an Azure DevOps Server instance that is running on a Windows server configured with Kerberos-only authentication.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Squid Proxy

Connector does not work with out of the box Squid proxy.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Person Fields

Person fields cannot be distinguished from String or single-select fields via API.

Planview Hub: All

Tasktop Sync: 4.2 and later

For Planview Hub 18.1 and later and Sync 4.13 and later:

Azure DevOps Server 2012-2015

For Planview Hub 17.1 - 17.3 and Sync 4.2 - 4.13:

Third Party API Limitation

System Tags Field

The System.Tags field is read-only for Azure DevOps Server versions earlier than 2020. Labels/tags can be synchronized out of Azure DevOps Server but not into Azure DevOps Server.

The API declares this field as read-only.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Unicode Characters

Microsoft Azure DevOps Server (and thus the connector) does not support unicode characters in collections and projects

https://msdn.microsoft.com/en-us/library/aa980550.aspx#ProjectCollectionNames

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Web Links

Azure DevOps Server servers do not allow external web links pointing to the same URL.

If multiple web links to the same URL are flowed into Azure DevOps Server, only one will succeed. The rest will be ignored.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Person Fields

Projects which have multiple users with the same user name on separate domains are not supported.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Per-User Field Access Rules

Hub does not support per-user field access rules. For example, a field configured to be read-only for all but one specific user will appear in Hub as read-only for all users.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third party API Limitation

Person Fields

The Azure DevOps Server connector does not support groups as values for Person Fields. In some occasions (e.g., Kanban Board) it is possible for a group to appear as the value of a person field. But due to API limitations the connector cannot handle this and will ignore that person field value on retrieve.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Attachments

If using a version of Azure DevOps Server earlier than 2017.3, you may receive a 'NullPointerException' error when attempting to flow an attachment to TFS, when a workflow clearing a field is involved ("EMPTY" workflow directive).

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported version before Azure DevOps Server 2017.3 (issue is fixed in Azure DevOps Server 2017.3)

Third Party API Limitation

Attachments

The Azure DevOps Server SDK does not save attachment description for VSO and Azure DevOps Server 2015. However, if there is an existing attachment with comment, the connector can retrieve it.

Planview Hub: All

Tasktop Sync: 4.2 and later

VSO, Azure DevOps Server 2015

Third party API Limitation

Web Links

Azure DevOps Server Hyperlinks (web links) allow for some characters to be entered that are not valid URIs (RFC 2396). The connector will encode those to RFC 2396 compliant URI. However, the % character will not be encoded (because it could lead to double encoding), which means Hyperlinks containing "%" might cause an Artifact to not be retrieved by the connector.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Comments

Azure DevOps Server versions 2015 and later do not support comment impersonation.

Planview Hub: All

Tasktop Sync: 4.2 and later

Azure DevOps Server 2015, Azure DevOps Server 2017, VSO

Third Party API Limitation

Resolution Field

The resolution field does not provide options for creating transition mappings.

Planview Hub: All

Tasktop Sync: 4.5 and later

Any supported repository version:

Third Party API Limitation

Web Links

Web-Links to Azure DevOps Server Changesets are read-only from the Azure DevOps Server SDK, so those links can be read, but not written by Hub.

Planview Hub: All

Tasktop Sync: 4.6 and later

Any supported repository version:

Third Party API Limitation

Queries

Certain queries cannot be executed because of an "unknown MODE parameter" (ReturnMatchingChildren). Those queries will not show up in the Hub UI. An example is a "Tree of Work Items" query with Filter options set to "Match linked work items first".

Planview Hub: All

Tasktop Sync: 4.6 and later

Any supported repository version:

Third Party API Limitation

Temporary File

Microsoft Java SDK contains a defect that leaves temporary files in the system temp folder. To prevent the servers from running out of disk space, the temporary folder should be cleaned up periodically.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Changeset Links

Azure DevOps Services introduced a regression in their July 7th update that broke Azure DevOps Server SDK functionality for fetching the URL from a changeset link associated with a work item. All known versions of Microsoft Java Azure DevOps Server SDK (including the 12.0.2 version we are using) are affected. This regression will cause the connector to fail during work item search and CRUD operations if a work item has a changeset link.

Planview Hub: All

Tasktop Sync: 4.2 and later

Azure DevOps Services

Third Party API Limitation

Field Management

Microsoft Java SDK does not expose rules defined on a field except ALLOWEDVALUE and SUGGESTEDVALUE.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

Field Management

There is no way to separate the ALLOWEDVALUE and SUGGESTEDVALUE list using the Microsoft Java SDK. The two lists are returned together. Whenever a field (that is not of type boolean, date, double or integer) has these rules defined, the field is interpreted as a single select field with options from both ALLOWEDVALUE and SUGGESTEDVALUE lists. When a field has any SUGGESTEDVALUE options, the field is configured to accept new values.

Planview Hub: All

Tasktop Sync: 4.8 and later

Any supported repository version:

Limited Connector Set Support

Rich Text

Rich text formatting of text inside table cells may not be preserved when synchronized to Atlassian Jira.

Planview Hub: 18.2 and later

Tasktop Sync: 4.14 and later

Any supported repository version:

Third Party API Limitation

Git Link Fields

Git link fields (Branches, Commits, Pull Requests, and Tags) are only supported for Azure DevOps Server 2015 and later.

Planview Hub: 17.4 and later*

Tasktop Sync: 4.12 and later*

*Git link fields not supported in earlier Sync versions

Any supported repository version before Azure DevOps Server 2015:

Third Party API Limitation

Performance

Azure DevOps Services will throttle requests if it detects that a client has submitted too many queries or other requests. This is much more likely to happen with test management artifacts because the connector has to submit many separate requests to fulfill collection search and artifact retrieval.

Planview Hub: 17.2 and later

Tasktop Sync: 4.10 and later

Azure DevOps Services

Third Party API Limitation

Comments

The Azure DevOps Server SDK may not correctly identify the user associated with a comment if that user shares the the same display name (full name) as another user in the same team project collection. The Azure DevOps Server SDK only supports the display name for work item comments; it does not have access to the user's unique account name.

Planview Hub: 17.1 - 19.1

Tasktop Sync: 4.2 - 4.17

Any supported repository version:

Third Party API Limitation

Person Fields

The Azure DevOps Server SDK may not correctly identify the user associated with a work item if that user shares the the same display name (full name) as another user in the same team project collection. The Azure DevOps Server SDK only supports the display name for work item CRUD; it does not have access to the user's unique account name.

Planview Hub: 17.1 - 19.1

Tasktop Sync: 4.2 - 4.17

For Planview Hub 17.4 and later and Sync 4.12 and later:

Azure DevOps Server 2012, 2013

For Planview Hub 17.1 - 17.3 and Sync 4.2 - 4.13:

Any supported repository version:

Known Defect

Tasktop Sync

The Azure DevOps Server SDK connector cannot migrate Azure DevOps Server (Mylyn) Tasktop Sync configurations using a "Limited Scope Mapping".

Tasktop Sync: 4.2 and later

Any supported repository version:

Tasktop Sync

Configuration Requirement

Tasktop Sync

Tasktop Sync must use database proxy to integrate with Microsoft Azure DevOps Server.

Tasktop Sync: 4.10 and later

Any supported repository version:

Tasktop Sync

Third Party API Limitation

Test Steps

Test Steps are not supported.

Planview Hub: All

Azure DevOps Services