Dela via

Define a Work Item Query to Add to a Process Template

  • Artikel

You can create a work item query (.wiq) file most easily in Team Explorer. In an existing team project, you can use Team Explorer to create all work item queries that you want to add to your process template and then follow the steps in this topic to save each query as a .wiq file. For more information about how to create work item queries, see Specify Query Filter Criteria.

In this topic

  • Saving a Work Item Query as a .Wiq File

  • Creating a Work Item Query That References an Iteration Path

  • Example of an Iteration-Specific Work Item Query

  • WorkItemQuery Element Reference

Required Permissions

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 team project in the query. To save a query as a team query, you must have the appropriate permissions. For more information, see Organize and Set Permissions on Work Item Queries.

Saving a Work Item Query as a .Wiq File

To save a work item query to a .wiq file

  1. In Team Explorer, right-click the query, and then click View Query.

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

  3. In the Save Query As dialog box, click File, and specify a location and file name for the .wiq file. As an alternative, click Browse, specify a file name, browse to the location to save the file, and then click 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 team 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 team 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 team project or any other values that are specific to a certain environment.

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

Back to top

Creating 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 team 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 team project is created, the macro is replaced with the name of the team project.

By using this macro, you can define workbooks that reference specific iteration paths. The process template for MSF agile software development 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 Defining the Initial Areas and Iterations in the Classification Plug-in and Defining the Root Tasks Using the Process Template Plug-in File.

Back to top

Example of An Iteration-Specific Work Item Query

The following example shows the Iteration1Backlog work item query, which supports the Iteration Backlog workbook.

<?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>

Back to top

WorkItemQuery Element Reference

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

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

Element

Syntax

Description

TeamFoundationServer

 
<TeamFoundationServer>collectionURL
</TeamFoundatonServer>

Optional child element of WorkItemQuery.

Important noteImportant
In general, you remove this element from queries that you add to process templates.

Specifies the URI of the team project collection in the following format:

http://ServerName:Port/VirtualDirectoryName/CollectionName

If no virtual directory is used, use the following format for the URI:

http://ServerName:Port/CollectionName

The attribute type is ServerNameType with a maximum length of 2047.

TeamProject

 
<TeamProject>TeamProjectName</TeamProject>

Optional child element of WorkItemQuery.

Important noteImportant
In general, you remove this element from queries that you add to process templates.

Specifies the team project against which to run the query.

The attribute type is ProjectNameType with a maximum length of 255 characters.

Wiql

 
<Wiql>WorkItemQueryLanguage</Wiql>

Required child element of WorkItemQuery.

Specifies a sequence of Structured Query Language (SQL) commands that act as filter criteria to find a set of work items in a team project and return the values that are assigned to a set number of fields.

The MSF process templates provide several examples of the SQL commands that the Wiql element supports. These files are located in the Queries folder of the WorkItem Tracking folder. For more information about how to define queries, see Finding Bugs, Tasks, and Other Work Items.

Back to top

See Also

Concepts

Finding Bugs, Tasks, and Other Work Items

Defining and Customizing Objects for Tracking Work Items By Using the Work Item Tracking Plug-in

Change History

Date

History

Reason

April 2011

Described each WorkItemQuery element, and removed links to deleted topics.

Information enhancement.