Query for linked work items

Article
03/03/2022
3 minutes to read

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

Querying work items across links is much like using typical navigation properties. Links themselves are entities though, so there's some extra complexity.

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.

In this article you'll learn:

How to construct a query to return hierarchically (parent-child) linked work items
How to construct a query to return non-hierarchically (related, direct) linked work items

Note

The Analytics service is automatically enabled for all Azure DevOps Services. It is supported for use in production. Power BI integration and access to the OData feed of the Analytics Service are in Preview. We encourage you to use it and provide us feedback.

Note

The Analytics service is automatically installed on all new project collections for Azure DevOps Server 2020. It is supported for use in production. Power BI integration and access to the OData feed of the Analytics Service are in Preview. We encourage you to use it and provide us feedback. If you upgraded from Azure DevOps Server 2019, then you're provided with the option to install the Analytics service during upgrade.

Note

The Analytics service is in preview for Azure DevOps Server 2019. You access Analytics by enabling or installing it for a project collection. Power BI integration and access to the OData feed of the Analytics Service are in Preview. We encourage you to use it and provide us feedback.

Note

The examples shown in this document are based on a Azure DevOps Services URL, you will need to substitute in your Azure DevOps Server URL.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/

Note

The {version} value is formatted as v1.0. The latest supported version is v2.0, and the latest preview version is v4.0-preview. For more information, see OData API versioning.

Parent-child hierarchy

You can include items related through Parent/Child links by using $expand on the Parent and Children properties.

Example: Parent to child query

To return information about an item's children, use $expand on the Children navigation property.

Request

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?$select=WorkItemId,Title,State&$expand=Children($select=WorkItemId,Title,State)&$filter=WorkItemId eq 103

Response

{
    "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//$metadata#WorkItems(WorkItemId,Title,State,Children,Children(WorkItemId,Title,State))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "State": "New",
        "Children": [{
            "WorkItemId": 48,
            "Title": "Story 15",
            "State": "Resolved"
        }, {
            "WorkItemId": 50,
            "Title": "Story 17",
            "State": "New"
        }, {
            "WorkItemId": 55,
            "Title": "Story 22",
            "State": "New"
        }]
    }]
}

Example: Child to parent query

By replacing Children with Parent in the $expand option, you can retrieve an item's ancestry.

Request

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?$select=WorkItemId,Title,State&$expand=Parent($select=WorkItemId,Title,State)&$filter=WorkItemId eq 105

Response

{
    "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//$metadata#WorkItems(WorkItemId,Title,State,Parent,Parent(WorkItemId,Title,State,Parent,Parent(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 105,
        "Title": "Task B",
        "State": "New",
        "Parent": {
            "WorkItemId": 55,
            "Title": "Story 22",
            "State": "New",
        }
    }]
}

Query for non-hierarchical links

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.

Example: Request an item's links

To retrieve the links associated with an item, you may $expand the Links navigation property. In this example the SourceWorkItemId, TargetWorkItemId, and LinkTypeName will be retrieved for all links associated with the work item.

Request

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId%20eq%20103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName)

Response

{
    "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 48,
            "LinkTypeName": "Child"
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 50,
            "LinkTypeName": "Child"
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 55,
            "LinkTypeName": "Child"
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related"
        }]
    }]
}

Example: Request details of linked items

You may include the details of your linked work items by using $expand on the TargetWorkItem or SourceWorkItem navigation properties. In this example, we'll retrieve the WorkItemId, Title, and State of the target work item for each link.

Request

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId%20eq%20103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$expand=TargetWorkItem($select=WorkItemId,Title,State))

Response

{
    "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 48,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 48,
                "Title": "Story 15",
                "State": "Resolved"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 50,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 50,
                "Title": "Story 17",
                "State": "Active"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 55,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 55,
                "Title": "Story 22",
                "State": "New"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

Example: Links of a specific type

You may also be interested in a particular type of link between items, in which case the LinkTypeName property can be used in a $filter. This query expands all 'Related' links and filters out all other link types.

Request

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId eq 103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$filter=LinkTypeName eq 'Related';$expand=TargetWorkItem($select=WorkItemId,Title,State))

Response

{
    "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

Next steps

Explore Analytics metadata

Query for linked work items

Parent-child hierarchy

Example: Parent to child query

Example: Child to parent query

Query for non-hierarchical links

Example: Request an item's links

Example: Request details of linked items

Example: Links of a specific type

Next steps

Feedback