Introduction

The Apache Superset Userview Menu plugin is used to integrate Apache Superset dashboards into Joget DX Userview Menu. User can choose to embed their dashboard in either public or protected. Customisation options can be configured to show or hide before rendering the dashboard.

This plugin is created with the use of Superset Embedded SDK to embed the Superset dashboards into Joget DX.

This plugin source code and jar is available in JogetOSS repository at https://github.com/jogetoss/superset-menu.


Plugin Information

Plugins Available in the Bundle:

  1. Apache Superset Userview Menu

This plugin bundle is compatible with Joget DX 8.


Expected Outcome

Able to display an Apache Superset dashboard in Joget Userview Menu as shown in Figure 1.

Figure 1: A dashboard from Apache Superset displayed in userview menu


Get Started

Prerequisites / Assumptions

Before proceeding, make sure you have the following prerequisites:

  • Docker installed on your system
  • Basic familiarity with Docker Compose
  • Familiarity with Apache Superset

Please follow the link to setup Apache Superset using Docker: https://superset.apache.org/docs/installation/installing-superset-using-docker-compose/.

If you wish to use other means other than Docker to setup Apache Superset, please dive into their documentation under Installation and Configuration for more details.

How to install Apache Superset (Simplified Version)

1. Install a Docker Engine and Docker Compose

2. Clone Superset's GitHub repository

git clone https://github.com/apache/superset.git


3. Launch Superset Through Docker Compose

Enter the "superset" folder

cd superset


Run in development mode using the following code:

docker compose up


In docker, you can see that the superset container is running:

Figure 2: Docker Superset Container Running


You will need to wait a short while for all the containers to initialise and run around 5-10 minutes. After everything is done, you will be able to login and see the landing page.


4.  Log in to Superset

Wait for a short while, after that you can launch http://localhost:8088/ which is the default hosting location, and you can see the following login page.

Username "admin", password "admin" will be the default user credentials.

Figure 3: Hosting Apache Superset Locally


After logging in, this will be the main page of superset.

Figure 4: Landing page of Superset

First steps to get started in Apache Superset (Debugging)

1. If you are not able build the docker image

Related to Mac Apple Silicon, refer to Docker startup on Apple Silicon · Issue #25434 · apache/superset (github.com)

If you want to clear everything and start afresh, use the following code to delete the container and the image. Also check if there are unused volumes, manually delete them from docker if necessary.

docker-compose down && docker image prune -a
docker builder prune


2. If you are not able to login

Figure 5: Invalid Login

You might need to run following command to setup username and password manually:

docker-compose exec superset bash docker/docker-init.sh


3. Try to open the dashboard in incognito to see whether the dashboard is really "public", if access is denied

Figure 6: Access is Denied

Try adding the permissions as shown in Configure All Dashboard to be Public.


4. If you can open the dashboard in incognito, but cannot see the dashboard in Joget

Figure 7: Cannot load Public Superset Dashboard in Joget

Try following Disabling Talisman. [Source: node.js - Problem with Superset dashboard embedding in web app - Stack Overflow]


5. If public dashboard is working in Joget but protected dashboard is not working

Figure 8: Cannot load Protected Superset Dashboard in Joget


There might be a problem regarding the CSRF session token issue. Below is Joget tomcat log.

Figure 9: CSRF session token missing

Try following Disabling CSRF protection. 

Steps

Where to get plugin

Please refer to Source Code and Plugin Download.

How to install and use the plugin

1. In Joget, go to UI Builder. Under Marketplace section, drag the Apache Superset Userview Menu into the UI.

Figure 10: UI Builder


2. Fill in all the plugin configuration properties by referring to Apache Superset Userview Menu Properties.

For different dashboard types, refer to Public Dashboard and Protected Dashboard.


Public Dashboard 

1. For public dashboard, please follow Configure All Dashboard to be Public or Configure Specific Dashboard to be Public to configure the Public role. Make sure you can see your dashboard in incognito mode (without logging into superset). Copy the URL.

Figure 11: Apache Superset Public Dashboard 


2. Paste the URL in the Dashboard URL for Public Dashboard Type.

Figure 12: Apache Superset Public Dashboard Configurations


3. Save and run in UI. You will be able to see the Apache Superset Public Dashboard.

Figure 13: Apache Superset Public Dashboard shown


Protected Dashboard

