For in-depth, version specific documentation of Rapid Portal components, please use this reference of documents.

Here are links to documentation for Zuar's other products:

• Mitto
• Custom Portal
• Web Application Firewall

More content is available on Zuar's blog including specific embedded analytics content.

Join the Zuar community and discuss Rapid Portal!

In browser editor

To make prototyping and simple tweaks easier, the Rapid Portal has an in browser editor. In production, this functionality should be turned off and only enabled if and when changes need to be made (rarely).

In your browser, on your new Rapid Portal go to /edit.

This in browser editor allows you to change any of the Rapid Portal's files directly, save those changes, and see the changes live.

Clicking on “Enter a file path and name to edit” shows the list of files.

Important files below:

• /login.mako - Login page
• /index.html - Main Application page showing embedded Tableau dashboards
• /css/style.css - Cascading Style Sheet for images, logos, colors, etc. Controls styling for both the Login and Index pages.
• /js/app.js - This is the JavaScript for the Rapid Portal. It leverages the zwaf.js and Tableau JavaScript API.
• /js/zwaf.js - JavaScript allowing the Rapid Portal front end to communicate with the backend Tableau REST API.

Save edits

You can edit any of the files and press CTRL+S or click the pink SAVE button to save. After saving, navigate to the page you edited and refresh your browser. You should see the changes reflected live.

HELPFUL TIP: It is best practice to create new files and edit those while testing changes rather than overwriting the main pages directly.

Create new files

You can create a new file by typing a filename and pressing enter or clicking the black arrow.

Branding

The /css/styles.css file is your one stop shop for branding the Rapid Portal.

You can customize anything, but we have simplified the pieces that are necessary and consolidated them at the top.

HELPFUL TIP: Split your screen so you can edit and save in the editor and then refresh the live page.

When moving to a production deployment there are two major questions to answer:

• Where do you want the Rapid Portal to be hosted?
• What URL do you want for the Rapid Portal?

Where do you want the Rapid Portal to be hosted?

The Rapid Portal is deployed via Docker and therefore can be deployed on any operating system that Docker supports (Linux, MacOS, or Windows) and on either physical or virtual hardware.

Hosting options

• Self hosted in your company's public cloud (Amazon Web Services, Microsoft Azure, Google Cloud Platform)
• Self hosted by your company on-premise in DMZ or behind the firewall
• Zuar hosted in Zuar's account

What hostname do you want for the Rapid Portal?

The Rapid Portal can be accessed via any domain your company owns.

Typical URLs include:

• https://analytics.yourcompany.com
• https://reporting.yourcompany.com
• https://portal.yourcompany.com

The Rapid Portal can use your company's SSL certificates or Zuar can generate one for you. All that is needed is an existing DNS A record.

Deployment

In the case where your company is hosting the Rapid Portal, please see the Self Hosted Questionnaire.

Without Rapid Portal

Without Rapid Portal, external users (customers, partners, vendors, and external employees) must connect directly to Tableau Server inside your company's firewall.

From Tableau documentation:

In most enterprises, Tableau Server needs to communicate with the internet. Tableau Server was designed to operate inside a protected internal network. Do not set up Tableau Server directly on the internet or in a DMZ. Instead, communications between your network and the internet should be mediated using proxy servers. Forward proxy servers mediate traffic from inside the network to targets on the internet. Reverse proxy servers mediate traffic from the internet to targets inside the network.

With Rapid Portal

Rapid Portal gives external users (customers, partners, vendors, and external employees) interactive access to embedded Tableau content without giving them direct access to Tableau Server.

In this use case, Rapid Portal  is serving as a reverse proxy for Tableau Server.

Read this Zuar WAF documentation: Trusted Host for Tableau Server Trusted Authentication

Get Share Link of the Dashboard from Tableau

With Trusted Tickets Configured for your Portal, you just need to pick a dashboard to use. Logged into your Tableau Server, click on the dashboard you want and then click "Share" at the top right of the screen (in green below):

The part of the share link we need starts with /t and ends right before ?; in this case: /t/Demo/views/Superstore-Mitto/Overview

Load a Trusted Ticket in Rapid Portal

Copy the relevant part of the share link to your clipboard, then in a new browser window, add it to your Rapid Portal's hostname with a trailing /z/trusted. The full path in your location bar should look something like this:

