Search results

Bold BI Dashboards embedding in React with ASP.NET Core using Embedded SDK

A GitHub link has been provided to get the sample application, which demonstrates the dashboard rendering in your Bold BI server and followed by steps to create a new embedding application in React with ASP.NET Core on your own.

NOTE: The best way to get started would be reading the Getting Started section of the documentation to start using first. The Getting Started guide gives you enough information that you need to know before working on the sample.

Prerequisites

NOTE: Node.js v14.16 to v18.16 are supported

How to run the sample

  1. Please get the React with ASP.NET Core sample from GitHub.

  2. Please ensure you have enabled embed authentication on the embed settings page. If it is not currently enabled, please refer to the following image or detailed instructions to enable it.

    Embed Settings

  3. To download the embedConfig.json file, please follow this link for reference. Additionally, you can refer to the following image for visual guidance.

    EmbedSettings image EmbedConfig Properties

  4. Copy the downloaded embedConfig.json file and paste it into the designated location within the application. Please ensure you have placed it in the application, as shown in the following image.

    EmbedConfig image

    ServerUrl Dashboard Server BI URL (ex: http://localhost:5000/bi, https://demo.boldbi.com/bi)
    SiteIdentifier For the Bold BI Enterprise edition, it should be like site/site1. For Bold BI Cloud, it should be an empty string.
    UserEmail UserEmail of the Admin in your Bold BI, which would be used to get the dashboard list.
    EmbedSecret Get your EmbedSecret key from the Embed tab by enabling the Enable embed authentication in the Administration page
    Environment Your Bold BI application environment. (If it is a cloud analytics server, use `BoldBI.Environment.Cloud`; if it is your server, use `BoldBI.Environment.Enterprise`)
    DashboardId Item ID of the dashboard to be embedded in your application.
    ExpirationTime Token expiration time. (In the EmbedConfig.json file, the default token expiration time is 10000 seconds)
  5. Open your React with ASP.NET Core project in Visual Studio Code and install all dependent packages, using the following command npm install.

  6. Execute the command dotnet restore to restore the necessary packages. Once the packages have been restored, use the dotnet build command to build the project.

  7. Run your React with ASP.NET Core sample with the command dotnet run in Visual Studio Code.

  8. The dashboard can be editable in design mode and create a new dashboard with the following changes in the renderDashboard() method.

    dashboardId Provide the dashboard ID of the dashboard you want to embed in view or edit mode. In order to create a new dashboard, please exclude this specific property.
    mode In which mode do you want to render the dashboard? It can either be 'BoldBI.Mode.View' or 'BoldBI.Mode.Design' mode.
    authorizationServer Url of the 'authorizationServerAPI' action in the application.
           renderDashboard(data) {
              this.dashboard = BoldBI.create({
              serverUrl: data.ServerUrl + "/" + data.SiteIdentifier,
              dashboardId: data.DashboardId,
              embedContainerId: "dashboard",
              embedType: data.EmbedType,
              environment: data.Environment,
              mode: BoldBI.Mode.View,
              width: "100%",
              height: window.innerHeight + 'px',
              expirationTime: 100000,
              authorizationServer: {
                  url: apiHost + authorizationUrl
              },
            });
    
            console.log(this.dashboard);
            this.dashboard.loadDashboard();
           }
    

NOTE: If you are facing issues with the validity of the ASP.NET Core developer certificate, you can try the following commands to resolve it: dotnet dev-certs https --clean, dotnet dev-certs https and dotnet dev-certs https --trust.

How this sample works

  1. Based on the configured embedConfig values in the DashboardListing.js file, the renderDashboard method will be invoked from the componentDidMount() function. render dashboard

  2. Before rendering, call the authorizationUrl, which redirects to the AuthorizationServer action in the BoldBIEmbedController, which generates the EmbedSignature using the embed secret provided in the embedConfig.json of the ASP.NET Core application.
    Get Embed Details

  3. These details will be sent to the Bold BI server and get validated there. Once the details are validated, the dashboard starts to render.

Steps to create new React with ASP.NET Core application to embed dashboard

  1. Create a folder in the desired location and open it in the Visual Studio Code.

  2. Open the terminal in the Visual Studio Code. Please refer to the following image. Terminal Image

  3. To create a new project, run this command in the terminal.

         dotnet new react
  4. Please ensure you have enabled embed authentication on the embed settings page. If it is not currently enabled, please refer to the following image or detailed instructions to enable it. Embed Settings

  5. To download the embedConfig.json file, please follow this link for reference. Additionally, you can refer to the following image for visual guidance. EmbedSettings image EmbedConfig Properties

  6. Copy the downloaded embedConfig.json file and paste it into the designated location within the application. Please ensure you have placed it in the application, as shown in the following image.

    EmbedConfig image

  7. Create a new folder called Models. Create a model class as DataClass.cs to define the following properties. These properties are used to get the dashboard details from the server.

    Execute the following commands in the terminal to add the necessary references to the project: dotnet add package Newtonsoft.Json and dotnet add package System.Runtime.Serialization.Primitives. Ensure the System.Runtime.Serialization and Newtonsoft.Json namespaces in the DataClass.cs model file.

         [DataContract]
         public class EmbedClass
         {
            [DataMember]
            public string embedQuerString { get; set; }
            [DataMember]
            public string dashboardServerApiUrl { get; set; }
         }
    
          public class EmbedDetails
          {
             public string Environment { get; set; }
    
             public string SiteIdentifier { get; set; }
    
             public string ServerUrl { get; set; }
    
             public string EmbedSecret { get; set; }
    
             public string UserEmail { get; set; }
    
             public string EmbedType { get; set; }
      
             public string DashboardId { get; set; }
          }
    
  8. Create another model class as GlobalAppSettings.cs to define the following properties. These properties maintain the embedConfig.json file object within the GlobalAppSettings.

        public class GlobalAppSettings
        {
            public static EmbedDetails EmbedDetails { get; set; }
        }
  9. Create a new controller as BoldBIEmbedController.cs. In the Controllers\BoldBIEmbedController.cs, To get particular dashboard details, define an API AuthorizationServer() which uses the method GetSignatureUrl() to generate the algorithm. In this API, the embedQuerString, userEmail and the value from the GetSignatureUrl() method are appended as query parameters in the URL to get details of a particular dashboard. With these details, the renderDashboard() method is called in the React application.

    Ensure the System.Security.Cryptography and Microsoft.AspNetCore.Mvc namespaces in the BoldBIEmbedController.cs.

    EmbedConfig image

         [ApiController]
         [Route("api/[controller]")]
         public class BoldBIEmbedController : Controller
         {
         [HttpGet]
         [Route("GetData")]
         public IActionResult GetData()
         {
            var jsonData = System.IO.File.ReadAllText("embedConfig.json");
            return Ok(jsonData);
         }
    
         [HttpPost]
         [Route("AuthorizationServer")]
         public string AuthorizationServer([FromBody] object embedQuerString)
         {
         var embedClass = Newtonsoft.Json.JsonConvert.DeserializeObject<EmbedClass>(embedQuerString.ToString());
    
         var embedQuery = embedClass.embedQuerString;
         // User your user-email as embed_user_email
         embedQuery += "&embed_user_email=" + GlobalAppSettings.EmbedDetails.UserEmail;
         //To set embed_server_timestamp to overcome the EmbedCodeValidation failing while different timezone using at client application.
         double timeStamp = (int)DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1)).TotalSeconds;
         embedQuery += "&embed_server_timestamp=" + timeStamp;
         var embedDetailsUrl = "/embed/authorize?" + embedQuery + "&embed_signature=" + GetSignatureUrl(embedQuery);
    
         using (var client = new HttpClient())
         {
             client.BaseAddress = new Uri(embedClass.dashboardServerApiUrl);
             client.DefaultRequestHeaders.Accept.Clear();
    
             var result = client.GetAsync(embedClass.dashboardServerApiUrl + embedDetailsUrl).Result;
             string resultContent = result.Content.ReadAsStringAsync().Result;       
             return resultContent;
         }
    
         }
    
         public string GetSignatureUrl(string queryString)
         {
         if (queryString != null)
         {
             var encoding = new System.Text.UTF8Encoding();
             var keyBytes = encoding.GetBytes(GlobalAppSettings.EmbedDetails.EmbedSecret);
             var messageBytes = encoding.GetBytes(queryString);
             using (var hmacsha1 = new HMACSHA256(keyBytes))
             {
                 var hashMessage = hmacsha1.ComputeHash(messageBytes);
                 return Convert.ToBase64String(hashMessage);
             }
         }
         return string.Empty;
         }
         }
  10. Open the Program.cs file. These lines of code configure a permissive CORS policy allowing requests from any origin, HTTP method, and headers. It’s crucial to consider security implications and adapt the policy to meet application requirements. Ensure the Newtonsoft.Json namespaces in the Program.cs

         app.UseCors(corsPolicyBuilder => corsPolicyBuilder
         .AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader());
         string basePath = AppDomain.CurrentDomain.BaseDirectory;
         string jsonString = System.IO.File.ReadAllText(Path.Combine(basePath, "embedConfig.json"));
         GlobalAppSettings.EmbedDetails = JsonConvert.DeserializeObject<EmbedDetails>(jsonString);
  11. Create a new file and name it package.json. It is essential to install the packages listed in the dependencies section below.

      {
        "name": "embedded-bi-react",
        "version": "0.1.0",
        "private": true,
        "dependencies": {
        "@boldbi/boldbi-embedded-sdk": "^6.4.6",
        "@testing-library/jest-dom": "^4.2.4",
        "@testing-library/react": "^9.4.0",
        "@testing-library/user-event": "^7.2.1",
        "axios": "^0.19.2",
        "jquery": "^3.5.1",
        "react": "^16.12.0",
        "react-dom": "^16.12.0",
        "react-scripts": "^3.4.0"
       }
      }
    
  12. Open the ClientApp\src folder. Within the ClientApp\src folder, create a new folder named DashboardListing. Inside the DashboardListing folder, create a file named DashboardListing.js. In the DashboardListing.js file, define the mandatory properties and implement the methods renderDashboard() to render the dashboard, render() to create the DOM elements and componentDidMount() to contact server as follows.

        import React from 'react';
        import '../index';
        import { BoldBI } from '@boldbi/boldbi-embedded-sdk';
    
       //ASP.NET Core application would be run on "https://localhost:7222;http://localhost:5137", which needs to be set as `apiHost`
       const apiHost = "https://localhost:7222";
    
       //Url of the AuthorizationServer action in ValuesController of the ASP.NET Core application
       const authorizationUrl = "/api/boldbiembed/authorizationserver";
       var BoldBiObj;
       class DashboardListing extends React.Component {
       constructor(props) {
         super(props);
         this.state = {
           toke: undefined,
           items: [],
           embedConfig: {},
         };
        this.BoldBiObj = new BoldBI();
        }
       } 