1. For protected dashboards, you can use admin user for the Superset Username and Password if you want to save the hassle of creating a new user. If you wish to create a user with limited permissions, please refer to Configure Superset User Role.

Figure 14: Apache Superset Protected Dashboard Configurations


2. To use embed mode, make sure you refer to Configure Roles for Superset Dashboard Embedded Mode to have the necessary Guest Role permissions.


3. Obtain the dashboard embed ID after you have done the steps in Retrieve Superset Dashboard Embed ID

Figure 15: Apache Superset Protected Dashboard Embed ID


4. Paste the embed ID in Dashboard Embed ID. Save and run the UI.

Figure 16: Apache Superset Protected Dashboard Configurations Save


5. Save and run in UI. You will be able to see the Apache Superset Protected Dashboard.

Figure 17: Apache Superset Protected Dashboard shown

How to connect Joget data to Superset

1. In Superset, go to Database Connections if you have not linked your Joget database to Superset.

Figure 18: Apache Superset Database Connections


2. Go to +Database on the top right to add your Joget database connection.

Figure 19: Apache Superset add database


3. Connect your database. For this demo, I use MySQL as the database.

Figure 20: Apache Superset connect to a database


4. Fill in the details. Remember to use host.docker.internal as the host if you are running Superset in docker. [Source]

Figure 21: Apache Superset add database credentials


5. After the database is connected, click on Create Dataset.

Figure 22: Apache Superset finish connecting to database


6. In the create new dataset page, click on the database that we connected earlier.

Figure 23: Apache Superset create dataset


7. If you have a database table in mind, you can skip this step. If not, create a form and CRUD in Joget and enter some records for the datalist.

Figure 24: Joget add basic records for datalist


8. In the create new dataset page, select the table created. Now click on Create Dataset and Create Chart.

Figure 25: Apache Superset create dataset connect table


9. In the create new chart page, choose any desired charts. For this demo, we will use the Bar Chart.

Figure 26: Apache Superset create new chart


10. Amend the chart to your needs and click Save.

Figure 27: Apache Superset create new chart 2


11. Add a chart name and add the chart to a dashboard so that we can copy the link to Joget later.

Figure 28: Apache Superset add chart to dashboard


12. Click on the ... > Share > Copy permalink to clipboard to copy the link.

Figure 29: Apache Superset copy dashboard link


13. Paste the link in the Dashboard URL for Public. You can also copy the embed value to Protected dashboard as shown in Protected Dashboard.


Figure 30: Joget paste dashboard link to Dashboard URL field


14. Now you can see the dashboard with Joget data shown in Superset.

Figure 31: Joget view Apache Superset table with Joget data


Apache Superset Userview Menu Properties

Configure Apache Superset Dashboard Menu

Figure 32: Plugin Configurations with no Dashboard Type


Figure 33: Plugin Configurations with Public Dashboard Type


Figure 34: Plugin Configurations with Protected Dashboard Type


Name

Description

Label

Menu label. Mandatory field.

Menu ID

Menu element unique ID. 

Dashboard Type

The type of dashboard that is shown to the user.

  • Public

  • Protected

Dashboard URL

This field is visible when "Dashboard Type" is public. Defines the entire URL of the dashboard. 

Example: http://localhost:8088/superset/dashboard/5/ (Assuming your Apache Superset is running on default http://localhost:8088/).

Apache Superset URL

This field is visible when "Dashboard Type" is protected. Defines the domain running Apache Superset.

Example: http://localhost:8088 (Assuming your Apache Superset is running on default http://localhost:8088/)

Superset Username

This field is visible when "Dashboard Type" is protected. Superset username used to create guest token. Refer to Configure Superset User Role. If you do not wish to create a new user, use the admin role.

Superset Password

This field is visible when "Dashboard Type" is protected. Superset user password used to create guest token.

Dashboard Embed ID

This field is visible when "Dashboard Type" is protected. Embed ID retrieved from Superset dashboard. Refer to Retrieve Superset Dashboard Embed ID. When using this embedded mode, please refer to Configure Roles for Superset Dashboard Embedded Mode to make sure you have the necessary roles to enable embedded mode.

Show Title

This option is visible when "Dashboard Type" is protected. Show or hide the title of the dashboard.

  • No

  • Yes

Show Tabs

This option is visible when "Dashboard Type" is protected. Show or hide the tabs of the dashboard.

  • No

  • Yes

Show Chart Controls

