Embed portal - Getting started

BETA FEATURE

This is a Beta feature. The documentation and feature may change rapidly.

You can request Beta access and try it out.

Pre-requisite to use Embed Portal

• You need to enable git flow
• If you connect Holistics to your own repository, you need to make sure there is no protected branch restrictions

Overview

Creating an Embed Portal involves four main steps:

1. Define your portal in a .embed.aml file
2. Publish your portal to production
3. Generate embed credentials
4. Integrate the portal into your application

Step 1: Define your portal

• Create a new file in your Development tab with the naming convention: *.embed.aml
• Add dashboards and datasets that you want to embed into the Embed Portal

sales_portal.embed.aml

EmbedPortal sales_portal { // object with a unique name
  objects: [ // array containing the dashboard and dataset names.
    sales_overview,    // dashboard
    revenue_trends,    // dashboard
    sales_data,        // dataset
    // Since objects are unique across your Holistics instance, you can simply list the object names
    // Holistics automatically detects whether each object is a dashboard or dataset.

  ],
}

Step 2: Publish your portal

Once you've defined your Embed Portal in the .embed.aml file, you need to publish it to make it available for embedding.

For more information, please refer to publishing to production

Step 3: Generate embed credentials

1. Navigate to Tools → Embedded Analytics
2. Find your published portal in the list
3. Click Enable to activate embed credentials
4. Note your Key ID and Secret - you'll need these for integration

note

You only need to generate embed credentials once; the same credentials can be used for all your embedded portals.

Step 4: Integrate into your application

Backend Token Generation

To embed your portal into your application, you need to generate secure tokens on your backend.

In your application backend, generate embed tokens using this structure:

// Basic embed payload
const embed_payload = {
  object_name: 'customer_analytics',
  object_type: 'EmbedPortal',
  settings: {
    default_timezone: "UTC",
    enable_export_data: false,
  }
};

// Generate token (implementation depends on your backend)
const token = jwt.sign(embed_payload, embed_secret, { algorithm: 'HS256' });

Frontend Integration

Basic iframe Implementation

<!-- Generate this URL in your backend -->
<iframe  src="https://holistics.io/embed/{embed_key_id}?token={generated_token}"  width="100%"  height="600"  frameborder="0"></iframe>

Optional: Call API to generate Embedded URL (or embedded token)

// Frontend JavaScript example
async function loadPortal(userId, orgId) {
    // Call your backend to generate token
    const response = await fetch('/api/embed-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
      portal: 'customer_analytics',
    })
  });
  const { embedUrl } = await response.json();
  // Update iframe source
  document.getElementById('portal-iframe').src = embedUrl;
}

Embed portal payload's parameters

Parameter	Type	Description	Required
object_name	string	Name of your EmbedPortal	✅
object_type	string	Must be 'EmbedPortal'	✅
embed_user_id	string	Unique identifier for the user	For SSBI features
embed_org_id	string	Unique identifier for user's organization	For org workspaces
user_attributes	object	Values for row-level permissions	If using row-level permission
settings	object	Portal configuration settings	Optional
permissions.enable_personal_workspace	boolean	Enable personal workspace for user	Optional
permissions.org_workspace_role	string	User's role in organization workspace: 'no_access', 'viewer', 'editor'	Optional