https://rapid-portal.portaldomain.com/z/trusted/t/Demo/views/Superstore-Mitto/Overview

... and the resulting Dashboard:

ssh -i ~/.ssh/<keyname> <username>@<portal_host_name>

Upon SSHing into the machine you should be in the home directory of the default user. If not cd ~. If you list all files in the directory with ls -las there will be four files/directories important to the architecture of your portal.

-rw-rw-r--  1 ubuntu ubuntu      781 Mar 24 14:00 .env
drwxr-xr-x  4 root   root       4096 Mar 16 19:38 app
-rw-rw-r--  1 ubuntu ubuntu     1108 Mar 18 19:33 docker-compose.yaml
drwx------ 19    999 root       4096 Apr 25 00:34 pgdata

Docker

Your portal is running in three docker containers. To confirm it's running and see the containers run docker-compose ps.

To stop all the docker containers: docker-compose down

To start all docker containers: docker-compose up -d .. This will start the containers in the background.

To view logs for the running containers: docker-compose logs -f --tail=100 or for a single container: docker-compose logs -f --tail=100 auth

All of the configuration for the docker containers is in the file docker-compose.yaml. Below is an edited version for reference:

version: "3"
services:
  zwaf:
    ...
    networks:
      - zuar
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./app/nginx:/app/nginx
      - ./app/static:/app/static
      - ./server.key:/etc/ssl/private/server.key
      - ./server.crt:/etc/ssl/certs/server.crt
      - /etc/letsencrypt:/etc/letsencrypt
    env_file:
      - .env
    depends_on:
      - auth
  auth:
    ...
    networks:
      - zuar
    volumes:
      - ./app/static:/app/static
    env_file:
      - .env
    environment:
      - GUNICORN_CMD_ARGS=--bind=0.0.0.0:5756 --workers=4
    depends_on:
      - db
  db:
      ...
      networks:
        - zuar
      volumes:
        - ./pgdata:/var/lib/postgresql/data
      env_file:
        - .env

networks:
    zuar:

As you can see, There are three containers defined: zwaf, auth, and db. In the zwaf block we map ports using the pattern - "host:container". Similarly, in all three containers we map files and directories on the host machine to directories in the docker container using the volumes block.

The volumes map is important, because it means that changes made to these files or directories on the host machine will also happen inside the container.

Finally, the defined .env file has information about the Tableau server, and PostgreSQL (more on that later).

Front-end Files

All front end files are located in ~/app/static/. Any number of custom html files can be added to this directory, and they will available in the UI of your portal. Additionally, CSS styles are maintained in ~/app/static/css/style.css, and Javascript in ~/app/static/js/. Most of the javascript will be found in app.js. Images and site assets will be found in ~/app/static/assets/.

Nginx

The server running your portal is Nginx. The configuration files are located in ~/app/nginx/nginx.conf as well as any conf file included in ~/app/nginx/conf.d/. The first file is general settings that apply to http, and the files in conf.d apply to the server itself, including locations, etc. Below for reference is the default nginx conf file ~/app/nginx/conf.d/default.conf (edited):

