Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content
Permalink
main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

azure-devops-docs/docs/boards/queries/linking-attachments.md

Go to file
 
 
Cannot retrieve contributors at this time
Query work items by link or attachment count Supported operators and macros Link or attachment count queries List hierarchical items in a tree view Browser Visual Studio 2015 List items based on linked dependents Browser Visual Studio 2015 List orphan user stories Link, attachment count, and comment fields Related articles Visualize related work and other objects Add custom link types or customize the links controls Default data fields in lists of links
376 lines (289 sloc) 14.6 KB
Raw Blame
Open in GitHub Desktop
title titleSuffix description ms.custom ms.service ms.assetid ms.author author ms.topic monikerRange ms.date
Query work items by link or attachment count in Azure Boards
Azure Boards
Learn how to query work items based on link type, link count, link restrictions, and attachment file count in Azure Boards.
boards-queries, engagement-fy23
azure-devops-boards
219717a0-de6e-4f70-8558-54f813f82507
chcomley
chcomley
example-scenario
<= azure-devops
07/26/2022

Query work items by link or attachment count

[!INCLUDE version-lt-eq-azure-devops]

You can link work items to track related work and dependencies and attach files to share information with your team. You can then list work items based on one or more of the following fields:

::: moniker range="azure-devops"

  • Attachment File Count
  • (Discussion) Comment Count
  • External Link count
  • Hyperlink Count
  • Link Comment
  • Related Link Count
  • Remote Link Count ::: moniker-end

::: moniker range="< azure-devops"

  • Attachment File Count
  • (Discussion) Comment Count
  • External Link count
  • Hyperlink Count
  • Link Comment
  • Related Link Count ::: moniker-end

For descriptions of each of these fields, see the table provided later in this article.

Supported operators and macros

Query clauses that specify an integer field can use the operators listed below.

= , <> , > , < , >= , <= ,
=[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field],
In, Not In,
Was Ever

Link or attachment count queries

You can filter for work items by the link type, link count, or attachment count.

::: moniker-end

List hierarchical items in a tree view

Add a query and select Tree of work items to begin your query. You should see something similar to the following examples:

Browser

:::image type="content" source="media/query-link-attach-all-items-tree-query.png" alt-text="Screenshot of Query Editor, Tree Query, web portal.":::

Visual Studio 2015

:::image type="content" source="media/link-attachments/tree-query-te.png" alt-text="Screenshot of Query Editor, Tree Query, Team Explorer.":::

[!NOTE] You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. However, you can create a Direct links query that lists test-related work items. Also, you can, view the hierarchy through the Test>Test Plans page.

From there, you can add query clauses or change the filter options for linked work items. :::row::: :::column span=""::: Filter for :::column-end::: :::column span=""::: Include these query clauses :::column-end::: :::row-end::: :::row::: :::column span=""::: View only child items of work item 645 :::column-end::: :::column span=""::: Add to Filters for top-level work items:
ID = 645 :::column-end::: :::row-end::: :::row::: :::column span=""::: Tasks or bugs :::column-end::: :::column span=""::: Add to Filters for linked work items:
Work Item Type In Task,Bug :::column-end::: :::row-end::: :::row::: :::column span=""::: Items assigned to my team (Web) :::column-end::: :::column span=""::: Add to both top and bottom filters:
Assigned to In Group [Fabrikam Fiber]\Web
:::column-end::: :::row-end::: :::row::: :::column span=""::: Parent items of tasks assigned to me :::column-end::: :::column span=""::: Change Filter options to Match linked work items first
Add to Filters for linked work items:
Assigned To = @Me :::column-end::: :::row-end:::

List items based on linked dependents

The following example shows a dependent linked query that returns items with dependencies on work managed by other teams and projects.

Browser

The following query finds work items in all projects that are linked to work items under the Fabrikam area path and project using Predecessor and Successor link types.

:::image type="content" source="media/link-attachments/direct-links-query-web-portal.png" alt-text="Screenshot of Query Editor, Work items, and direct links, Web portal.":::

Why this works:

  • Checking the Query across projects checkbox enables all dependent linked work items that match the filter criteria to be listed, no matter which project they belong to.

  • Specifying the Area Path Under Fabrikam clause indicates to find only work items that are linked to work items defined under the Fabrikam project.

  • Specifying Only return items that have matching links, and Return selected link types causes the query to return only work items that are linked based on the Predecessor and Successor link types.

Visual Studio 2015

Use this type of query to list all dependent work items that link to active Product Backlog Items or Bugs that haven't been removed, closed, or completed. Only those dependent work items that are under a product area other than the Phone Save\Phone Customers are returned.

Work Items and Dependent Links Query

Why this works:

  • Removing the Team Project = @Project clause enables all dependent linked work items that match the filter criteria to be listed, no matter which project they belong to in the collection.

  • Grouping each of two clauses returns all Product Backlog Items on the backlog or in progress, and the second grouped clause returns all Bugs on the backlog or in progress.

  • Grouping the two clauses with the OR operator at the start of the second clause returns work items that match either of the two filter criteria.

  • Choosing the Only return items that have the specified links returns only top-level work items that have dependencies.

  • Choosing Return links of any type returns all linked work items that match the filter criteria for linked work items, in this case, returning all work items that aren't under the Phone Saver\Phone Customers area path, and aren't completed or removed.

