Embeddable Widgets

Embeddable widgets allow organizations to share live, read-only views of ProBeya boards, KPI charts, and dashboards with external stakeholders. Widgets are rendered in iframes and do not require authentication, making them ideal for TV displays, SharePoint pages, or partner portals.

Overview

Operations teams often need to share live data with stakeholders who don't have ProBeya accounts — plant managers watching TV displays, executives checking SharePoint dashboards, or partners monitoring shared KPIs. Embeddable widgets provide:

• Token-based access: Secure embed tokens with optional expiration
• Read-only rendering: No editing capabilities — data display only
• Live updates: Widgets refresh on a configurable interval
• Customizable appearance: Show/hide titles, timestamps, and apply themes
• Multiple embed types: Boards, KPI charts, dashboards, and portfolios

Widget Types

ProBeya supports four types of embeddable widgets, each with a dedicated renderer:

Type	Renderer	Best For
Board	Table/Kanban view	Displaying task lists, action items, SQCDP boards on TV screens
KPI Chart	Card grid with trend indicators	Showing KPI scorecards on executive dashboards
Dashboard	Custom layout with board data	Composite views combining multiple data sources
Portfolio	Project overview	High-level portfolio status for steering committees

Board Embeds

Board embeds render the full board structure including groups, columns, and items with their cell values. The data returned includes:

• Groups: Name, color, and sort order for visual grouping
• Columns: Name, type, configuration, and display width
• Items: Row data with a values map of columnId to cell value

Sensitive fields (user emails, createdById, assigneeId) are automatically stripped before the data reaches the embed renderer.

KPI Chart Embeds

KPI chart embeds return all KPI definitions on a board along with their last 30 values. Each KPI includes its threshold configuration and frequency, enabling the renderer to display traffic-light status indicators and sparkline trends.

Getting Started

1. Navigate to any board, KPI chart, or dashboard.
2. Click the Share menu and select Create Embed.
3. Configure embed options:
   • Label: A human-readable name for managing the token later
   • Theme: Visual theme for the embed appearance
   • Refresh interval: How often the widget auto-refreshes (in seconds)
   • Show title: Whether to display the resource name in the header
   • Show timestamp: Whether to display the last-updated time
   • Expiration date: Optional date after which the token stops working
4. Copy the generated embed snippet (<iframe> HTML).
5. Paste the snippet into any web page, SharePoint site, or TV dashboard.

How It Works

Embed Tokens

Each embed widget is backed by a unique token generated using cuid2 (cryptographically random). The token record stores:

• The organization and resource being embedded (entity type + entity ID)
• Configuration options (theme, refresh interval, title/timestamp visibility)
• Optional expiration date
• The user who created the token (for audit trail)

Rendering Pipeline

When a browser loads the embed URL (/api/embed/{token}):

1. The token is validated against the embed_tokens table
2. Expiration is checked — revoked or expired tokens return 403
3. Rate limiting is applied (60 requests/minute per token)
4. Resource data is fetched scoped to the token's organization
5. Sensitive fields are stripped from the response
6. A minimal, chrome-free version of the component is rendered

Security

• Cryptographic tokens: Generated with cuid2, making them unguessable
• Soft revocation: Revoking a token sets expiresAt to the current time, preserving the record for audit
• Rate limiting: 60 requests/minute per token (in-memory per-process limiter)
• Data sanitization: User emails, createdById, and assigneeId are stripped from public data
• Tenant isolation: All data fetched through embeds is scoped to the token's organizationId
• No write capability: The public endpoint only supports read operations

Iframe Snippet

The generated iframe HTML uses sensible defaults:

<iframe
  src="https://app.probeya.com/api/embed/{token}"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none;"
></iframe>

Administrators can customize the width and height after copying the snippet.

Managing Embed Tokens

Listing Tokens

Navigate to Settings > Embed Tokens to see all active tokens. Each entry shows the entity type, label, creation date, and expiration status. Use the entity ID filter to find tokens for a specific board or dashboard.

Revoking Access

To disable an embed immediately, click Revoke on the token. The token's expiresAt is set to the current time, and all subsequent requests using that token will receive a 403 Forbidden response. The record is preserved for audit trail purposes.

Including Revoked Tokens

By default, the token list hides revoked tokens. Toggle Show Revoked to include them for audit review.

API Reference

Procedure	Type	Description
embeds.create	Mutation	Create a new embed token for a resource
embeds.list	Query	List all embed tokens for the organization
embeds.revoke	Mutation	Soft-revoke an embed token
embeds.getPublicData	Query	Public endpoint to fetch embed data by token

Permissions

Action	Required Role
Create embed	manage_settings permission (Admin/Owner)
List embeds	manage_settings permission
Revoke embed	manage_settings permission
View embed	Anyone with a valid token URL

Related Features

• White-Label Branding — Branded embeds match your organization's theme
• KPI Boards — Embed live KPI charts on external displays
• Custom Domains — Serve embeds from your own domain