@CurrentIteration, Team Parameter, Offset
With our Sprint 131 update (rolling out over the next few weeks), there are some major changes coming to the @CurrentIteration macro used for work item queries. We are introducing the concept of a macro parameter, as well as allowing an offset to @CurrentIteration. These updates are mainly motivated by:
- A desire for queries to return the same results regardless of your team selection in our navigation
- A highly upvoted User Voice item for the ability to query for items in past and future iterations
- A way to use the macro to reference different iterations in the same query. For example, to look at the active work of two teams in different projects in their respective current iterations.
Using the Team Parameter
Now when you create or modify a query with the @CurrentIteration macro, you will be required to also select the team whose iteration schedule you would like to use. In the query editor UI, this selection will be made via an inline dropdown:
If you are using our Work Item Query Language (WIQL), you will also be required to specify the team as a parameter to the macro. The syntax for that would be as follows:
… WHERE [System.Iteration] = @CurrentIteration(‘[Project]\Team’) …
With the team parameter, you can use the @CurrentIteration macro in the same query for different teams. This means you can now query for work items in two different team projects using different iteration names and even schedules! This satisfies another highly upvoted User Voice item.
Updating Existing Queries
You will not be able to save modifications to the query unless the team parameter has been specified. However, you will still be able to run the query without the new parameter and it will continue to choose a team based on your context and prompt you to save changes to the query via a banner.
For Queries run from the hub, the populated team will be the one you have selected in the upper left corner of the navigation. For Dashboards, the detected team is the one who owns the Dashboard where the query widget is pinned. This means your Dashboard widgets will continue to return expected results, regardless of whether you have taken advantage of the macro updates.
Using Offset with @CurrentIteration
You can now choose to specify an integer offset that follows the @CurrentIteration macro to query for past and future sprints in a rolling window. The Editor will include +1 and -1 as suggested offsets, but you can choose to input your own offset value, just like you can with the @Today macro.
If you are writing WIQL rather than using the query UI, you will use the same syntax as @Today. In the example below, I am querying for the features we have planned in the next two sprints for my team, WIT IQ.
… WHERE [System.Iteration] = @CurrentIteration(‘[VSTS]\WIT IQ’) + 1
OR [System.Iteration] = @CurrentIteration(‘[VSTS]\WIT IQ’) + 2 …
Running @CurrentIteration Queries in Visual Studio
The new Team parameter is a change to the WIQL that previously shipped versions of Visual Studio will not know how to interpret and render in the Query editor. To prevent you from encountering errors when opening your existing queries in Visual Studio, we will ignore the team parameter as a requirement for running the query. This means you will still be able to view query results with the iteration calculated based on your connected team from Team Explorer. To ensure the same results between web access and Visual Studio, be sure to connect to the same team you choose for the parameter.
You can edit the query and change columns, but you will not be able to save changes to a query from Visual Studio because we require all new queries to have a team parameter moving forward. Instead, you will be prompted to open the query in the web where we can support editing the macro with the team parameter.
If you take advantage of the new offset functionality, your query will not run at all in Visual Studio. Again, this is because previously shipped versions of Visual Studio will not know how to interpret and render the offset selection in the Query Editor. You will see your queries in Team Explorer fail to load a result count. An icon by the query name will indicate the query has a syntax error.
We hope to enrich our macro experience with the use of parameters in the future. There are many turns of the dial here, but some ideas include:
- @Today(Time Zone) – explicitly define a time zone in your query so that all your team members see the same results, regardless of their datetime preferences
- @Areas(Team) – easily reference the area paths owned by a team without writing multiple clauses
- @LinkedTo(Link Type, ID) – find work items based on their link relationships with other work items and artifacts
Have questions or feedback?
Feel free to post questions or feedback below and be on the lookout for these changes coming to your VSTS account over the next couple of weeks!