Widget - Cross tracker search

The Cross trackers search widget lets you search for artifacts across multiple trackers and multiple projects simultaneously, directly from your dashboard. It relies entirely on the TQL (Tuleap Query Language) query language to select columns to display, define data sources, and filter results.

It is an ideal tool for getting cross-cutting views of your activity: tracking your assigned artifacts across projects, multi-tracker reporting, information consolidation, etc.

Installation note

This widget is available on both Project dashboards and the Personal dashboard. Its behavior differs slightly depending on the context (see the Differences between project and personal dashboards section).
The Cross Tracker Search plugin must also be installed and activated by the platform administrator.

Creating a query

The widget works entirely through queries written in TQL. A query is made up of four clauses:

• SELECT — the columns to display in the results table

• FROM — the projects and trackers to query

• WHERE — the artifact filtering conditions

• ORDER BY (optional) — the result sorting

Warning

You must have read access to the trackers you want to query.

Writing a query

On first use, or when you create a new query, the widget presents a TQL text editor. Type your query directly into this editor.

Example query on a project dashboard:

SELECT @pretty_title, @status, @last_update_date, @submitted_by
FROM @project = 'self'
WHERE @status = OPEN()
ORDER BY @last_update_date DESC

Example query on a personal dashboard:

SELECT @pretty_title, @project.name, @last_update_date, @submitted_by
FROM @project = MY_PROJECTS()
WHERE @assigned_to = MYSELF() AND @status = OPEN()
ORDER BY @last_update_date DESC

Info

The TQL editor provides syntax highlighting and auto-completion (Ctrl+Space) to help you build your queries. You can also use Ctrl+Enter to run a search (preview) without leaving the editor. For a complete reference of the TQL syntax available in this widget, see the official documentation: TQL in Cross-Tracker Search.

Using query suggestions

When creating a new query, the widget offers predefined query suggestions. These suggestions are tailored to the dashboard context:

On a project dashboard, three suggestions are available:

• All open artifacts — Displays all open artifacts in the current project.

• Open artifacts assigned to me — Filters on open artifacts assigned to the logged-in user.

• All artifacts created in the last 10 days — Displays recently created artifacts in the project.

On the personal dashboard, one suggestion is available:

• Open artifacts assigned to me in my projects — Displays open artifacts assigned to the logged-in user, from all projects they are a member of.

Click on the desired suggestion to pre-fill the editor with the corresponding query. You can then adapt it to your needs before saving.

Saving a query

Once your query is written:

1. Enter a title (required) in the Name your query field to easily identify this query.

2. Add a description (optional) in the Write your description field to clarify the purpose of the query.

3. If desired, toggle the Make this query displayed by default option so that this query is automatically presented when the widget is opened.

4. Click Save.

The widget supports saving multiple queries per widget instance. You can navigate between your saved queries to view different perspectives.

Editing a query

1. Click the Query details button.

2. Click directly on the displayed query or on the Edit button.

3. Modify the title, description, or TQL query.

4. You can click Search to preview the results of the modified query without saving it.

5. Click Save to confirm the changes, or Cancel to return to the query without saving your changes.

Information

Only users with dashboard editing permissions (project administrators for a project dashboard, or the owner for a personal dashboard) can create, edit, or delete queries. Other users only see read-only results.

Deleting a query

1. Click the Query details button.

2. Click the Delete button.

3. A confirmation dialog appears. Confirm the deletion.

Warning

Deleting a query is permanent. Other dashboard users will no longer have access to it.

Browsing and switching between queries

By default, the widget directly displays the results of the active query (the default query, or the first saved query). To access query details:

1. Click the Query details button.

2. The details panel opens, showing the title, description, and associated TQL query.

To switch between queries:

1. Click Choose another query. A dropdown menu appears with the list of all saved queries for this widget.

2. Use the built-in search field in the menu to filter queries by title if the list is long.

Info

If you are a dashboard administrator and no query exists yet, the widget automatically displays the query creation panel. Read-only users will see an empty state.

Results table

Pagination

Results are displayed in pages of 50 artifacts maximum. If your query returns more than 50 results, Previous and Next buttons appear at the bottom of the table to navigate between pages.

Direct access to an artifact

Each row in the results table has an icon allowing you to open the artifact in its original tracker. Click this icon to access the artifact detail page.

Tip

Hover over title or text cells to display a tooltip with the full content, useful when text is truncated in the column.

Artifact links

When displayed artifacts have links (parent/child, test coverage, etc.), the widget can show these relationships as visual arrows and link type information. You can expand an artifact's links to see their details.

Displayed columns

The table columns are determined by the SELECT clause of your TQL query. See the TQL SELECT documentation for the full list of available columns (semantics, dynamic fields, custom fields, etc.).

