Context
As of Tuleap 16.0, cross tracker search widget displays the TQL query by default. Unless reader perfectly understands TQL, it's quite hard to tell what is displayed and even for those who master TQL, it's inconvenient to read to remember what the query covers. The current alternative is to place the widget in a dashboard with a descriptive name.
In order to improve the user experience in this area, we associate a name and a description to the query. The name will be displayed by default instead of the whole query.
We also want to leverage on the feedback we have on the usage of reports in trackers. The main problems are that
- People don't understand they are seeing a filtered view of their artifacts.
- People don't understand there are multiple filters (reports) and they can switch from one to another.
- The term "report" itself seems confusing.
In the context of Cross Tracker Search widget, we are going to use the term "Query" to designate the search that is done. A Query is made of
- a TQL query
- a title
- a description
Query scope
Queries will not be tight to a given widget but to the scope where they are defined. If a query was tight to a widget, deletion of the widget would delete the query. There are two different Query Scopes that corresponds to the scope of the dashboards where the widget can be used
Pinned queries
Given that queries are not tight to a widget, it means that all queries of a scope would be visible in all widgets of this scope.
For instance, let's take "Deserts" Project, with three dashboards that corresponds to a internal breakdown of activities: Atacama, Gobi, Sahel. Those 3 dashboards have a cross tracker search widget to present "Open Atacama artifacts", "Open Gobi artifacts" and "Open Sahel artifacts".
Given that queries are shared across widgets of same scope (here project) it would mean that on "Atacama" dashboard, one could select to see "Open Gobi artifacts". This would lead to confusion.
The solution is to have widgets with Pinned Query. Those widget would have one and only one Query with no possibility to select another one (on the longer run we might relax the constraint to allow more than one query but we choose to let the need emerge and to adapt).
Cross Tracker Search Widget will have two modes:
- Pinned: Only one query is selected.
- Not pinned: all queries are available.
Personal queries
Unlike Tracker Reports, it will not be possible to have personal queries on a project widget. If a user sees a query on a project dashboard and want to modify it, we will provide guidance and tooling to replicate the project query inside a personal dashboard.
Acceptance criteria
A query can be defined
- By Tuleap itself
- By a project admin for project queries
- By a user for user queries
At widget level
- By default, all queries are displayed
- Project widget: all Tuleap queries with "project" scope + project defined queries
- User widget: all Tuleap queries with "user" scope + user defined queries
- one (user for personal widgets, project admin for project widgets) can "pin" a query. When a query is pinned, it's the only one that can be run on widget. Other queries are not displayed.
It should be possible to copy queries across scopes (project -> user, user -> project) with "smart" copy to handle aggregated
and self
. One of the technical possibilities here would be to change aggregated
magic string by a dedicated "function" AGGREGATED()
that could take a parameter to make it usable elsewhere (AGGREGATED('guinea-pig')
). SELF()
would be added too to make it consistent.