Skip to content

Commit 3c5f99c

Browse files
JKirsch1JKirsch1
committed
Refresh article
1 parent 159a56d commit 3c5f99c

File tree

3 files changed

+48
-48
lines changed

3 files changed

+48
-48
lines changed

‎docs/report/extend-analytics/work-item-links.md‎

Lines changed: 40 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,39 @@
11
---
22
title: Query for Linked Work Items
33
titleSuffix: Azure DevOps
4-
description: Learn how to create a query for linked work items using Analytics for Azure DevOps.
4+
description: Find out how to create OData queries against Analytics for Azure DevOps to retrieve information about linked work items.
55
ms.subservice: azure-devops-analytics
66
ms.topic: tutorial
77
ms.assetid: BF30FE4E-0370-4C9B-A660-51207D816F8B
88
ms.author: chcomley
99
author: chcomley
1010
monikerRange: "<=azure-devops"
1111
ms.date: 05/09/2025
12+
# customer intent: As a developer, I want to find out how to create OData queries against Analytics for Azure DevOps so that I can retrieve information about linked work items.
1213
---
1314

1415
# Tutorial: Query for linked work items
1516

1617
[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)]
1718

18-
Querying work items across links is much like using typical navigation properties. Links themselves are entities though, so there's some extra complexity.
19+
When you run Open Data Protocol (OData) queries against Analytics for Azure DevOps, you can retrieve information about work items. You can also query linked work items. Work items can be linked hierarchically, such as in parent or child relationships. Work items can also be linked nonhierarchically, such as when work items are related or are duplicates.
1920

20-
There are two ways to query for linked work items. The first is the Parent/Child hierarchy, and the second is the Links navigation property.
21+
The way you query linked work items is similar to the way you use navigation properties to filter queries of entity sets. But links are entities, so there's some extra complexity. There are two ways to query linked work items:
22+
23+
- By using the `Parent` or `Children` navigation properties
24+
- By using the `Links` navigation property
2125

2226
In this tutorial you:
2327

2428
> [!div class="checklist"]
25-
> * Construct a query to return hierarchically (parent-child) linked work items
26-
> * Construct a query to return non-hierarchically (related, direct) linked work items
29+
> * Construct queries to return hierarchically linked work items.
30+
> * Construct queries to return nonhierarchically linked work items.
2731
28-
[!INCLUDE [temp](../includes/analytics-preview.md)]
32+
[!INCLUDE [Analytics preview](../includes/analytics-preview.md)]
2933

3034
## Prerequisites
3135

32-
[!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)]
36+
[!INCLUDE [Basic prerequisites](../includes/analytics-prerequisites-simple.md)]
3337

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

@@ -38,30 +42,29 @@ In this tutorial you:
3842
>
3943
> `https://analytics.dev.azure.com/{organization-name}/{project-name}/_odata/{version}`
4044
>
41-
> For Azure DevOps Server, instead use the following format, which includes the on-premises server:
45+
> For Azure DevOps Server, use the following format instead, which includes the on-premises server:
4246
>
4347
> `https://{server-name}:{port}/tfs/{organization-name}/{project-name}/_odata/{version}`
4448
4549
::: moniker-end
4650

47-
## Parent-child hierarchy
51+
## Query for parent or children work items
4852

49-
You can include items related through Parent/Child links by using ```$expand``` on the Parent and Children properties.
53+
You can query items related through parent-child links by using the `$expand` option on the `Parent` and `Children` navigation properties.
5054

51-
### Example: Parent to child query
55+
### Example: Request an item's children
5256

53-
To return information about an item's children, use ```$expand``` on the **Children** navigation property.
54-
The following code snippet requests to return the children of work item ID 359 from the Fabrikam Fiber project.
57+
To return information about an item's children, use `$expand` on the `Children` navigation property. The following OData code queries the Fabrikam Fiber project in the fabrikam organization. It returns the children of the work item with ID 359.
5558

5659
**Request**
5760

5861
```odata
5962
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 359&$select=WorkItemId, Title, WorkItemType, State&$expand=Children($select=WorkItemId,Title, WorkItemType, State)
6063
```
6164

62-
The response returns features 479 and 480, which are children of the epic 359.
65+
The response lists information about the feature work items with IDs 479 and 480. These features are children of the epic work item with ID 359.
6366

64-
[!INCLUDE [temp](../includes/note-work-item-link-warning.md)]
67+
[!INCLUDE [Note about the work item link warning](../includes/note-work-item-link-warning.md)]
6568

