TFS Integration Platform … why you should avoid narrow queries! Q&A-32

  • Article

First of all … “what is a narrow” query?

Narrow …?  Broad …?

In the context of TFS Integration Platform, a narrow query refers to the WIQL query that is associated with the WIT Session. For example,
<FilterItem MigrationSourceUniqueId="{88BD39F-…" FilterString="[System.WorkItemType] = ‘Defect’" /> … performs a query for all items of type Defect.

Let us assume that we want to synchronize team project X.Y from server 1 to team project Z on server 2 and vice versa, as shown in the following illustration:

Objective:
  • Synchronize all source to sync between “$/X.Y” and “$/X/Y”, which we can configure quite easily using filter pairs.
  • Synchronize all work items between X.Y with X, with the area and iteration values changed from “/X.Y/*” to “/X/Y/*
Options:
  • For work items (the second objective) we could create a filter pair query that reads all work items on either side and synchronizes them. Doing an all encompassing query from the root is regarded as a broad query.
  • For work items moving from right to left, we could create a query that selects by area path on Server 2 for Y. This only queries a selected portion of the work items and is regarded as a narrow query.
Notes:
  • The root node (X.Y on Server 1) is stripped off during delta computation and thus not available when performing value mapping. To work around this “feature”, you can use an aggregated field mapping to pre-pend Y to any paths coming from X.Y to X.

OK, so why avoid the narrow query it?

As long as all work items are sitting within X/Y the environment is happy. If, however, we move a work item to another area path, for example X/Z, the narrow query will no longer return the work item and it will therefore no longer be synchronized.

To conclude:

  • The recommended criteria for selecting work items is to either perform a broad query for all work items for the project, or to query by type.
  • The narrow query is possible, has its place, but is not recommended as changes may under certain circumstances not be synchronized as expected … state, data loss.

For more information on any of the above features, please refer to the Configuration documentation, that ships as part of the TFS Integration Platform.