Specifying values from a URL

When creating an external link, you can override a parameter's value by adding it to the URL.

Applicable features

The following features let you specify parameters from a URL. With these features, the URL updates each time you change a parameter, so sharing the URL also shares the parameter values.

• Notebook versions
• Reports
  • Applies to interactive reports.
  • If Auto-run is enabled, the report runs automatically after merging in the URL-specified parameters.
  • Even if Use parameter default values is enabled, parameters specified in the URL take priority (they're reset to default first, and then the URL-specified values are applied).

How to specify

Parameters are synced with the cdm.params query parameter in the URL. The format is as follows.

// Keyed by page ID so values are retained across page navigation
type Params = { [pageId: string]: { [paramId: string]: string } };

// Each value is a JSON.stringify'd string
// pageId / paramId are actually IDs like 68783eb9c4b4b71483a1d617
const params: Params = {
  page1: {
    param1: JSON.stringify('value1'),
    param2: JSON.stringify(123),
  },
  page2: {
    param3: JSON.stringify(true),
    param4: JSON.stringify(['value1', 'value2']),
  },
};

const query = `?cdm.params=${encodeURIComponent(JSON.stringify(params))}`;

Shortcut format

If cdm.params is hard to construct directly, you can also use the cdm.params.${paramId} format. If both are present, cdm.params.${paramId} takes priority, and the merged result is reflected as a new cdm.params in the URL.

const paramId = 'param1';
// JSON.stringify isn't needed for the shortcut format (but encodeURIComponent is)
const value = 'string_value';

const query = `?cdm.params.${paramId}=${encodeURIComponent(value)}`;

// Specifying an empty string clears that parameter
const queryEmpty = `?cdm.params.${paramId}=`;

How to specify values

How to specify values differs by parameter type. JSON.stringify isn't needed for the shortcut format, but encodeURIComponent is still needed when placing the value in the URL.

Type	Specifying via cdm.params	Shortcut format
Text input / Text select	JSON.stringify("string_value")	string_value
Text multi input / Text multi select	JSON.stringify(["item1", "item2"])	item1,item2
Number input / Number select	JSON.stringify(123)	123
Date input	JSON.stringify("2025-01-01")	2025-01-01
Date range	JSON.stringify(["2025-01-01", "2025-01-02"])	2025-01-01,2025-01-02
Checkbox	JSON.stringify(true) or JSON.stringify(false)	true or false

• For array types, use , as the separator in the shortcut format.
• Date input and date range use YYYY-MM-DD format.
• An invalid value results in an error screen.