6669
**Response**
6770

@@ -93,19 +96,19 @@ The response returns features 479 and 480, which are children of the epic 359.
9396
}
9497
```
9598

96-
### Example: Child to parent query
99+
### Example: Request an item's parent
97100

98-
By replacing **Children** with **Parent** in the ```$expand``` option, you can retrieve an item's ancestry.
101+
By replacing `Children` with `Parent` in the `$expand` option, you can retrieve an item's ancestry.
99102

100-
The following query requests to return the parent of work item ID 1048 from the Fabrikam Fiber project.
103+
The following code queries the parent of the work item with ID 1048 in the Fabrikam Fiber project and the fabrikam organization.
101104

102105
**Request**
103106

104107
```odata
105108
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$expand=Parent($select=WorkItemId,Title,WorkItemType, State)&$filter=WorkItemId eq 1048
106109
```
107110

108-
The response returns feature 480, which is the parent to product backlog item 1048.
111+
The response lists information about the feature with ID 480, which is the parent of the product backlog item with ID 1048.
109112

110113
**Response**
111114

@@ -131,13 +134,13 @@ The response returns feature 480, which is the parent to product backlog item 10
131134
}
132135
```
133136

134-
## Query for non-hierarchical links
137+
## Query for nonhierarchical links
135138

136-
In addition to the Parent/Child hierarchy, items can be directly related to other items with link types like *Related* or *Duplicate*. The **Links** navigation property allows you to request these relationships.
139+
Besides parent-child links, other types like `Related` or `Duplicate` can also link work items. You can use the `Links` navigation property to request information about work items linked through nonhierarchical relationships.
137140

138141
### Example: Request an item's links
139142

140-
To retrieve the links associated with an item, you can ```$expand``` the **Links** navigation property. In this example the **SourceWorkItemId**, **TargetWorkItemId**, and **LinkTypeName** are retrieved for all links associated with the work item 363.
143+
To retrieve the links associated with an item, you use the `$expand` option on the `Links` navigation property. The following query retrieves the `SourceWorkItemId`, `TargetWorkItemId`, and `LinkTypeName` values for all links associated with work item 363.
141144

142145
**Request**
143146

@@ -179,9 +182,11 @@ https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Wo
179182
}
180183
```
181184

182-
### Example: Request details of linked items
185+
### Example: Request detailed information about linked items
186+
187+
You can query detailed information about linked work items by using the `$expand` option on the `TargetWorkItem` or `SourceWorkItem` navigation properties.
183188

184-
You can include the details of your linked work items by using ```$expand``` on the **TargetWorkItem** or **SourceWorkItem** navigation properties. In this example, we retrieve the **WorkItemId**, **Title**, and **State** of the target work item for each link.
189+
Like the previous query, the following query retrieves the `SourceWorkItemId`, `TargetWorkItemId`, and `LinkTypeName` values for all links associated with a work item. But this query also retrieves the `WorkItemId`, `Title`, and `State` values of each link's target work item.
185190

186191
**Request**
187192

@@ -232,17 +237,17 @@ https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Wo
232237
"LinkTypeName": "Related",
233238
"TargetWorkItem": {
234239
"WorkItemId": 112,
235-
"Title": "Some issue",
240+
"Title": "Issue 10",
236241
"State": "Active"
237242
}
238243
}]
239244
}]
240245
}
241246
```
242247

243-
### Example: Links of a specific type
248+
### Example: Request links of a specific type
244249

245-
You may also be interested in a particular type of link between items. Specify the **LinkTypeName** property in a `$filter` clause. The following query example expands all **Related** links and filters out all other link types for work item 103.
250+
If you're interested in a particular type of link between items, you can use the `LinkTypeName` property in a `$filter` clause. The following query expands all `Related` links and filters out all other link types for work item 103.
246251

247252
**Request**
248253

