Share via

Add work item queries to a process template

  • Article

By adding work item queries to your process template, you can define the initial set of shared queries and query folder structure for a team project. All team members use queries to find the bugs, tasks, and other work items on which they must take action.

Work item queries specify criteria for generating a list of work items, such as a list of active bugs or closed tasks. Files for work item queries have a .wiq extension and are stored in the Queries subfolder of the WorkItem Tracking folder for Microsoft Solutions Framework (MSF) process templates.

Important

Microsoft process templates define several queries. For more information, see Shared queries (Scrum), Shared queries (Agile), and Shared queries (CMMI). Query definitions depend on the fields and types of work items in the process template. Also, some workbooks that are uploaded within the Portal plug-in depend on the query definitions.

You specify the query definitions to upload as a task within the WorkItemTracking plug-in. This task may be required because several artifacts in a process template may depend on a query. In addition, the task to upload queries depends on the successful completion of the task for uploading work item types. You specify each query file to upload within the taskXml element.

In this topic

  • Creating a File for a Work Item Query

  • Specifying Queries to Upload

  • QUERIES Element Reference

After a team project is created from the process template, you can add, remove, and change queries by using the Query Editor. For more information, see Query for work items.

For information about how to assign query permissions to groups, see Control access to functional areas. For information about how to create query folders, see Define objects for tracking work items using the work Item tracking plug-in.

Creating a File for a Work Item Query

Each query definition must be specified in its own file with an extension of .wiq, using the WorkItemQuery parent element, and conform to the schema that is defined in the wiq.xsd file. You can download the schema files for tracking work items from the following page on the Microsoft website: Process Template and Work Item Schemas for Visual Studio Team Foundation.

The following example shows the high-level syntax structure that defines a work item query:

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

For more information about how to create a work item query to add to a process template, see Define a work item query to add to a process template.

Back to top

Specifying Queries to Upload

To include the work item queries in the process template, create one or more tasks in the workitems.xml file, which you can find in the \WorkItem Tracking folder, which is in the folder to which you downloaded your process template. Use the Query element to specify the file for the work item query. For example, the following XML specifies the query that is defined in the ActiveBugs.wiq file to be uploaded and named Active Bugs.

<Query name="Active Bugs" fileName="WorkItem Tracking\Queries\ActiveBugs.wiq" />

You add the set of queries to upload as a task in the WorkItemTracking plug-in.

The following example shows how to specify a task to create a query folder that is named Product Management and upload a query that is named All User Stories to that folder.

<task id="Queries" name="Stored Query Definitions" plugin="Microsoft.ProjectCreationWizard.WorkItemTracking" completionMessage=" Work item queries uploaded" />
   <dependencies>
      <dependency taskId="WITs" />
   </dependencies>
   <taskXml>
      <QUERIES>
         <QueryFolder name="Product Management" >
            <Query name="All User Stories" fileName="WorkItem Tracking\Queries\AllUserStories.wiq" />
         </QueryFolder>
         . . .
      </QUERIES>
   </taskXml>
</task>

For more information, see Define objects for tracking work items using the work Item tracking plug-in.

Back to top

QUERY Elements

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

<QUERIES>
   <Permission />
   <QueryFolder >
      <Query />
   </QueryFolder>
</QUERIES>

The following table describes the elements that you use to specify the query folder structure, permissions, and queries to upload. You specify these elements within a taskXml container element in the WorkItemTracking plug-in file.

Element

Syntax

Description

Permission

 
<permission allow="ListOfPermissions" identity="GroupName" />

Optional child element of Query.

Specifies the default permissions that are assigned to shared queries. For more information, see Assigning Permissions for Work Item Queries.

Query

 
<Query name="QueryName" fileName="QueryFilePathName" />

As the following example shows, you can upload the query that is labeled “Active Bugs” and that is defined in the ActiveBugs.wiq file:

<Query name="Active Bugs" fileName="WorkItem Tracking\Queries\ActiveBugs.wiq" />

Required child element of QUERIES.

Specifies the name and the path of the .wiq file that defines a query to upload.

QueryFolder

 
<QueryFolder name="FolderName">
   <Query />
</QueryFolder>

Optional child element of QUERIES.

Specifies the name of a query folder.

QUERIES

 
<QUERIES>
   . . . 
</QUERIES>

Optional child element of the taskXml element for the WorkItemTracking plug-in.

Specifies which query definition files to use to create default queries.

Back to top

See Also

Concepts

Query for work items

Define objects for tracking work items using the work Item tracking plug-in