URL Parameters - Nextedy Documentation

URL query parameters are surfaced to the sheet configuration as context.parameters.<name> and read through dynamic value expressions (() => …). Fed into a query where, they scope the query on the server at render time. For the parameter mechanism see URL Parameters; for how a where filters on the server see Server-Side Filtering; for the task see Open a Scoped Sheet with URL Parameters.

Reading a Parameter

where:
  severity: "() => context.parameters.domain"

For a URL ending in …&domain=HW, context.parameters.domain resolves to the string HW. Any parameter present on the URL is readable this way; declaring it in the parameters block (below) is only required for defaults and the required gate.

Configuration Surface

The same () => context.parameters.<name> expression applies across the source configuration:

Location	Applies to
`sources[].query.where`	The root query for the sheet.
`sources[].expand[].query.where`	An expanded level’s subquery, filtered independently of the current document.
`sources[].constraints.applyCurrentDocumentTo`	The entity type scoped to the current document (see Document Filtering).
`sources[].entityFactory`	Default values applied to newly created items.
`title`, `subtitle`, `icon`	The sheet header, evaluated against the context including `context.parameters`.

Server-Rendered Properties

Starting with Powersheet 26.7.2, URL parameters also reach server-rendered properties defined in the data model. Inside a serverRender Velocity template the values are read through $context.parameters.<name> — the server-side counterpart of the client-side () => context.parameters.<name> form:

$!context.parameters.domain

Read the parameter with Velocity’s quiet reference ($!context.parameters.<name>, with the ! immediately after the $) so a missing parameter renders blank instead of the literal reference text. A serverRender template driven by a URL parameter remains read-only — it can read Polarion data but not modify it. See Context Variables for the full behavior and a worked example.

The `parameters` Block

A top-level parameters object declares named parameters, keyed by parameter name (mirroring how columns and views are keyed). It drives defaults and the required gate:

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"

Property	Type	Description
`required`	`boolean`	When `true` and the parameter has neither a URL value nor a `default`, the sheet does not load; the missing-parameter message is shown instead.
`default`	`string`	Value used when the URL omits the parameter. A `default` also satisfies a `required` parameter.
`ifMissing.message`	`string`	Message shown when this required parameter is missing. Accepts a `() => …` dynamic value.
`ifMissing.button.label`	`string`	Label for the link shown in the missing-parameter dialog. Accepts a `() => …` dynamic value; when omitted, a generic label is used.
`ifMissing.button.url`	`string`	Target of the link, opened in the same tab. Accepts a `() => …` dynamic value. The button appears only when `button.url` is set.

Required and Optional Parameters

Optional (the default). A referenced parameter with no value drops its where condition, so the query runs without it and the broader set loads.
Required. A required parameter with no URL value and no default blocks the sheet. The dialog shows the first missing parameter’s ifMissing message and button; when several are missing, the message lists them all. Administrators additionally get an Open Configuration action.

A broken expression fails loudlyA parameter that has no value degrades gracefully (the condition is dropped). This is distinct from a malformed () => … expression, which raises an error during query construction rather than silently producing a filterless query.

Reserved System Parameters

Powersheet carries its own navigation state in URL parameters. Starting with Powersheet 26.7.2, these system parameters are prefixed with an underscore (_) so they cannot collide with your own parameter names. They also populate the corresponding typed context fields (see the note below).

Parameter	Legacy name	Purpose
`_project`	—	Current Polarion project.
`_document`	`document`	Current document.
`_revision`	`revision`	Historical revision to load (see baseline and revision queries).
`_title`	`documentTitle`	Document title carried from the Polarion link.
`_view`	—	Saved view to apply on load, by view id.
`_collection`	—	Id of the Polarion Collection to open the sheet in (see The `_collection` Parameter).
`_version`	—	Internal build cache-buster written by Powersheet. Do not set it yourself.

Reserve the leading underscore for Powersheet: do not give your own parameters names beginning with _.

Legacy names still open existing linksBefore 26.7.2 the navigation parameters had no underscore. The legacy bare names listed above (document, revision, documentTitle) are still honored so links saved in Polarion documents, wikis, and bookmarks keep working unchanged. When both the underscored and the legacy name are present on a URL, the underscored one wins. Writes only ever emit the underscored form, so a rewritten URL never carries two disagreeing copies. _project, _view, and _version are internal and never appeared in saved links, so they have no legacy alias.

Context fields are unchanged — no config edits neededThe rename applies to the URL only. The typed context fields a configuration reads — context.project, context.document, context.revision, context.documentTitle — keep their unprefixed names and behavior, so existing sheet configurations need no changes. And because the URL system names are now underscore-prefixed, a user-defined parameter named document (or any former reserved name) arrives verbatim in context.parameters.document and no longer affects navigation.

The `_view` Parameter

?_view=<id> opens the sheet in a saved view identified by its id. When _view is absent, the configured default view (if any) is applied instead. The value is part of the URL, so the selected perspective is shareable.

The `_collection` Parameter

?_collection=<id> opens the sheet inside a Polarion Collection: the sheet shows only the work items of the Collection’s documents, each at the revision the Collection pins for its document. Filters, expanded levels, item pickers and the links in cells follow the same Collection. See Collection-Scoped Sheets for the behavior and Open a Sheet in a Polarion Collection for the task.

Value	Behavior
Not specified, or blank	The sheet is not scoped and reads the live project.
A Collection id	The sheet opens inside that Collection. The id is the number in the Collection’s own Polarion URL.
Anything that is not a number	The sheet does not open. A Collection’s name is not accepted in place of its id.
A number that is no Collection of the project	The sheet reports that there is no Collection with that id.

The Collection is looked up in the sheet’s own project (_project), so a Collection owned by another project cannot be named. Unlike _revision, which shows the whole sheet at one revision and makes it read-only, _collection applies a revision per document, and rows from documents the Collection leaves live stay editable. Use one or the other: a _revision beside _collection makes the sheet read-only. The context.revision field is not set by _collection. Read the Collection through context.collectionId and context.collection (see Dynamic Value Expressions).

​Reading a Parameter

​Configuration Surface

​Server-Rendered Properties

​The parameters Block

​Required and Optional Parameters

​Reserved System Parameters

​The _view Parameter

​The _collection Parameter

​See Also

Reading a Parameter

Configuration Surface

Server-Rendered Properties

The `parameters` Block

Required and Optional Parameters

Reserved System Parameters

The `_view` Parameter

The `_collection` Parameter

See Also