Use cases

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

For code examples, also see the README of the Codatum Embed SDK.

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

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.
• store_id
  • The ID of the store to display.
  • Text select. The choices are the store IDs within the tenant specified by tenant_id.
• date_range
  • The aggregation period.
  • Date range. The default value is a relative date, 7 days ending yesterday.
• product_category
  • The product category to aggregate.
  • Text multi select. When nothing is selected, the SQL conditions show all categories.

Configuration example A: using the signed embed's own form

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'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).
     • 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

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

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).
     • 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.