This option is visible when "Dashboard Type" is protected. Show or hide the chart controls of the dashboard.

  • No

  • Yes

Show Filters

This option is visible when "Dashboard Type" is protected. Show or hide the filter bar of the dashboard.

  • No

  • Yes



Apache Superset Dashboard Configurations

Please navigate to the domain where your superset is hosted, if you follow the documentation in Get Started -> Prerequisites / Assumptions, the default host location will be http://localhost:8088/.


Configure All Dashboard to be Public

  1. Settings > List Roles > Edit Record for "Public" role 

  2. Add Permissions:

    • can read on Chart
    • can read on Dataset
    • can read on Dashboard
    • can write on DashboardFilterStateRestApi
    • can read on DashboardFilterStateRestApi
    • can dashboard on Superset
    • can explore json on Superset
    • all datasource access on all_datasource_access
    • all database access on all_database_access

       And any other permissions if required.


Figure 35: Edit Role for "Public"


Configure Specific Dashboard to be Public

  1. Settings > List Roles > Edit Record for "Public" role 
  2. Add Permissions:
    • can read on chart
    • can read on dataset
    • can read on Dashboard
    • can write on DashboardFilterStateRestApi
    • can read on DashboardFilterStateRestApi
    • can dashboard on Superset
    • can explore json on Superset
    • datasource access on [examples]
    • database access on [examples]

       And any other permissions if required.

Figure 36: Permission "datasource access on [examples]"


Figure 37: Permission "database access on [examples]"



Configure Superset User Role

When "Dashboard Type" is protected, username and password is required. The user that is logged in needs to have the following roles: "can read on SecurityRestApi" and "can grant guest token on SecurityRestApi".

Create a new role (Figure 38):

  1. Settings > List Roles > Add a new record
  2. Add Permissions:
    1. can read on SecurityRestApi
    2. can grant guest token on SecurityRestApi

Create a new user (Figure 39):

  1. Settings > List Users > Add a new record 
  2. Link Role (Role created in Figure 38)


To read more on roles, refer to Apache Superset Documentation on roles: Apache Superset: Security > Provided Roles.




Figure 38: Add new role to generate guest token


Figure 39: Add new user to generate guest token



Configure Roles for Superset Dashboard Embedded Mode

When "Dashboard Type" is protected, we will need to use embedded mode to embed the dashboard. Under Embedded config options in superset/superset/config.py, the GUEST_ROLE_NAME role must have the following permissions configured:

  • can read on Chart
  • can read on Dataset
  • can read on Dashboard
  • can read on Database
  • can dashboard on Superset
  • can explore json on Superset
  • all database access on all_database_access

You can create a new role for this if you do not wish to use "Public" role. Refer to Figure 41 and Figure 42 for this.


Figure 40: Default setting for Guest Role at Config.py for Superset


Figure 41: New "EmbedRole" created with necessary permissions


Figure 42: EmbedRole as the new Guest Role at Config.py for Superset


Retrieve Superset Dashboard Embed ID

  1. At superset/superset/config.py for Superset, enable "EMBEDDED_SUPERSET" to True.

  2. Dashboards > any dashboard > Settings > Embed dashboard

  3. Copy the embed ID 

Figure 43: Enable Embedded_Superset to True at Config.py for Superset


Figure 44: Embed dashboard option enabled after setting in Config.py


Figure 45: Embed ID in Embed dashboard



Customising Options for Superset Dashboard before Render

  • Show Title

  • Show Tabs

  • Show Chart Controls

  • Show Filters


Figure 46: Original dashboard without customisation


Figure 47: Show Title


Figure 48: Show Chart Controls



Disabling CSRF protection

  1. If you face any CSRF errors, at superset/superset/config.py for Superset, modify "WTF_CSRF_ENABLED" to False. This will disable all CSRF protection.


Figure 49: Disabling CSRF protection


Disabling Talisman

  1. If you still cannot load the Superset Dashboard in Joget, at superset/superset/config.py for Superset, try modifying "TALISMAN_ENABLED" to False. 


Figure 50: Disabling Talisman

Source Code and Plugin Download

  1. Please visit https://github.com/jogetoss/superset-menu for the plugin's source code.
  2. You can find the latest release at https://github.com/jogetoss/superset-menu/releases.
  3. Upload the plugin to your Joget by navigating to Settings > Manage Plugins > Upload Plugin as admin.


Related Links


  • No labels