NOTE: Open the launchSettings.json file, applicationUrl is copied and pasted in apiHost.

  1. In DashboardListing.js file inside, include this method. In the renderDashboard(), use the following code to render the dashboard.

    DashboardListing Image

       renderDashboard(data) {
          this.dashboard = BoldBI.create({
          serverUrl: data.ServerUrl + "/" + data.SiteIdentifier,
          dashboardId: data.DashboardId,
          embedContainerId: "dashboard",
          embedType: data.EmbedType,
          environment: data.Environment,
          mode: BoldBI.Mode.View,
          width: "100%",
          height: window.innerHeight + 'px',
          expirationTime: 100000,
          authorizationServer: {
          url: apiHost + authorizationUrl
       },
       });
    
       console.log(this.dashboard);
       this.dashboard.loadDashboard();
       }
  2. In DashboardListing.js file inside, include this method. Create a DOM element with the Id dashboard, which will be utilized in therenderDashboard() method to render the dashboard in it.

       render() {
           return (
               <div id="viewer-section">
                   <div id="dashboard"></div>
               </div>
           );
       }
  3. In DashboardListing.js file inside, include this method. The componentDidMount() method contact the server to get the token and with this token, particular dashboard details is collected and passed to the renderDashboard() method to render it.

    DashboardListing Image

       async componentDidMount() {
       var dashboard = undefined;
       var querystring = require('querystring');
       var token = "";
    
       try {
         const response = await fetch(apiHost + '/api/boldbiembed/GetData');
         const data = await response.json();
         this.setState({ embedConfig: data });
         const embedConfig = this.state.embedConfig;
         this.renderDashboard(embedConfig);
       } catch (error) {
       console.log(error);
       this.setState({ toke: "error", items: "error" });
       }
       }
    
       export default DashboardListing;
    
  4. Open the App.js folder, replace the below code. The below code imports the necessary modules, defines the App component, renders the DashboardListing component, and exports it for use in other files.

          import React from 'react';
          import DashboardListing from './DashboardListing/DashboardListing';
    
          class App extends React.Component {
          render() {
             return (
               <div>
               <DashboardListing/>
               </div>
               );
              }
          }
    
          export default App;
      
  5. Open the Index.js file, replace the below code. These lines of code import the necessary modules React and ReactDOM, import the App component, and use ReactDOM.render to render the App component into the specified HTML element.

          import React from 'react';
          import ReactDOM from 'react-dom';
          import App from './App';
    
          ReactDOM.render(<App />, document.getElementById('root'));
  6. To install all dependent packages, use the following command npm install. Run the command dotnet restore to restore the necessary packages. Once the packages have been restored, use the dotnet build command to build the project.

  7. Run the React sample with Core sample, use the following command dotnet run in visual Studio Code.

NOTE: If you are facing issues with the validity of the ASP.NET Core developer certificate, you can try the following commands to resolve it: dotnet dev-certs https --clean, dotnet dev-certs https and dotnet dev-certs https --trust.