Appearance
Pass Parameters Through URL
About 738 wordsAbout 2 min
2026-09-04
Append named values to initialize Report or Global Parameters when an Open or Embed URL loads.
This guide covers Report and Global Parameters in the form ?<ParameterName>=<value>. To set the opening selection of a filter component directly, use default_<component title or id>=value1;value2 (see Filters); the SDK's initialFilterValues option does the same (see SDK Embedding).
URL values only narrow the data within what the signed-in user may see. Anyone can change a URL, so do not rely on URL values to restrict data; use row-level security.
Prerequisite: bind a filter default to a parameter
- Create a parameter with the required type and default value.
- Select a filter component in the report.
- Set its Default value option to Parameter, then select the parameter.
- Save the report.
At least one filter component on the page must use a Parameter default. In the current runtime, URL parameter mapping is initialized only when such a component exists. A parameter used only in a title, calculated measure, tab action, or advanced filter is not sufficient by itself.
Build the URL
Start with the Open or Embed URL generated by Datafor. Append the parameter's exact, case-sensitive name and its value:
<report-url>?<encoded-parameter-name>=<encoded-value>Use & for additional parameters. If the generated URL already contains a query string, add the first custom parameter with &, not another ?.
Use a standard URL builder or encodeURIComponent for parameter names and values. Prefer %20 for spaces; + is also read as a space. For example, both spaces in this parameter are encoded:
?Business%20Region=North%20AmericaAvoid values containing a literal percent sign (%). The current runtime performs an additional decode after parsing the query string, so a remaining percent sequence can cause initialization to fail.
Do not put a comparison operator in the URL key. Configure operators such as Greater than or equal to in the filter, then pass only the parameter value:
?Minimum%20Sales=1000Values by parameter type
| Input | URL value | Requirements |
|---|---|---|
| Text | North%20America | Use the exact displayed option value expected by the bound filter. Matching is case-sensitive. |
| Numeric | 1000 or -2.5 | Use a plain number without grouping separators. Configure the comparison operator in the report. |
| Date | 2026-08-31 | Use an unambiguous ISO calendar date (YYYY-MM-DD). |
| Date range | 2026-08-01,2026-08-31 | Separate start and end with one comma. A date filter uses the first two values. |
| Multiple values | East,West | For a multi-select filter, separate values with commas. Do not repeat the same URL key. |
A comma is the multi-value separator and cannot be preserved reliably as part of an individual value.
Complete URL examples
Open URL:
https://analytics.example.com/datafor/plugin/datafor/api/open/<pageId>?Business%20Region=North%20America&Minimum%20Sales=1000Embed URL with an existing system option:
https://analytics.example.com/datafor/plugin/datafor/api/integrate/<pageId>?__compact=true&Business%20Region=North%20America&Reporting%20Period=2026-08-01,2026-08-31<pageId> is the encoded report path generated by Datafor. Copy the generated Open or Embed URL; do not construct this identifier from the report title.
Missing and invalid values
| Input | Behavior |
|---|---|
| Parameter omitted | The parameter keeps its current supplied value or saved default. |
| Unknown or incorrectly cased name | The URL entry is ignored. |
| Same name repeated | The last occurrence becomes the current value. Use a comma-separated value for multi-select instead. |
| Empty value | Behavior depends on the consuming component and may not match the saved default. Do not send empty values. |
| Text value not found in the filter choices | It may not appear selected and can produce an unintended query. Validate against the report's displayed choices. |
| Invalid number or date | It can cause an invalid or failed query. Validate values before building the URL. |
Verify the result
- Save the report before testing the URL.
- Open the URL in a new browser tab so the report initializes from the query string.
- Confirm the filter selection and the resulting data—not only the visible URL.
- Test every allowed Text value and the boundary values for Numeric and Date inputs.