Export XLSX

You can export the results of a saved query in XLSX (Excel) format.

When you click the Export XLSX button, two export modes are offered if the results span multiple pages:

• Export all — Exports all artifacts matching the query (all pages), without artifact links. This is the most common mode for getting a complete export.

• Export with links — Exports only the artifacts on the current page, along with their links (forward and reverse links) visible in the widget. This mode is useful for preserving artifact relationships in your export.

Warning

Only some field types can be exported as XLSX:

• Text fields (String, Text)

• Numeric fields (Integer, Float)

• Date fields (with or without time)

• Single-selection lists (Selectbox, Radio button)

Multi-selection lists (Multi-selectbox, Checkbox) and other field types are not yet supported and will be skipped during export.

Differences between project and personal dashboards

The Cross trackers search widget is available in both dashboard contexts, but its behavior differs on several points.

FROM clause: selecting projects and trackers

The main difference concerns how to target projects in the FROM clause of your TQL queries:

Project dashboard:

• @project = 'self' — Targets the current project. This is the most common value in this context.

• @project = 'aggregated' — Targets aggregated projects for a Program project type.

• @project IN('self', 'aggregated') — Combines the current project and its aggregated projects.

• @project.name = 'project_name' — Targets a specific project by its short name.

• @project.category = 'Topic::Hardware' — Targets projects in a given category.

Personal dashboard:

• @project = MY_PROJECTS() — Targets all projects you are a member of. This is the most common value in this context.

• @project.name = 'project_name' — Targets a specific project by its short name.

• @project.category = 'Topic::Hardware' — Targets projects in a given category.

Attention

@project = 'self' and @project = 'aggregated' are not usable on the personal dashboard (an error will be displayed). Conversely, on a project dashboard, the project condition is optional in FROM: if absent, the query will implicitly target the current project.

Info

On the personal dashboard, the project condition is mandatory in the FROM clause. For more details, see the TQL FROM documentation.

Query suggestions

The suggestions offered are adapted to the context:

• Project: suggestions use @project = 'self' to stay within the project scope.

• Personal: suggestions use @project = MY_PROJECTS() and include the @project.name column to identify where artifacts come from.

Recommended columns

On a personal dashboard, it is recommended to include @project.name in your SELECT clause to easily identify which project each artifact belongs to, since results potentially come from multiple projects.

Common use cases

Consolidated view of my tasks

On your personal dashboard, create a query to see all artifacts assigned to you across your projects:

SELECT @pretty_title, @project.name, @tracker.name, @status, @last_update_date
FROM @project = MY_PROJECTS()
WHERE @assigned_to = MYSELF() AND @status = OPEN()
ORDER BY @last_update_date DESC

Tracking tickets in a support project

On a project dashboard, track open tickets in a specific tracker:

SELECT @pretty_title, @status, @assigned_to, @submitted_by, @last_update_date
FROM @project = 'self' AND @tracker.name = 'ticket'
WHERE @status = OPEN()
ORDER BY @last_update_date DESC

Multi-project search by category

Query all projects in a given category for a cross-cutting view:

SELECT @pretty_title, @project.name, @status, @assigned_to
FROM @project.category = 'Topic::Team' AND @tracker.name IN('epic', 'story')
WHERE @status = OPEN()
ORDER BY @last_update_date DESC

Searching for linked artifacts (parents/children)

Use the link search syntax to find artifacts based on their relationships:

SELECT @pretty_title, @status
FROM @project = 'self'
WHERE @status = OPEN() AND WITHOUT PARENT

Info

For a complete reference of the TQL syntax (conditions, operators, link search, aliases, etc.), see the TQL in Cross-Tracker Search page.

Permissions

The widget distinguishes two access levels:

Dashboard administrators (project administrators or personal dashboard owner):

• Create, edit, and delete queries

• Set the default query

• All viewing and export actions

Read-only users:

• View results of saved queries

• Navigate between queries and result pages

• Export results to XLSX

• Access artifacts from the results table

The Edit, Delete, and Create new query buttons are only visible to administrators.

Common errors

• Using @project = 'self' on the personal dashboard — This syntax is not supported in a personal context. Use @project = MY_PROJECTS() or @project.name = 'project_name' instead.

• Using @project = 'aggregated' outside a Program project — This syntax is only supported on the dashboard of a project with the Program Management service enabled.

• Missing SELECT, FROM or WHERE clause — All three clauses SELECT, FROM, and WHERE are mandatory in a Cross-Tracker Search query.

• "No artifact found" — The FROM clause does not match any tracker you have access to. Check the project and tracker names.

Info

For the full list of possible errors (syntax, incompatible fields, query too complex, etc.), see the Errors section of the TQL documentation.