URL Parameters - Nextedy Documentation

A Powersheet reads every value from its own URL query string into context.parameters, where the sheet configuration can pick it up. Because the values live in the URL, a view can be bookmarked, shared with a colleague, or reloaded and resolves to the same thing every time — without editing the stored configuration. You get a different view by changing the URL, not the configuration.

This mirrors how the built-in revision parameter lets you share a specific historical snapshot by URL.

Reading a parameter

You do not have to declare a parameter to read it — every value present on the URL is automatically available under context.parameters.<name>, keyed by the name you gave it in the URL. Read one through the dynamic value expression () => … form:

where:
  component: "() => context.parameters.device"   # from ?device=…

For a URL ending …&device=laptop, context.parameters.device resolves to the string laptop. Declaring the parameter (see below) is only needed for defaults and the required gate.

URL parameters work anywhere a `() =>` value is accepted

context.parameters is a plain map, and it is available in every place that accepts a () => … dynamic value — not only query filters. The same () => context.parameters.<name> expression works across the source configuration:

Surface	Example use
Query `where` (root or an expand subquery)	Scope which rows load on the server.
`entityFactory` defaults	Seed a new row with the slice it was created in.
Computed column (`formula`)	Fold a URL value into a calculated cell.
Cell `render`	Reflect a URL value in custom cell HTML.
`constraints.applyCurrentDocumentTo`	Choose (dynamically) which entity type is scoped to the current document.
Header `title` / `subtitle` / `icon`	State which slice is on screen — a label, project name, or icon driven by a URL value.

Which context object is available in each of these places is documented under Dynamic Value Expressions; this page is about getting values into context.parameters from the URL. Feeding a URL value into a query where is how a sheet is scoped on the server — see Server-Side Filtering for that mechanism.

Also in server-rendered properties

Starting with Powersheet 26.7.2, the same URL parameters also reach server-rendered properties. A serverRender Velocity template reads them through $context.parameters.<name> — the server-side counterpart of the client-side () => context.parameters.<name> form. Use it to compute a value on the server that depends on a URL parameter, for example narrowing a computed column to the slice named in the URL. Read the parameter with Velocity’s quiet reference ($!context.parameters.<name>) so a missing parameter renders blank rather than printing the literal reference text. See Context Variables for the full details and a worked example.

Declaring parameters

You declare a parameter only when you want to control what happens if it is absent — require it, or give it a default. The top-level parameters block is a map keyed by parameter name (the same shape as columns and views):

parameters:
  device:            # required -- the sheet won't open without ?device=…
    required: true
  approval:          # optional -- this value is used when ?approval is absent
    default: approved

Field	Effect
`required: true`	No URL value and no `default` — the sheet refuses to open and shows a message (see below).
`default: <value>`	Used when the parameter is absent from the URL. A `required` parameter that also has a `default` is satisfied by the default and will not block.

Guiding the user when a required parameter is missing

A bare “missing parameter” error is a dead end. Add ifMissing to turn the block into a way out — a message and an optional link to a page where the user can pick a valid value:

parameters:
  device:
    required: true
    ifMissing:
      message: "Pick a device to load its requirements."
      button:
        label: "Back to the overview"
        url: "() => `${context.polarionBaseUrl}/polarion/#/project/${context.project.id}/wiki/Index`"

The block dialog then shows your message and a button that opens button.url in the same tab. The button appears only when button.url is set; button.label falls back to a generic label when omitted. All three of message, button.label, and button.url accept the () => dynamic form, so both the label and the destination can be computed from context. Document administrators additionally see an Open Configuration button. If several required parameters are missing at once, the dialog lists them all and shows the message of the first one that declares an ifMissing.

What happens when a value is missing

Situation	Result
Declared `required`, no `default`	The sheet does not open; the user sees the message (and the optional `ifMissing` link).
Declared optional with a `default`	The `default` value is used.
Referenced but not declared, and absent	The condition that uses it is dropped — that filter quietly disappears and the level loads unfiltered.

A 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.

System parameters

Powersheet carries its own navigation and UI state in URL parameters too. Starting with Powersheet 26.7.2, these system parameters all begin with an underscore (_), which keeps them out of the way of your own parameter names:

Parameter	Purpose
`_project`	Current Polarion project.
`_document`	Current document.
`_revision`	Historical revision to load.
`_title`	Document title carried from the Polarion link.
`_view`	Saved view to apply on load, by view id.

Reserve the leading underscore for Powersheet: do not give your own parameters names beginning with _. Powersheet also writes an internal _version cache-buster onto the URL; you never set it yourself.

Before 26.7.2 these parameters had no underscore (document, revision, documentTitle). Those bare names are still honored for links saved in Polarion documents, wikis, and bookmarks, so existing links open exactly as before. When both the underscored and the legacy bare name are present, the underscored one wins.

Because system parameters are now underscore-prefixed, a parameter you name document (or any former reserved name) no longer collides with navigation state: it arrives verbatim in context.parameters.document and does not affect which document the sheet loads.

The typed context fields your configuration already reads — context.project, context.document, context.revision, context.documentTitle — keep their names and behavior. The underscore rename applies to the URL only, so existing sheet configurations need no edits.

Server-Side Filtering

The main thing URL parameters drive: filtering a sheet on the server so only the matching slice loads.

Open a Scoped Sheet with URL Parameters

Step-by-step: reference a parameter, build the shareable URL, and gate required values.

URL Parameters Reference

The parameters block schema, reserved names, and the full configuration surface.

Dynamic Value Expressions

The () => … syntax and the context object that context.parameters is read from.

​Reading a parameter

​URL parameters work anywhere a () => value is accepted

​Also in server-rendered properties

​Declaring parameters

​Guiding the user when a required parameter is missing

​What happens when a value is missing

​System parameters

​Related

Server-Side Filtering

Open a Scoped Sheet with URL Parameters

URL Parameters Reference

Dynamic Value Expressions

Reading a parameter

URL parameters work anywhere a `() =>` value is accepted

Also in server-rendered properties

Declaring parameters

Guiding the user when a required parameter is missing

What happens when a value is missing

System parameters

Related