# SSL Redirect: 80 -> 443
server {
    listen 80;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;

    server_name  _;
    root /app/static/;
    resolver 8.8.8.8;

    #charset koi8-r;
    access_log /proc/self/fd/1;

    # ENABLE SSL
    ssl_protocols TLSv1.2 TLSv1.1;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "EECDH+ECDSA+AESGCM EECDH+aRSA+AESGCM EECDH+ECDSA+SHA384 EECDH+ECDSA+SHA256 EECDH+aRSA+SHA384 EECDH+aRSA+SHA256 EECDH+aRSA+RC4 EECDH EDH+aRSA RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP !PSK !SRP !DSS !RC4";
    ssl_certificate /etc/ssl/certs/server.crt;
    ssl_certificate_key /etc/ssl/private/server.key;
    ...
    ... location blocks below ...

The first server block redirects traffic from port 80 to port 443, and the second server block controls all traffic (on 443). Important settings to take note of are the server_name blocks, the DNS resolver, the ssl_certificate and the ssl_certificate_key. A server_name of _ matches any hostname.

Any changes made to the Nginx configuration will require restarting Nginx inside the docker container to take effect using: docker exec zwaf nginx -s reload

Env

Settings in the ~/.env file also effects the configuration of the portal. Below is an .env file for reference:

DEBUG=True
SECRET=<secret>
DATABASE_URL=postgres://root:<rootpass>@db/portal
POSTGRES_DB=portal
POSTGRES_USER=root
POSTGRES_PASSWORD=<rootpass>
TABLEAU_SERVER_URL=https://tableau.yourhostname.com
TABLEAU_SERVER_SITE=Demo
LOGIN_TEMPLATE=/app/static/login.mako
TOKEN_EXPIRY=7200
PORTAL_ADMIN_USERNAME=<adminusername>
PORTAL_ADMIN_PASSWORD=<adminpass>

The most frequently changed information is probably the TABLEAU_SERVER_NAME and TABLEAU_SERVER_SITE. Any change made to this file will require restarting docker to take effect using: docker-compose down && docker-compose up -d.

The Rapid Portal is sending a request to the Tableau REST API, specifically the "Query Views for Site" method.

Filtering by Tableau tags

The "Query Views for Site" Tableau REST API method can be filtered by passing a tag or set of tags.

app.js contains the JavaScript code that controls how the Rapid Portal application behaves. You can edit app.js by going to https://{your_rapid_portal_url}/edit/js/app.js in your browser. Learn more about the Rapid Portal in browser editor here.

You will edit one specific line of code to pass the tag filter and limit the views exposed to Rapid Portal users.

Update this line:

    zwaf.getViews().then(res => {

To this:

    zwaf.getViews({tags: ['embed']}).then(res => {

This will filter the available views in the Rapid Portal to only the Tableau views that are tagged with the word embed. Learn more about Tableau tags here.

As another example, if you wanted to filter by views with either embed or portal, then you would update that line to this:

    zwaf.getViews({tags: ['embed', 'portal']}).then(res => {

The customizer includes two sections:

• Theme - Brand the Rapid Portal's logo, login background, colors, and dashboard tags.
• Layout - Select from existing page layout templates and/or edit HTML, CSS, and JavaScript for a completely customized user experience.

This feature requires Rapid Portal v2.0+.

How Do I Open the Customizer?

After logging into the Rapid Portal, admin users have access to the customizer via their user menu and the "Customize" button.

Users without admin access will not see the "Admin" or "Customize" buttons in their user menu.

How Do I Customize the Theme?

The first section of the customizer includes quick options for changing:

• Logo - This is the image that can appear on the login page (depending on the template) and that appears in the header of the app page.
• Login Background - This is the background image/video displayed on the login page.
• Primary color - This is the primary color of the Rapid Portal. It appears in multiple places (login page’s log in button, dashboard loading icon, etc.).
• Login form background color - This is the color of the background of the login form.
• Header icon color - This is the color of the icons in the top right of the app page.
• Header background color - This is the background color of the index page's header.
• Dashboard tags - These tags control the filtering of dashboards in the Rapid Portal.

Logo

The logo can either be a relative or absolute path to an image. Drop in a file to host the file on the Rapid Portal and reference it locally.

Login Background

The login background image can either be a relative or absolute path to an image or video. Drop in a file to host the file on the Rapid Portal and reference it locally.

Color Picker Widgets

Color picker widgets are available for:

• Primary color
• Login form background color
• Header icon color
• Header background color

There are several options for picking colors:

• RGB
• HSL
• HEX
• Eye dropper

Dashboard Tags

Dashboard tags filter the dashboards available to each user. These filters are passed to the Tableau REST API's list of views.

How do I Customize the Layout?

The second section of the Customizer includes options for changing the template of these pages:

• Login - The login page for users.
• App - The application page that displays the embedded dashboards.

Learn more about Rapid Portal templates.

Next to each template is an “Advanced” link that takes the admin to the editor page. There the admin can edit all of the Rapid Portal code directly in the browser and make any further customizations.

Simple branding changes like swapping out images or colors can be done with the Rapid Portal's customizer in the UI.

For those with more in depth knowledge of JavaScript, the Tableau JavaScript API, and the Tableau REST API, the Rapid Portal can be completely customized and extended.

In Browser Editor

To make prototyping and simple tweaks easier, the Rapid Portal has an in browser editor. In production, this functionality should be turned off and only enabled if and when changes need to be made (rarely).

The editor can be opened by Rapid Portal admins through the user menu.

This in browser editor allows you to change any of the Rapid Portal's files directly, save those changes, and see the changes live.

Clicking on “Enter a file path and name to edit” shows the list of files.

Important files below:

• /login.html - Login page
• /index.html - Main Application page showing embedded Tableau dashboards
• /css/style.css

HELPFUL TIP: Split your screen so you can edit and save in the editor and then refresh the live page.

Save edits

You can edit any of the files and press CTRL+S or click the pink SAVE button to save. After saving, navigate to the page you edited and refresh your browser. You should see the changes reflected live.

HELPFUL TIP: It is best practice to create new files and edit those while testing changes rather than overwriting the main pages directly.

Create new files

You can create a new file by typing a filename and pressing enter or clicking the black arrow.

Typically in an embedded analytics application you want to expose a subset of all content that is available in Tableau. There is a specific use case and associated dashboards you are exposing externally to clients or you are just trying to simplify the user experience for your internal users.

Tags in Tableau

Using tags on Tableau content in your Tableau Server/Online is one of the ways to expose content in the Zuar Rapid Portal.

Below is a graphic showing all of the content in Tableau versus the subset of content (tagged with "embed") that shows up in the Zuar Rapid Portal.

Tableau documentation on tags here.

Authors can tag content when they publish it to a Tableau server. You can also add tags to any content you are allowed to access, and you can delete any tags you have added.

Permissions in Tableau

The Zuar Rapid Portal leverages all of the security on the Tableau side. Specifically, users in the Rapid Portal only see content they are allowed to see in Tableau.

Below is a graphic showing all of the content in Tableau versus the subset of content that a specific user has access to and therefore that shows up in the Zuar Rapid Portal.

Tableau documentation on permissions from a Tableau Server/Online perspective here. Tableau documentation on setting permissions as a content creator here.

How do I sort the content that is exposed in the Portal?

Now that you have content exposed in the Rapid Portal, you may want to sort that content in some way. By default, the content is sorted alphanumerically ascending.

Naming convention in Tableau

Favorites in the Rapid Portal

Individual users can favorite content they have access to in the portal to give them control over what content they want to see first.

Favoriting content can be done directly in the Rapid Portal by clicking on the star in the bottom right of any dashboard thumbnail.

Tableau documentation on favorites here.

Rapid Portal should be installed on its own dedicated server (VM or physical).

Operating System

The Portal is deployed via Docker and therefore can be installed on any system Docker supports. The following systems are supported by Zuar technical support:

• Linux (Ubuntu preferred)
• MacOS (AMD)

Prior to deploying via Docker, test to confirm Docker allows linux images:

docker pull alpine
docker run alpine ls -l

CPU

2 vCPU

RAM

4 GB

Disk Space

50 GB

Network

The Portal needs network access to any systems it is integrating with (e.g. database, Tableau, etc).

Inbound Ports

End users access the Portal via a web browser. Typically the Portal is configured to listen on ports 443 (and 80 redirecting to 443).

Supported Web Browsers

The Portal supports the last 2 major versions of the following browsers:

• Google Chrome
• Microsoft Edge
• Mozilla Firefox
• Apple Safari

1. The application code itself
2. A JavaScript library for accessing the Tableau REST API

The web application reads the list of Tableau views from the REST API and displays thumbnails along with loading the first dashboard. The list of dashboards shown is configurable in multiple ways, including all views on a site or all views with a particular tag.

The standard Tableau actions are listed in the header bar using the standard Tableau JavaScript API.

In the meantime, if you have questions on this Rapid Portal topic feel free to create a community post!

Action items

1. Create a DNS CNAME record for the Zuar Rapid Portal pointing to the Zuar owned hostname (e.g. customer.zuarbase.net).
2. Send the hostname (or URL) of the DNS CNAME record to Zuar. Zuar will create SSL certificates for the hostname.
3. Send Tableau information (Tableau Server/Online URL, Tableau Server/Online Site, and authentication mechanism) to Zuar. Read about how Zuar uses Tableau for authentication.