> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# URL Parameters

> Reference for URL-driven parameters in Nextedy POWERSHEET: the parameters block schema, reserved system names, and every configuration surface where a URL value applies against Siemens Polarion ALM.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

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

## Reading a Parameter

```yaml theme={null}
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](/powersheet/reference/query-api/expand-clause), filtered independently of the current document.     |
| `sources[].constraints.applyCurrentDocumentTo` | The entity type scoped to the current document (see [Document Filtering](/powersheet/reference/query-api/document-filtering)).     |
| `sources[].entityFactory`                      | Default values applied to newly created items.                                                                                     |
| `title`, `subtitle`, `icon`                    | The [sheet header](/powersheet/reference/sheet-config/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](/powersheet/reference/server-rendering/context-variables) 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:

```velocity theme={null}
$!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](/powersheet/reference/server-rendering/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:

```yaml theme={null}
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.

<Note title="A broken expression fails loudly">
  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.
</Note>

## 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](/powersheet/reference/query-api/baseline-and-revision-queries)). |
| `_title`    | `documentTitle` | Document title carried from the Polarion link.                                                                                    |
| `_view`     | --              | Saved view to apply on load, by view id.                                                                                          |
| `_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 `_`.

<Note title="Legacy names still open existing links">
  Before 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.
</Note>

<Note title="Context fields are unchanged -- no config edits needed">
  The 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.
</Note>

### The `_view` Parameter

`?_view=<id>` opens the sheet in a saved [view](/powersheet/reference/sheet-config/views) 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.

## See Also

* [URL Parameters](/powersheet/concepts/url-parameters) -- the parameter mechanism concept
* [Server-Side Filtering](/powersheet/concepts/server-side-filtering) -- filtering a sheet on the server, at the root and on expand levels
* [Open a Scoped Sheet with URL Parameters](/powersheet/guides/sheet-configuration/parametrize-sheet-url)
* [Dynamic Expressions Reference](/powersheet/reference/sheet-config/dynamic-expressions)
* [Context Expressions](/powersheet/reference/data-model/context-expressions) -- the full context object
* [Sheet Header](/powersheet/reference/sheet-config/sheet-header) -- title, subtitle, and icon driven by the same context
* [Expand Clause](/powersheet/reference/query-api/expand-clause) -- expand subquery `where`

<LastReviewed date="2026-07-28" />