> ## 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

> How Nextedy POWERSHEET reads named values from a sheet's URL into context.parameters, so one configuration can be driven -- filters, new-row defaults, computed columns, even the sheet name -- from shareable, bookmarkable links 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>;
};

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.

<Note>
  This mirrors how the built-in `revision` parameter lets you [share a specific historical snapshot](/powersheet/guides/queries/query-baseline-revision) by URL.
</Note>

## 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](/powersheet/concepts/dynamic-expressions) `() => …` form:

```yaml theme={null}
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](/powersheet/concepts/source-configuration):

| Surface                                                                                  | Example use                                                                             |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Query `where` (root or an [expand subquery](/powersheet/concepts/server-side-filtering)) | 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](/powersheet/reference/sheet-config/sheet-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](/powersheet/concepts/dynamic-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](/powersheet/concepts/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](/powersheet/reference/server-rendering/context-variables). 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](/powersheet/reference/server-rendering/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`):

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

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

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

## 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](/powersheet/reference/query-api/document-filtering).                       |
| `_revision` | [Historical revision](/powersheet/reference/query-api/baseline-and-revision-queries) to load. |
| `_title`    | Document title carried from the Polarion link.                                                |
| `_view`     | Saved [view](/powersheet/reference/sheet-config/views) 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.

<Note title="Older links keep working">
  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.
</Note>

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.

<Note title="Context fields are unchanged">
  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.
</Note>

## Related

<Columns cols={2}>
  <Card title="Server-Side Filtering" icon="filter" href="/powersheet/concepts/server-side-filtering">
    The main thing URL parameters drive: filtering a sheet on the server so only the matching slice loads.
  </Card>

  <Card title="Open a Scoped Sheet with URL Parameters" icon="wrench" href="/powersheet/guides/sheet-configuration/parametrize-sheet-url">
    Step-by-step: reference a parameter, build the shareable URL, and gate required values.
  </Card>

  <Card title="URL Parameters Reference" icon="list" href="/powersheet/reference/sheet-config/url-parameters">
    The `parameters` block schema, reserved names, and the full configuration surface.
  </Card>

  <Card title="Dynamic Value Expressions" icon="code" href="/powersheet/concepts/dynamic-expressions">
    The `() => …` syntax and the context object that `context.parameters` is read from.
  </Card>
</Columns>

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