---
url: 'https://docs.codatum.com/features/notebook/sharing/signed-embed/use-case.md'
description: Design examples for isolating data per tenant with a signed embed
---

# Use cases

Design examples for a signed embed, assuming a retail-support SaaS. For a summary of parameter roles, see [Multi-tenant](./multi-tenant); for publishing and settings, see [Signed embed](./overview); for integration steps, see [Integration steps](./integration).

For code examples, also see the README of the [Codatum Embed SDK](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme).

## Scenario {#scenario}

Assume a SaaS that supports retail store operations, embedding a dashboard of sales and KPIs per store. When a store manager or an area manager logs in, only the information related to their own store is shown.

## Notebook parameters {#params}

Assume the source notebook has the following parameters. The parameter names are examples; they aren't required names.

* `tenant_id`
  * The tenant ID the logged-in user belongs to.
  * [Text input](../../parameter/types#text-input).
* `store_id`
  * The ID of the store to display.
  * [Text select](../../parameter/types#text-select). The choices are the store IDs within the tenant specified by `tenant_id`.
* `date_range`
  * The aggregation period.
  * [Date range](../../parameter/types#date-range). The default value is a [relative date](../../parameter/relative-date), 7 days ending yesterday.
* `product_category`
  * The product category to aggregate.
  * [Text multi select](../../parameter/types#text-multi-select). When nothing is selected, the SQL conditions show all categories.

## Configuration example A: using the signed embed's own form {#example-a}

### Notebook design assumptions

* Fix `tenant_id` to restrict the data that can be accessed.
  * The SQL that extracts data must always include `tenant_id` as a filter condition.
  * Even when extracting store data, include `tenant_id` as a condition in addition to `store_id`, so that another tenant's store data can't be extracted.
* Design `date_range` and `product_category` so any value can be specified.

### Parameter configuration

* `tenant_id`: **server-side parameter fixed value**
* `store_id`: server-side parameter initial value
* `date_range`: client-side parameter
* `product_category`: client-side parameter

### Flow up to display

1. Issue a token server-side.
   * Specify the user's `tenant_id` as the fixed value.
   * Among the stores tied to `tenant_id`, specify the `store_id` to display initially as the initial value.
2. Render initially on the frontend.
   * In the return value of the [Embed SDK](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)'s `tokenProvider`, include the following client-side parameters in `params`.
     * For `date_range`, configure it to use the default value as the initial value, so the relative date is recalculated (see [Relative dates](../../parameter/relative-date#signed-embed)).
     * Specify an empty array as the initial value for `product_category`.
3. The user operates the dashboard.
   * The user can change `store_id`, `date_range`, and `product_category` from the input form.

## Configuration example B: managing parameters on the embedding app side {#example-b}

### Notebook design assumptions

Same as configuration example A.

### Parameter configuration

* `tenant_id`: **server-side parameter fixed value**
* `store_id`: client-side parameter
* `date_range`: client-side parameter
* `product_category`: client-side parameter

### Flow up to display

1. Issue a token server-side.
   * Specify the user's `tenant_id` as the fixed value.
2. Render initially on the frontend.
   * Enable `displayOptions.hideParamsForm` to hide the parameter form.
   * Parameters placed on a grid page remain visible. Viewers can edit them when they're referenced by SQL or charts on this page and don't have fixed values.
   * In the return value of `tokenProvider`, include the `store_id`, `date_range`, and `product_category` managed by the embedding app in `params`.
3. The user operates the dashboard.
   * To update the display based on a condition change on the embedding app side, use the following steps.
   * Reuse the token used for the initial render, and reload the embed (for example, via `reload`) with the full set of updated client-side parameters included in `params`.
     * Send the full set (`store_id`, `date_range`, `product_category`), not just the diff.
     * If the same user uses the same fixed value, the token can be reused within its expiration period.

## Configuration example C: updating a server-side parameter's fixed value {#example-c}

### Notebook design assumptions

* Fix both `tenant_id` and `store_id` to restrict the data that can be accessed.
  * Unlike configuration example A, this assumes `store_id` also needs to be fixed server-side.
* Design `date_range` and `product_category` so any value can be specified, as in configuration example A.

### Parameter configuration

* `tenant_id`: **server-side parameter fixed value**
* `store_id`: **server-side parameter fixed value**
* `date_range`: client-side parameter
* `product_category`: client-side parameter

### Flow up to display

1. Issue a token server-side.
   * Specify the user's `tenant_id` and the `store_id` to display initially as fixed values.
2. Render initially on the frontend.
   * In the return value of `tokenProvider`, include the following client-side parameters in `params`.
     * For `date_range`, configure it to use the default value as the initial value, so the relative date is recalculated (see [Relative dates](../../parameter/relative-date#signed-embed)).
     * Specify an empty array as the initial value for `product_category`.
3. The user operates the dashboard.
   * `store_id` is a fixed value, so it can't be changed from the input form. Provide a store-switching UI on the embedding app side.
   * To change stores and re-render, reissue the token with the new `store_id`, then send the new token and the full set of client-side parameters.
     * Changing a fixed value requires reissuing the token.
     * Send the full set of client-side parameters (`date_range`, `product_category`), not just the diff.
     * If you want to preserve values the user changed before the redraw, record them using the Embed SDK's `paramChanged` event (`onParamChanged` in React / Vue) and include them when resending.
   * `date_range` and `product_category` can be changed from the input form.