@@ -257,31 +262,25 @@ https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Wo
257262
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
258263
"value": [{
259264
"WorkItemId": 103,
260-
"Title": "Feature Y1",
265+
"Title": "Feature Y",
261266
"WorkItemType": "Feature",
262-
"State": "Active",
267+
"State": "New",
263268
"Links": [{
264269
"SourceWorkItemId": 103,
265270
"TargetWorkItemId": 112,
266271
"LinkTypeName": "Related",
267272
"TargetWorkItem": {
268273
"WorkItemId": 112,
269-
"Title": "Feature Y2",
270-
"State": "New"
274+
"Title": "Issue 10",
275+
"State": "Active"
271276
}
272277
}]
273278
}]
274279
}
275280
```
276281

277-
## Next steps
278-
279-
> [!div class="nextstepaction"]
280-
> [Explore Analytics metadata](analytics-metadata.md)
281-
282-
## Related articles
282+
## Related content
283283

284-
- [Construct OData queries for Analytics](../analytics/analytics-query-parts.md)
285-
- [Construct basic queries using OData Analytics](wit-analytics.md)
286-
- [Work items with direct links sample reports](../powerbi/sample-boards-directlinks.md)
287-
- [Requirements tracking sample report](../powerbi/sample-stories-overview.md)
284+
- [Analytics OData metadata](analytics-metadata.md)
285+
- [Construct OData queries for Analytics in Azure DevOps](../analytics/analytics-query-parts.md)
286+
- [List linked work items sample queries and reports](../powerbi/sample-boards-directlinks.md)

‎docs/report/includes/analytics-preview.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,23 +3,24 @@ ms.subservice: azure-devops-analytics
33
ms.author: chcomley
44
author: chcomley
55
ms.topic: include
6-
ms.date: 07/21/2023
6+
ms.date: 05/09/2025
77
---
88

99
::: moniker range="azure-devops"
1010

1111
> [!NOTE]
12-
> The Analytics service is automatically enabled and supported in production for all Azure DevOps Services. [Power BI integration](../powerbi/overview.md) and access to the [OData feed](../extend-analytics/quick-ref.md) of the Analytics Service are generally available. We encourage you to use it and give us feedback.
13-
> Available data is version-dependent. The latest supported version is `v2.0`, and the latest preview version is `v4.0-preview`. For more information, see [OData API versioning](../extend-analytics/odata-api-version.md).
12+
> The Analytics service is automatically enabled and supported in production for all services within Azure DevOps Services. [Power BI integration](../powerbi/overview.md) and access to the [OData feed](../extend-analytics/quick-ref.md) of the Analytics service are generally available. You're encouraged to use the Analytics OData feed and provide feedback.
13+
>
14+
> Available data is version-dependent. The latest supported version of the OData API is `v2.0`, and the latest preview version is `v4.0-preview`. For more information, see [OData API versioning](../extend-analytics/odata-api-version.md).
1415
1516
::: moniker-end
1617

1718
::: moniker range=">= azure-devops-2020 < azure-devops"
1819

1920
> [!NOTE]
20-
> The Analytics service is automatically installed and supported in production for all new project collections for Azure DevOps Server 2020 and later versions. [Power BI integration](../powerbi/overview.md) and access to the [OData feed](../extend-analytics/quick-ref.md) of the Analytics Service are generally available. We encourage you to use it and give us feedback. If you upgraded from Azure DevOps Server 2019, then you can install the Analytics service during upgrade.
21+
> The Analytics service is automatically installed and supported in production for all new project collections for Azure DevOps Server 2020 and later versions. [Power BI integration](../powerbi/overview.md) and access to the [OData feed](../extend-analytics/quick-ref.md) of the Analytics service are generally available. You're encouraged to use the Analytics OData feed and provide feedback. If you upgrade from Azure DevOps Server 2019, you can install the Analytics service during upgrade.
2122
>
22-
> Available data is version-dependent. The latest supported version is `v2.0`, and the latest preview version is `v4.0-preview`. For more information, see [OData API versioning](../extend-analytics/odata-api-version.md).
23+
> Available data is version-dependent. The latest supported version of the OData API is `v2.0`, and the latest preview version is `v4.0-preview`. For more information, see [OData API versioning](../extend-analytics/odata-api-version.md).
2324
2425
::: moniker-end
2526

‎docs/report/includes/note-work-item-link-warning.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@ ms.technology: devops-analytics
33
ms.author: chcomley
44
author: chcomley
55
ms.topic: include
6-
ms.date: 10/26/2022
6+
ms.date: 05/09/2025
77
---
88

99

1010
> [!NOTE]
11-
> Most OData queries that request work item link information will return results but also a warning. The warning is a reminder to follow recommended query guidelines described in [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md). However, the query examples provided are valid.
11+
> Most OData queries that request work item link information return results but also a warning. The warning is a reminder to follow the recommended query guidelines described in [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md). However, the query examples in this article are valid.

0 commit comments

Comments
 (0)