The following image shows the query results that are returned.

Direct links query results

List orphan user stories

If you typically organize your user stories under features, you can quickly find user stories that are orphan by opening the product backlog, enable Parents On view option, and scroll down to the section that lists Unparented Stories (Agile) or Unparented Backlog items (Scrum).

[!div class="mx-imgBorder"]
List orphan stories or backlog items

Or, you can find unparented backlog items using a Work items and direct links query. For example, the following query lists active user stories for the Azure DevOps team that don't have a Parent link.

:::image type="content" source="media/link-attachments/unparented-work-items.png" alt-text="Screenshot of Query Editor, Work items, and direct links, Web portal, unparented user stories.":::

Link, attachment count, and comment fields

The following table describes fields associated with links and attachments. Most of these fields don't appear within the work item form, but are tracked for all work item types.

:::row::: :::column span="1"::: Attachment File Count :::column-end::: :::column span="3"::: The number of files attached to the work item and stored in the work item tracking database.
Reference Name=System.AttachedFileCount, Data type=Integer

[!NOTE] For Azure Boards (cloud service), you can add up to 100 attachments to a work item. Attempts to add more result in an error message upon saving the work item.
:::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: :::row::: :::column span="1"::: Comment Count :::column-end::: :::column span="3"::: The number of comments added to the Discussion section of the work item.
Reference Name=System.CommentCount, Data type=Integer
:::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: :::row::: :::column span="1":::

External Link Count

:::column-end::: :::column span="3"::: The number of links from the work item to artifacts that are not work items. such as pull requests, commits, changesets, or other link types.
Reference Name=System.ExternalLinkCount, Data type=Integer :::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: :::row::: :::column span="1":::

Hyperlink Count

:::column-end::: :::column span="3"::: The number of hyperlinks that are defined for the work item.

Reference Name=System.HyperLinkCount, Data type=Integer :::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: :::row::: :::column span="1"::: Link Comment :::column-end::: :::column span="3"::: Contains comments from the team member who created the link. You can configure this field to appear as a column in a list of links on a work item form. (Not supported in query editor.)

Reference Name=System.Links.Comment, Data type=PlainText :::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: :::row::: :::column span="1":::

Link Description

:::column-end::: :::column span="3"::: Contains the work item type, ID, and title of the work item that is the target of the link. You can configure this field to appear as a column in a list of links on a work item form. (Not supported in query editor.)

Reference Name=System.Links.Description, Data type=PlainText :::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: ::: moniker range=">= azure-devops-2022" :::row::: :::column span="1":::

Parent

:::column-end::: :::column span="3"::: When included as a column option in a backlog or query results list, the Title of the parent work item is displayed. Internally, the system stores the ID of the work item within an Integer field.

[!NOTE] You can add the Parent field as a column or specify it within a query clause by specifying the parent work item ID.
Reference Name=System.Parent, Data type=Integer :::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: ::: moniker-end ::: moniker range="azure-devops-2020" :::row::: :::column span="1":::

Parent

:::column-end::: :::column span="3"::: When included as a column option in a backlog or query results list, the Title of the parent work item is displayed. Internally, the system stores the ID of the work item within an Integer field.

[!NOTE] The Parent field is available from Azure DevOps Server 2020 and later versions. You can't specify this field within a query clause.
Reference Name=System.Parent, Data type=Integer :::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: ::: moniker-end :::row::: :::column span="1":::

Related Link Count

:::column-end::: :::column span="3"::: The number of links defined for a work item which use a work link type, such as Parent-Child, Predecessor-Successor, and Related. For a full list, see Link type reference.
Reference Name=System.RelatedLinkCount, Data type=Integer :::column-end::: :::column span="1"::: All :::column-end::: :::row-end::: :::row::: :::column span="1":::

Remote Link Count

:::column-end::: :::column span="3"::: Available for Azure DevOps Services only. The number of links from a work item to work items defined in another organization. Organizations must be managed by the same Azure Active Directory. Supported link types include Consumes From, Produced For, and Remote Related. To learn more, see Add link to work items, Link to a remote work item.
Reference Name=System.RemoteLinkCount, Data type=Integer :::column-end::: :::column span="1"::: All :::column-end::: :::row-end:::

Related articles

::: moniker range="< azure-devops"

Visualize related work and other objects

You can view related work items and object within a work item form by installing the Work item visualization extension available from the Visual Studio Marketplace, Azure DevOps tab. ::: moniker-end

::: moniker range="< azure-devops"

Add custom link types or customize the links controls

To add link types, see Manage link types [witadmin].

All tabs that support creating links between work items are implemented by using the LinksControl element on the work item form. This element controls filtering and restricting the types of work items to which you can link, the types of links that you can create, and whether you can link to work items in another project. To customize the link controls and restrictions, you modify the definition of the LinksControlOptions for a work item type, see LinksControlOptions XML elements.

Default data fields in lists of links

You can add or remove columns from the list of links, and you can customize the default columns and the column order. For more information, see LinksControlOptions XML elements.

::: moniker-end