Managing User Permissions and Dashboard Access in Embedded Application

In Bold BI, the management of user permissions and dashboard access is primarily handled at the application layer. This approach allows for a streamlined process in determining who can view and create reports, as well as edit existing ones. Below is an overview of how listing, creation, and editing functionalities are structured within the application.

User Permissions Overview

Listing Dashboards

The system retrieves data from specific categories to present reports based on user access. The application layer is responsible for managing these categories, ensuring that users can only access dashboards relevant to their permissions.

Creation of Reports

The application layer contains detailed information about users authorized to create reports. Permissions can be set at the application level to control who can create new reports. This ensures that only designated users have the ability to initiate report creation.

Editing Reports

Roles for administrative users are defined within the application layer, determining who can modify original reports and who is restricted from making edits. This functionality allows for tailored visibility of the edit option based on user roles.

Example of Dashboard Management

In this sample embed application , dashboards are categorized for better organization. For instance, the System Dashboard is listed under the Master and Company name category, while individual user dashboards are retrieved from a user-specific category labeled “My Dashboard.” . Please find the sample code used for different API operations used in the embedded application like Authentication, Fetching Dashboards, Copy Dashboard, Save Dashboard, New dashboard and Delete Dashboard

Authentication

To access the API, a token must be fetched. The following function demonstrates how to retrieve this token:

export async function getToken(): Promise<string> {
  const config = await loadConfig();
  return fetchToken({
    username: config.useremail,
    embedSecret: config.embedsecret,
    rootUrl: config.rooturl,
    siteidentifier: config.siteidentifier,
    cookiePrefix: 'bbi_embed_adhoc'
  });
}

Parameters:

• username: The email associated with the account.
• embedSecret: A secret key used for embedding
• rootUrl: The base URL for the API…
• siteidentifier: The identifier for the specific site
• cookiePrefix: A prefix for cookies used in the session.

Fetching the Token

The token is fetched by making a POST request to the API endpoint:

const res = await fetch(`${rootUrl}/api/${siteidentifier}/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload)
});

Fetching Dashboards

Once the token is obtained, dashboards can be retrieved from a specified category. The following code snippet illustrates how to fetch dashboards:

const token = await getToken();
const response = await fetch(
  `${boldBIConfig.rooturl}/api/${boldBIConfig.siteidentifier}/v5.0/dashboards?serverPath=/${boldBIConfig.defaultCategory}`,
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
  }
);

Parameters:

• rootUrl: The base URL for the API…
• siteidentifier: The identifier for the specific site
• serverPath: The path to the category of dashboards to be retrieved.

Copy Dashboard

To copy an existing dashboard to a new category, you can use the following API call:

const response = await fetch(
  `${boldBIConfig.rooturl}/api/${boldBIConfig.siteidentifier}/v5.0/dashboards/${dashboard.id}/copy`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      Name: name,
      Description: `${name} (copied)`,
      CategoryId: myCategoryId,
      IsPublic: true,
      IsCopyDatasource: true,
    }),
  }
);

Parameters:

• Name: The name of the new dashboard.
• Description: A description for the new dashboard, typically indicating it is a copy.
• CategoryId: The ID of the category where the new dashboard will be placed.
• IsPublic: A boolean indicating if the dashboard should be public.
• IsCopyDatasource: A boolean indicating if the data source should be copied.

Save Dashboard

To publish changes made to a dashboard, the following method can be used:

const info = {
  category: editingDashboard.categoryName,
  categoryId: editingDashboard.categoryid,
  name: editingDashboard.name,
  description: '',
  id: editingDashboard.id,
  isPublic: true
};
dbrdInstance.designer.publish(info, 'dashboard');

Parameters:

• category: The name of the category for the dashboard.
• categoryId: The ID of the category.
• name: The name of the dashboard.
• description: A description for the dashboard (optional).
• id: The ID of the dashboard.
• isPublic: A boolean indicating if the dashboard should be public.

Delete Dashboard

To remove a dashboard by its ID, use the following API call:

const response = await fetch(
  `${boldBIConfig.rooturl}/api/${boldBIConfig.siteidentifier}/v5.0/items/${id}`,
  {
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
  }
);

Parameters:

• id: The ID of the dashboard to be deleted.

Create New Dashboard

To initiate a new draft dashboard, the following API call can be used:

const response = await fetch(
  `${boldBIConfig.rooturl}/api/${boldBIConfig.siteidentifier}/v5.0/dashboards/draft`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
  }
);

Category Management

When a user attempts to create a dashboard, the server must validate whether a category exists for managing reports. If the category is not available, the application will prompt the user to provide a dashboard name, which will be used to create the category along with the dashboard.

In the application, categories are created using the user’s email address. For example:

• john@alphacorp.com becomes johnalphacorpcom
• davis@alphacorp.com becomes davisalphacorpcom

Additionally, a new group must be created with the same name as the category, and appropriate permissions should be assigned to that category.

Group Creation and Permissions

A new group must be created with the same name as the category, and appropriate permissions should be assigned to this group to manage access effectively.

Key Processes

1. Retrieve the list of dashboards through the API.
2. Integrate client-side mapping to the authorization server.
3. Send dashboard IDs to the component.
4. The component requests the authorization server endpoint to generate a token.
5. Conduct server-side authorization using anonymous user details.
6. Load the dashboard using the generated token.

By following these guidelines, users can effectively manage their dashboards and ensure that permissions are appropriately assigned, enhancing the overall functionality and security of the Bold BI application.

Key Concepts

Default/Public Dashboard

• Purpose: Provides default dashboards for all clients.
• Management: Maintained under the Master category in Bold BI.
• Workflow: Dashboards created by the provider are moved to the Master category once completed.
• Example:
  • Master Group Permission: Read all dashboards from the Master category.

Company Dashboards

• Purpose: Specific dashboards for individual companies.
• Management: Each company has its own category, e.g., Tenant_TenantID (Tenant_34) or AlphaCorp.
• Workflow: Categories and groups are created automatically when a new tenant registers. The group is granted permission to access the category resources.
• Dashboard Creation: Dashboards can be created by providers or individual admins within the company. Once created, these dashboards are moved to the company-specific category.
• Example:
  • Company Group Permission: Tenant_34 or AlphaCorp
    • Read all dashboards from the company-specific category.
    • Read all dashboards from the Master category (Optional).
      
      

Individual User Dashboards

• Purpose: Dashboards created by individual users.
• Management: Each user has a separate category, e.g., john@alphacorp.com -> johnalphacorpcom.
• Workflow: Categories and groups are created when the user starts creating dashboards. The group is granted permission to access the category resources.
• Example:
  • User Group Permission: johnalphacorpcom or AlphaCorp_8 or Tenant_34_user_8
    • Create, read, write, delete dashboards in the user-specific category.
      
      

Sharing Dashboards

• Purpose: Allows users to share dashboards with others.
• Management: Permissions are added to the group of the user who wants to view the shared dashboard.
• Workflow: If the user hasn’t created reports yet, the usual process for creating the group is followed.
• Example:
  • Sharing Example: A user shares a dashboard with another user.
    • Sharing User Group: davisalphacorpcom or AlphaCorp_9 or Tenant_34_user_9
    • Add read permission for the specific dashboard to the receiving user’s group: johnalphacorpcom or AlphaCorp_8 or Tenant_34_user_8.
      
      

Suggested Naming Conventions for Categories and Groups

To streamline the process and avoid storing group names and category names in the application, you can dynamically generate these names at runtime while interacting with the Bold BI server. Here are the suggested naming conventions:

Individual User Dashboards

• Email-based Naming:
  • Category: johnalphacorpcom
  • Group: johnalphacorpcom
• User ID-based Naming:
  • Category: AlphaCorp_8
  • Group: AlphaCorp_8
• Tenant and User ID-based Naming:
  • Category: Tenant_34_user_8
  • Group: Tenant_34_user_8

Company Dashboards

• Tenant-based Naming:
  • Category: Tenant_34
  • Group: Tenant_34
• Company Name-based Naming:
  • Category: AlphaCorp
  • Group: AlphaCorp

Usage in Application Development

Automated Processes

• Ensure these naming conventions are applied automatically during tenant registration and dashboard creation.

Permission Management

• Assign appropriate permissions to groups based on these naming conventions.

Benefits

• Efficiency: No need to store group names and category names in the application.
• Consistency: Ensures a standardized approach to naming.
• Flexibility: Names can be generated dynamically at runtime, simplifying interactions with the Bold BI server.

Detailed Processes

Company Dashboards Process

1. Once a new tenant is created, generate the name for the company group using the naming convention suggestions.
2. Create the category with the group name in Bold BI Server using the authentication token and create category API.
3. Create the group in Bold BI Server using create group API.
4. Add read permission to the group to access the dashboards from the created category.
   
   

Individual Dashboard Process

1. Start the report creation.
2. Generate the name for the individual user group using the naming convention suggestions.
3. Validate the category name availability with the group name. If the category is not available, create the category. If the category is already available, skip the entire process.
4. After creating the category, validate the group name availability. If the group name is not available, create the group name; otherwise, move to the end.
5. Add permission to the group to create, read, and delete dashboards within the created category.
   
   

Sharing Dashboard Process

1. Share the dashboard with a list of users.
2. Loop through all the users and process them one by one.
3. Generate the group name for the individual user group (for whom sharing) using the naming convention suggestions.
4. Validate the group name availability. If the group name is not available, create the group name.
5. Add permission to the group to read the specific report (for whom sharing).
   
   

Additional References

• Bold BI Documentation
• Server API Reference
• Manage Groups