Define a work item query to add to a process template

Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013

You can save work item queries as .wiq files that you can then add to a process template. For more information about how to create work item queries, see Define a query.

Prerequisites

• To create a query, you must be a member of the Readers group, or your View work items in this node permission must be set to Allow for each project in the query.
• To save a query as a team query, you must have the appropriate permissions described in Set permissions on queries.

Save a work item query as a .wiq file

You can install the Wiql Editor Marketplace extension to add import and export of .wiq files to the web portal. To learn more, see Cross-service and enhanced query operations.

Otherwise, you can use Team Explorer to save queries as .wiq files.

1. In Team Explorer, open the query that you want to save.

2. On the File menu, choose Save <name of query> [Query] As.

3. In the Save Query As dialog box, choose File, and specify a location and file name for the .wiq file. As an alternative, choose Browse, specify a file name, browse to the location to save the file, and then choose Save.

4. Copy the file to the \WorkItem Tracking\Queries folder, which is in the folder to which you downloaded your process template.

5. Open the .wiq file in a text editor.

6. Remove the <TeamFoundationServer> and <TeamProject> elements that associate the query with a specific server that is running Visual Studio Team Foundation Server and a specific project, as the following example shows:

   <TeamFoundationServer>CollectionURL</TeamFoundationServer>  
   <TeamProject>ProjectName</TeamProject>  
   

   Note

   You must edit the .wiq file in a text editor and remove the <TeamFoundationServer> and <TeamProject> elements that associate the query with a specific server and project. Otherwise, the query will not work correctly if the process template is uploaded to a different server. As an alternative, use macros where you can so that your query does not contain the explicit name of the current project or any other values that are specific to a certain environment.

7. Remove any additional elements that are specific to a user.

Create a work item query that references an iteration path

You can define a query that references a specific iteration path by including the macro for the project, $$PROJECTNAME$$, and the name of an iteration path that is defined in the Classification plug-in file. For example, the following syntax specifies a query that includes only those work items whose iteration path is under Iteration 1.

AND  [Source].[System.IterationPath] UNDER '$$PROJECTNAME$$\Iteration 1'  

When the project is created, the macro is replaced with the name of the project.

By using this macro, you can define workbooks that reference specific iteration paths. The Agile process template contains an iteration-specific query, Iteration1Backlog.wiq, that supports the iteration-specific workbook, Iteration Backlog.xlsm.

When you upload iteration-specific queries, the task to process the Classification.xml file must complete before the task to process the query files. For more information, see Define initial areas, iterations, and Project mapping file and Define the root tasks.

Example of an iteration-specific work item query

The following example shows the Iteration1Backlog work item query, which supports the Iteration Backlog workbook. For details on WIQL, see Work Item Query Language.

<?xml version="1.0" encoding="utf-8"?>  
<WorkItemQuery Version="1">  
  <Wiql>  
    SELECT [System.Id],  
           [System.WorkItemType],  
           [System.Title],  
           [System.State],  
           [System.AssignedTo],  
           [Microsoft.VSTS.Scheduling.RemainingWork],  
           [Microsoft.VSTS.Scheduling.CompletedWork],  
           [Microsoft.VSTS.Scheduling.StoryPoints],  
           [Microsoft.VSTS.Common.StackRank],  
           [Microsoft.VSTS.Common.Priority],  
           [Microsoft.VSTS.Common.Activity],  
           [System.IterationPath],  
           [System.AreaPath]  
      FROM WorkItemLinks  
     WHERE (Source.[System.TeamProject] = @project   
       AND  [Source].[System.AreaPath] UNDER @project  
       AND  [Source].[System.IterationPath] UNDER '$$PROJECTNAME$$\Iteration 1'  
       AND (  
               Source.[System.WorkItemType] = 'User Story'   
            OR Source.[System.WorkItemType] = 'Task'  
           )  
           )  
       AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'  
       AND [Target].[System.WorkItemType] = 'Task'  
       ORDER BY [Microsoft.VSTS.Common.StackRank], [Microsoft.VSTS.Common.Priority]  
       mode(Recursive)  
  </Wiql>  
</WorkItemQuery>  

WorkItemQuery element reference

The following syntax shows the structure of the WorkItemQuery element and its child elements.

<WorkItemQuery Version="1">  
      <TeamFoundationServer>collectionURL </TeamFoundationServer>  
      <TeamProject>TeamProjectName </TeamProject>  
      <Wiql>  
      WorkItemQueryLanguage  
      </Wiql>  
</WorkItemQuery>  

Related articles

• About managed queries
• Cross-service and enhanced query operations
• Define a query
• Define objects for tracking work items
• Work Item Query Language
• Wiql Editor, a Marketplace extension