Skip to main content
This page is a deep dive into Project Mode swimlane scoping — how a board that spans multiple Polarion projects controls exactly which projects appear, and what else changes once it does.

​
Scoping with Project Query

Project Mode’s swimlane list isn’t limited to “every sub-project in the current group.” The Project Query widget parameter is a Lucene query, evaluated once per board load, that defines exactly which projects belong on the board. Set it to describe the projects you’re planning for, and only those appear. Project Query filters three things at once, from the same query:
  • Which projects show up as swimlanes.
  • Which work items get loaded onto the board.
  • Which Plans appear as columns.
The unplanned-items sidebar respects it too. Because the scope lives in the query rather than in the page the widget is embedded on, the same board keeps working even if projects are later reorganized into different project groups.
If no Project Query is set, the board falls back to discovering sub-projects of the current project group, as described in Project Mode. Setting Project Query explicitly is recommended for any board meant to keep tracking a specific, fixed set of projects.

​
Query Examples

Any indexed project field can be used — not just id and name — including custom project fields.
Changing the Project Query re-computes swimlanes, loaded work items, and the dependency/parent role menus (below) immediately — there’s nothing else to refresh.

​
Filtering with a Page Parameter

To let planners choose the projects themselves — rather than editing a fixed query each time — Project Query can be driven by a page parameter instead of a literal string. This starts with a page parameter that lets planners pick one or more projects — for example, one named Projects, added via the page’s Parameters flyout (gear icon). Its type is typically Enumeration, so people can select from real Polarion projects rather than typing IDs. Unlike the general work-items Query field, which accepts Velocity syntax typed directly into the field, Project Query does not — typing a page-parameter reference straight into it does not work. Project Query only supports binding to a page parameter through the gear icon, and only to a String-typed parameter. Projects itself, being Enumeration-type, isn’t String-typed, so it can’t be bound directly either — it never appears in that gear icon’s list at all. The fix is a Page Script that reads Projects, computes the full query clause as a string, and exposes it as a new scripted parameter:
Then click the gear icon on Project Query → Parameters, and select Projects Query — the scripted parameter, not the raw project-picker parameter.
The scripted parameter’s value becomes the entire content of the Project Query field — there’s no surrounding id:(...) for it to slot into. Compute the complete clause, including the field prefix, inside the Page Script itself; don’t expose just the bare .toLucene() output.
The page parameter’s selectable projects still need to fall within Scope — Scope restricts the searchable project set before Project Query ever runs. A project outside Scope never appears, no matter what Project Query says.
The id: field prefix used above has not been independently confirmed against a live Project Query field — it’s inferred from the static query examples elsewhere on this page, which query project documents directly. A related, more general Planningboard query field uses project.id: instead (see Work Items Parameters), which filters work items rather than projects. Confirm which prefix Project Query actually expects before relying on this in production.

​
Cross-Project Board Behavior

​
Dependency and Parent Role Menus

Two menus need to work across every project a board shows: Work Items → Dependency Roles and Unplanned Sidebar → Parent Roles. Each Polarion project can define its own workitem-link-role enumeration, which replaces the global one — so the same logical role (e.g. “depends on”) can have a different internal ID per project. Both menus are built from the union of link roles across every project the board currently shows, so a role from any in-scope project can be selected, regardless of which project’s page the board lives on. How roles are labelled:
  • Options are keyed by role ID, titled by role name.
  • If multiple projects use the same ID with different names, they collapse into one option listing all names joined by / — e.g. depends on / requires.
  • If a role has no name anywhere, its ID is shown as the title.
  • Once more than one project is in scope, a selected role’s ID is appended in parentheses — depends on (depends_on) — so overlapping names stay distinguishable. Only selected roles get this treatment, to keep the rest of the list readable.
See Dependencies and Links for the general link/dependency model this builds on.

​
Swimlane Order

Project Query is a pure include/exclude filter — it doesn’t control order. Swimlanes are ordered the same way projects appear in the Polarion project tree (the project group hierarchy), and the query is applied after that order is resolved. For example, if a group contains [alpha, beta, gamma, delta] in that order and the query matches [beta, delta], the swimlanes appear as beta | delta — in hierarchy order, not query-match order.

​
Merged Iteration/Release Columns

Say two projects each run a Plan with the same plan ID — Iteration_35. The board’s column key used to combine the project with the plan (effectively alpha/Iteration_35 vs. beta/Iteration_35), so two projects sharing a plan ID produced two separate columns with the same name — and the more projects on the board, the more duplicate columns piled up. Plans that share the same plan ID now collapse into a single column, regardless of how many projects define them:
  • One column per iteration/release ID, however many projects run it.
  • A work item still belongs to the Plan of its own project — it shows up in the merged column, in its own project’s swimlane row.
  • Dropping a card into a merged column plans it into that project’s own Plan with that ID; nothing is written to other projects’ Plans.
  • Matching is on the full plan ID, not a prefix — Iteration_35 and Iteration_350 stay separate columns.

​
Common Misconceptions

“Which projects appear is decided by where the widget is placed.” Only when Project Query is left empty. Placement (inside a project, inside a project group, or at global scope) is a fallback default, not the primary mechanism — Project Query is what actually controls scope. “Project Query and Scope are the same setting.” They aren’t. Scope restricts the searchable project set before Project Query ever runs; Project Query then filters within whatever Scope allows. A project excluded by Scope never appears, regardless of what Project Query says. “Project Query controls the order swimlanes appear in.” It doesn’t — it’s a pure include/exclude filter. Order always follows the Polarion project group hierarchy, applied after the query has already narrowed the set. “Two projects with a plan of the same ID always produce duplicate columns.” Not anymore. Plans sharing the same plan ID collapse into a single column regardless of how many projects define them — see Merged Iteration/Release Columns above.
Last modified on August 20, 2026