Open a Scoped Sheet with URL Parameters

This guide shows how to make one sheet configuration serve many pre-filtered views by reading values from the URL. Each parametrised URL scopes the query on the server, is shareable, and survives a refresh. For the underlying ideas, see URL Parameters (how values reach the configuration) and Server-Side Filtering (how a where scopes the query on the server).

Prerequisites

A sheet configuration with at least one data source
Familiarity with dynamic value expressions (() => …)
A property you want to filter on (a primitive field or an enum id)

Reference a Parameter in the Query

In the source query.where, replace a fixed value with a dynamic expression that reads a URL parameter. The parameter name (domain here) is yours to choose:

sources:
  - id: user_needs
    query:
      from: UserNeed
      where:
        severity: "() => context.parameters.domain"

Each key in a where object is combined with AND, so you can keep fixed conditions alongside parameter-driven ones.

Open the Sheet with the Parameter in the URL

Append the parameter to the sheet’s URL as a normal query parameter:

…?_document=<doc>&domain=HW

The value HW is injected into the query before it runs, so Polarion returns only the matching rows. Change domain=SW and the same configuration returns the software slice instead. The URL is shareable and reloads to the same data.

A Powersheet sheet opened with match=Dosage in the URL, showing only the two user needs whose title contains “Dosage”, under a header that reads “User Needs matching “Dosage””. — A sheet whose query reads a URL parameter returns only the matching rows. In this example the parameter is named match, so opening the sheet with ?…&match=Dosage returns just the user needs whose title contains “Dosage”.

In a typical setup the parametrised link is constructed by the entry point that opens the sheet — for example a Polarion custom report or a document link that appends the parameter. The sheet itself only reads whatever parameters are present on its URL.

Filter an Expanded Level Independently

A parameter can also scope a downstream (expanded) entity level, independently of the current document. Add a query.where to the expand node:

sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: requirements
        expand:
          - name: requirement
            query:
              where:
                targetSystem: "() => context.parameters.system"

Opening the sheet with …&system=iOS shows only the expanded requirements whose targetSystem is iOS, while the parent rows are unaffected. See Expand Navigation Properties for expand subqueries in depth.

Declare Required and Optional Parameters

Without a value, a parameter-driven where condition is simply dropped and the sheet loads the broader set. When loading everything would be too heavy, declare the parameter in a top-level parameters block and mark it required, optionally giving it a default:

parameters:
  domain:
    required: true
    ifMissing:
      message: "Choose a domain to open this view."
      button:
        label: "Open selection page"
        url: "/polarion/…/select-domain"
  status:
    default: "open"

A required parameter with neither a URL value nor a default blocks the sheet and shows the ifMissing message and button (administrators additionally get an Open Configuration action).
A default fills in the value when the URL omits it.

A “Missing required parameters” card with the configured ifMissing message and its button, plus an admin-only Open Configuration action. — Opening the sheet without a required parameter blocks it and shows the ifMissing message and button instead of loading everything. An administrator additionally sees the Open Configuration action.

Show a Readable Label in the Header

The sheet header — title, subtitle, and icon — accepts dynamic values too, so it can state which slice a parametrised URL opened. Reflect the parameter in the sheet’s name, add the project name, and pick an icon per variant:

title:    "() => context.parameters.viewLabel"
subtitle: "() => `${context.project.name}: Domain ${context.parameters.domain}`"
icon:     "() => context.parameters.domain === 'HW' ? 'DeveloperTools' : 'Code'"

The whole value must be a single () => … expression — build any surrounding text inside it (a template literal or concatenation) rather than mixing literal text with () =>. When an expression resolves to nothing, title falls back to the document name, while subtitle and icon are hidden. See the Sheet Header reference for icon glyph-vs-image values and the full fallback rules.

A sheet header whose title reads “User Needs matching “Dosage”” with a project-name subtitle and an icon, all derived from the URL parameter. — The header title, subtitle, and icon are computed from the URL parameter, so the same configuration states which slice is on screen.

Open the Sheet in a Specific View

Saved views can be selected from the URL with the reserved _view system parameter, using the view’s id:

…?_document=<doc>&_view=traceability

On load, the sheet applies the referenced view (or the configured default view when _view is absent). Because _view is part of the URL, the chosen perspective is shareable along with the data scope.

Verify Your Configuration

Open the sheet with a parameter value in the URL and confirm only the matching rows load.
Change the value and reload — the data slice should change accordingly.
Remove a required parameter from the URL and confirm the sheet shows the missing-parameter message rather than loading everything.
Copy the full URL into a new tab and confirm it resolves to the same scoped view.

The same sheet opened with match=Glucose, now showing only the user need whose title contains “Glucose”, under a header that reads “User Needs matching “Glucose””. — Changing the parameter value re-scopes the same configuration: ?…&match=Glucose returns a different slice than match=Dosage, and the header updates to match.

​Prerequisites

​Verify Your Configuration

​See Also

Prerequisites

Verify Your Configuration

See Also