# Use Cases

## Case: Utilizing Embedded Dashboards in Retail Support SaaS

### Scenario

In a SaaS platform that supports retail store operations, we assume a need to embed dashboards within the SaaS to understand sales performance and KPIs for each store. This functionality allows store managers and area managers to view only information related to their stores when they log in.

### Notebook Parameters

The notebook that serves as the source for signed embed is assumed to have the following parameters configured:

* `tenant_id`:
  * Tenant ID to which the logged-in user belongs
  * "Text input" type parameter
* `store_id`:
  * Store ID for which data is to be displayed
  * "Text select" type parameter, where options allow selection of store IDs within the tenant specified by `tenant_id`
* `date_range`:
  * Data aggregation period
  * "Date range" type parameter with a default value of relative dates spanning 7 days from the previous day
* `product_category`:
  * Product category for narrowing down data aggregation targets
  * "Text multi select" type parameter, with SQL conditions specified to display all product categories when none are selected

### Configuration Example A: Using Signed Embed Forms

#### Prerequisite Notebook Design

* Security of data accessible to users is ensured by fixing `tenant_id`
  * SQL for data extraction always specifies `tenant_id` as a filter condition
  * For example, when extracting store data, both `store_id` and `tenant_id` are specified as filter conditions, preventing extraction of data from stores belonging to different tenants
* `date_range` and `product_category` are designed to allow arbitrary values

#### Parameter Configuration

* `tenant_id`: **Fixed value for a server-side parameter**
* `store_id`: Initial value for a server-side parameter
* `date_range`: Client-side parameter
* `product_category`: Client-side parameter

#### Flow to Display

1. Token issuance on server-side
   * Specify the user's `tenant_id` as a fixed value for a server-side parameter
   * Specify the `store_id` to display in the initial state as an initial value for a server-side parameter, selected from among the `store_id` values associated with `tenant_id`
2. Initial rendering process on front-end
   * When sending the `SET_TOKEN` message, send the following client-side parameters together:
     * `date_range` is specified to reset to default value for relative date recalculation
     * `product_category` is specified with an empty array as the initial value
3. User dashboard operations
   * Users can change `store_id`, `date_range`, and `product_category` from the dashboard form

### Configuration Example B: Managing Parameters on SaaS Front-end

#### Prerequisite Notebook Design

The same design as "Configuration Example A"

#### Parameter Configuration

* `tenant_id`: **Fixed value for a server-side parameter**
* `store_id`: Client-side parameter
* `date_range`: Client-side parameter
* `product_category`: Client-side parameter

#### Flow to Display

1. Token issuance on server-side
   * Specify the user's `tenant_id` as a fixed value for a server-side parameter
2. Initial rendering process on front-end
   * When sending the `SET_TOKEN` message, send the following client-side options together:
     * Since parameters are managed on the SaaS side, specify the option to hide the parameter form (`displayOptions.hideParamsForm = true`)
     * Specify values managed on the SaaS side for `store_id`, `date_range`, and `product_category`
3. User dashboard operations
   * When changing dashboard display conditions due to changes in conditions managed on the SaaS side, follow these steps:
   * **Reuse** the token used in the initial rendering process and resend the `SET_TOKEN` message with updated client-side options
     * By resending the `SET_TOKEN` message, the dashboard is redrawn based on the newly sent client-side options
     * The client-side parameters sent at this time must include all items (`store_id`, `date_range`, `product_category`), not just the differences
     * When the same user uses the same fixed value for a server-side parameter, token reuse is possible (note the expiration time)

### Configuration Example C: Updating Server-side Fixed Values

#### Prerequisite Notebook Design

* Security of data accessible to users is ensured by fixing both `tenant_id` and `store_id`
  * Unlike "Configuration Example A", this assumes a case where `store_id` needs to be fixed on the server-side
* `date_range` and `product_category` are designed to allow arbitrary values, same as "Configuration Example A"

#### Parameter Configuration

* `tenant_id`: **Fixed value for a server-side parameter**
* `store_id`: **Fixed value for a server-side parameter**
* `date_range`: Client-side parameter
* `product_category`: Client-side parameter

#### Flow to Display

1. Token issuance on server-side
   * Specify the user's `tenant_id` and the `store_id` to display in the initial state as fixed values for server-side parameters
2. Initial rendering process on front-end
   * When sending the `SET_TOKEN` message, send the following client-side parameters together:
     * `date_range` is specified to reset to default value for relative date recalculation
     * `product_category` is specified with an empty array as the initial value
3. User dashboard operations
   * Since `store_id` is a fixed value for a server-side parameter, it cannot be changed from the dashboard form, and the SaaS side needs to manage `store_id` and provide a form for changing the target store
   * When redrawing the dashboard by changing `store_id` based on user operations, follow these steps:
   * **Issue a new token** to the server-side specifying the new `store_id`, and send the `SET_TOKEN` message with the new token and client-side parameters
     * To change fixed values for server-side parameters, token reissuance is required
     * Client-side parameters must include all items (`date_range`, `product_category`), not just the differences
       * To preserve `date_range` or `product_category` changed by user operations, record the `PARAM_CHANGED` messages sent from the iframe and send them during redrawing
   * For `date_range` and `product_category`, users can change the display content from the dashboard form