Self-service Analytics

Overview

Self-service analytics empowers your customers to explore data and generate insights independently, reducing the burden on your analytics team while increasing customer satisfaction.

Let's explore how to implement this through the lens of Acme Corp, a shipping and logistics provider. Acme Corp wants to give their enterprise customers like Corp A and Corp B the ability to analyze their shipping data, track performance metrics, and build custom dashboards.

Before diving into implementation, let's examine the key scenarios Acme Corp needs to support:

• Prebuilt Insights
  Provide a collection of pre-built dashboards containing frequently needed insights. Users can interact with these dashboards and use AI assistant to rapidly discover insights.

• Custom Analytics
  Enable data-savvy users at Corp A and Corp B to create and customize insights by modifying existing dashboards or building new ones from scratch. Their users can leverage approved datasets from Acme Corp to build insights tailored to their needs and share them with their peers.

To support both scenarios, Semaphor provides two types of users:

1. Org Users: Internal users at Acme Corp who build and manage projects.
2. Tenant Users: End customers of Acme Corp (e.g., users from Corp A, Corp B).

In this guide, we'll walk through the process of setting up the project, adding datasets, creating dashboards, and finally sharing them with the Tenant Users.

Step 1: Project Setup

To get started, you (Org User) need to create a new project in Semaphor. A project is a container for your data connections, semantic models, and dashboards.

💡 After creating the project, make sure to note down your projectId and projectSecret - you'll need these to authenticate API requests later.

Add a Data Connection

1. Go to the Connections tab.
2. Click Add Connection to connect to your source data (e.g., a database or data warehouse).
3. Test the connection to ensure it is working.

Once connected, Org users can begin building dashboards. However, to enable a secure and intuitive self-service experience for your end users, we recommend setting up Semantic Domains.

Step 2: Define Semantic Domains

Semantic domains allow you to group tables into logical categories, making it easier for end users to find and understand the data they need. When you're enabling self-service analytics in your product, it's important to carefully control data access and organization. Consider the following aspects:

1. Data Access Control

   • Which tables and fields should end users be able to access?
   • Should users see all available tables or just a curated subset?

2. Dataset Organization

   • How should data be logically grouped for users (e.g., by business domain)?
   • What semantic groupings make sense (sales, purchasing, reconciliation, etc.)?

Rather than exposing raw database tables, you'll want to create curated datasets with proper documentation, field descriptions, and business-friendly labels. This ensures users work with vetted, well-documented data sources rather than dealing with complex raw tables directly.

Create a Semantic Domain

1. Go to the Semantic Domains tab in your project.
2. Click Create Domain and give it a name (e.g., sales_analytics).

💡 After creating the domain, note down the domainId. You’ll need this when generating access tokens for tenant users.

3. Open the domain and add datasets (tables) relevant to that domain.
4. Semaphor will automatically generate friendly field labels and descriptions.

You can also remove internal or irrelevant fields, edit labels and add helpful descriptions to improve usability for end customers.

Step 3: Create a Dashboard

Now that you've defined your semantic domains, you can create dashboards for your end users.

Create a Dashboard

1. Go to the Dashboards tab in your project.
2. Provide a name and description — this creates a blank dashboard with one empty card.
3. Click Edit, then open the card using the Eye icon in the top-right corner which will open the Explore view.

4. In the Explore view, click Add and select from your semantic domains.

5. Once you've added the dataset, you can drag and drop fields to create charts and tables. Make sure to frequently save your changes.

Share Dashboard with tenants

Once your dashboard is ready:

1. Click the Share button in the toolbar.

2. Choose how you'd like to share the dashboard — you can:

   • Share it with all tenant users.
   • Limit access to specific tenants or users.

💡 After creating the dashboard, note down the dashboardId. You’ll need this when generating access tokens for tenant users.

This setup ensures your end customers can access relevant dashboards — or copy and customize them as needed.

Step 4: Tenant Setup

Now in our example, we have two tenants - Corp A and Corp B. This is where you would typically have your end users.

Note: Tenants and their users can also be created programmatically using the API. In this guide, we’ll use the Admin Panel for demonstration.

Create a Tenant

1. From the Project page, click the three dots menu (⋮).
2. Select Admin Panel.
3. In the Admin Panel, go to the Tenants tab.
4. Click Add Tenant and enter your customer’s information.

Create a Tenant User

1. Go to the Users tab.
2. Click Add User and enter your user’s information.
3. Once created, note down the Tenant User ID — you’ll need this later during token generation.

Step 5: Generate Token

Now that everything is in place, you can generate access tokens for each tenant user to enable secure, self-service analytics within your app.

Required Parameters for Token Generation

1. Project Credentials: projectId and projectSecret. These authenticate access to the project.
2. Tenant User ID: endUserId. The unique identifier for the user accessing the dashboard in your app.
3. Semantic Domains: allowedSemanticDomains (optional). A list of semantic domains the user is permitted to access.
4. Initial Dashboard: dashboardId (optional). The dashboard that will be loaded by default when the user logs in.

You can also configure additional security parameters such as row-level, connection-level or schema-level security. See the token options and multi-tenancy for more details.

You can copy and paste the following code to generate a token and render a self-service analytics experince in your app.

Code Example (React)

Make sure you get the latest version of the semaphor package.

npm install semaphor@latest

import { useEffect, useState } from 'react';
import { AuthToken, Surfboard } from 'semaphor';
import 'semaphor/style.css'; // IMPORTANT! Include the CSS file. This is the default style, you can customize it.
 
const PROJECT_ID = 'your-project-id';
const PROJECT_SECRET = 'your-project-secret';
const END_USER_ID = 'tenant-user-id';
const ALLOWED_SEMANTIC_DOMAINS = ['your-semantic-domain-id'];
const INITIAL_DASHBOARD = 'your-dashboard-id';
 
const TOKEN_URL = 'https://semaphor.cloud/api/v1/token';
 
function App() {
  const [authToken, setAuthToken] = useState<AuthToken>();
 
  useEffect(() => {
    async function fetchToken() {
      try {
        const response = await fetch(TOKEN_URL, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            projectId: PROJECT_ID,
            projectSecret: PROJECT_SECRET,
            endUserId: END_USER_ID,
            allowedSemanticDomains: ALLOWED_SEMANTIC_DOMAINS,
            initialDashboardId: INITIAL_DASHBOARD,
          }),
        });
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }
 
        const token = await response.json();
        if (token?.accessToken) {
          setAuthToken(token);
        }
      } catch (error) {
        console.error('There was an error!', error);
      }
    }
    fetchToken();
  }, []);
 
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <Surfboard showAssistant showControls authToken={authToken} />
    </div>
  );
}
 
export default App;