# How to Specify from URLs

When creating links from external sites to this service, you can override existing parameter values by specifying parameters in the URL.

## Target Features

The following features allow you to specify parameters from URLs.\
In these features, the URL is updated each time parameters are changed, and **you can share parameter values with other users by sharing the URL**.

* Notebook [versions](https://docs.codatum.com/data-exploration/notebook/version)
* [Reports](https://docs.codatum.com/sharing/report)
  * Must select `Interactive Report` as the report type
  * If the `Enable automatically run on load` setting is enabled, it will automatically execute after these parameters are merged
  * Even if the `with default parameter values` setting is enabled, **parameters specified in the URL take priority**
    * Parameter updates specified in the URL are applied after the entire parameters are reset to default values

## How to Specify Parameters

Parameters are synchronized with the `cdm.params` query parameter in the URL.\
The `cdm.params` query parameter has the following format:

```typescript
// Parameters are stored for each page ID to maintain parameters during page transitions
type Params = {[pageId: string]: {[paramId: string]: string}};

// Each parameter value is specified as a string using JSON.stringify (details below)
// pageId and paramId are actually strings 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 Specification

If it's difficult to directly generate the `cdm.params` query parameter when creating links from external sites, you can also specify parameters by providing keys and values in the format `cdm.params.${paramId}`. When both `cdm.params` and `cdm.params.${paramId}` are specified, the `cdm.params.${paramId}` value takes priority, and a new `cdm.params` query parameter is automatically specified with both values merged.

```typescript
const paramId = "param1";
// In shortcut format, parameter values don't need JSON.stringify stringification (details below)
const value = "string_value";  

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

// In shortcut format, you can set a parameter to empty state by specifying an empty string
const queryEmpty = `?cdm.params.${paramId}=`;
```

## How to Specify Parameter Values

Parameter values are specified as follows according to the parameter type.\
When specifying in shortcut format, `JSON.stringify` stringification is not required, but `encodeURIComponent` encoding is necessary when specifying in URLs.

| Type                                          | Specification Method                              | Shortcut Format         |
| --------------------------------------------- | ------------------------------------------------- | ----------------------- |
| <p>Text input,<br>Text select</p>             | `JSON.stringify("string_value")`                  | `string_value`          |
| <p>Text multi input,<br>Text multi select</p> | `JSON.stringify(["item1", "item2"])`              | `item1,item2`           |
| <p>Number input,<br>Number select</p>         | `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`       |

### Specification Method Details

* Array-type parameters are specified by separating with `,` in shortcut format.
* For date input and date ranges, please specify in `YYYY-MM-DD` format
* If invalid parameter values are specified, the display will switch to an error screen