Turn your raw user data into a realtime reporting application in 30 minutes

A practical boilerplate for building your next multitenant analytics app brought to you by Reflect and Auth0.

Who’s this guide for?

This guide is for anyone that wants to give data insights to their users, but isn’t excited by the prospect of building and maintaining:

  • robust reporting APIs and charting components
  • user authentication flows from scratch.

To see an example of a finished product, visit our sample application.

blog/logistics-app-supplychain.png

Why this guide?

The two SaaS products used in this guide are free to setup and easy to use: Reflect allows product teams to integrate reporting and analytics into their applications, and Auth0 streamlines adding authentication flows.

After registering with Reflect and Auth0, you can swap the sample data in the app with your own data visualizations and user records. Just copy-and-paste the authentication tokens to your project. It’s that easy.

Acknowledgement: The boilerplate offered here is an extension of an Auth0 sample application found on their Github. They have an incredible assortment of user authentication flows documented here. The one I repurposed for this guide is built for a NodeJS web app using an embedded Auth0 sign-in form.

What you need

  1. This boilerplate
  2. Free accounts to Reflect and Auth0
  3. A SQL data-source (or a CSV saved to DropBox)

What you’ll get

  1. A reporting application with secure user login
  2. Free membership to Reflect for iterating on your live reports
  3. Free membership to Auth0 for easy user authentication

blog/logistics-app-supplychain-inapp.png

Look over the code (0:00)

Download the boilerplate

This boilerplate contains all of the logic needed to run your own realtime reporting app with user authentication. It provides a simple homepage, a login modal, and two data reports, or views.

Familiarize yourself with the code

Before we complete any sign ups, let’s understand the few files of interest in our boilerplate and how we are going to affect them.

.env.example

This file contains all of the project variables we need to get our app integrated with the services mentioned. Rename this file as .env and be ready to replace the empty variables with the tokens we will generate.

public

The public folder contains the images and styles used in the sample application. Feel free to modify where desired. The reflect-theme.css file provides a custom theme, built on top of the Reflect variables library. If you remove this file, uncomment the cdn linked in views/layout.pug to pull down the default styles for your Reflect reports.

routes

The routes folder contains the Express routes for our NodeJS app. index.js was configured by Auth0 and initiates the login flow. The unparameterized-user.js route is called when a user requests access to the Supply report—which is available to anyone that is able to log into our app. The parameterized-user.js route is called when a user requests access to the Distribution report—a secure Reflect report that enforces user authentication.

views

The views folder contains our views, or more specifically, templates written in Pug.js that are converted to HTML at runtime. In addition to outputting basic HTML, the distribution.pug and supplychain.pug files contain inline javascript that powers our Reflect reports. While the Supply report is available to anyone that is able to log into our app, the Distribution report enforces additional user authentication through Reflect. This added security protocol allows you to easily partition data by user or group.

app.js

Lastly, app.js contains the brunt of our backend logic, informing our application of necessary dependencies and protocols such as when to use a given route.

Set up Auth0 (0:05)

Configure the Authentication Flow

Sign up for Auth0. The modal you are using to sign up for Auth0 is very similar to the one already installed in our boilerplate—clean and with multiple login options. After signing up, you should arrive at the dashboard view, which provides high-level session data for users accessing our app. Shortly, it will reveal our first signups and logins.

blog/auth0-dash.png

To get started, let’s configure our application. Navigate to the Clients tab in the sidebar and click into the Default App. This Default App contains all of the tokens we need to integrate Auth0 with our boilerplate. Copy and paste the Domain, Client ID, and Client Secret from Auth0 to the like-named variables in your .env file. Next, add http://localhost:3000/callback to your Allowed Callback URLs and click Save. Now, when you submit your login credentials to your application running locally, Default App will return the response to /callback and index.js will authenticate or fail to authenticate your request.

Last, if you’re ready to connect Auth0 to your database of users follow the instructions here.

Test the login flow (0:10)

Start the local server

Navigate to your project directory in the terminal and enter npm install to install the project dependencies. Then enter npm start to start the local server. Visiting http://localhost:3000 in your browser now loads your application.

blog/logistics-app-home.png

Navigate to /login to find our embedded Auth0 login form. Create a new user or login with the credentials for a user in your Auth0-connected database. If you decide to create a new user, activate the account using the confirmation email. Upon successfully signing in, you can interact with the sample Supply report!

blog/auth0-modal.png

Conversely, if you navigate to Distribution in the navbar, you will notice that you cannot render the report embedded on this page. Because you do not have access to my personal Reflect project keys, you will not be able to render this report locally, but you can find it here. In the next section, you will learn how to generate your own Reflect project keys to embed secure reports into your application.

blog/logistics-app-distribution.png

Connect your data with Reflect (0:15)

Configure your database connection

Sign up for Reflect. Upon activating your new account, you will be asked to configure your first dashboard by by completing the following four steps:

blog/onboarding-flow.png

  1. Name your project. A project can contain many different reports, but can only be connected to one data source. The project for my sample application is named “E-commerce Sales”.
  2. Choose the appropriate connection type—some hosted SQL database, or a CSV on DropBox—and submit your credentials. Otherwise, a sample connection is available for testing the Reflect studio without a personal data source.
  3. Define the metrics and dimensions that you would like to graph. Join your tables, format your fields, and apply custom SQL expressions. You can always modify and add more fields later. This modelling layer is an abstraction of your underlying data source and will not affect your data source directly.
  4. Name your view. A view is a single report comprised of any number of visualizations. You can add multiple views to a single webpage or you can embed them across your site, and you can install controls on your views to swap date ranges, apply filters, etc. This sample application contains two views, Distribution and Supply.

Build your report with Reflect (0:20)

Visualize your data

Now comes the fun part. Click into your view, and click the + button in the navbar to create your first visualization. From here, the studio is your oyster. For some great ideas on how to get the most out of your data, see this post by the Reflect team. Otherwise be sure to explore the various component types and their display styles in the sidebar editor. To add some lightweight controls, a native datepicker and filterbar can be turned on from the general settings tab in the navbar. And, if you want to go back in time to see older versions of your report, toggle the revisions slider in the nav.

When you’re report is ready to embed, click Publish, and move on to the next section, or build another.

Embed your Reflect visualizations (0:25)

Embedding your report

Embedding your first report into the boilerplate is as easy as click, copy, paste. At the top of your view, click Embed to find your unique view identifier. Replace the token in views/supplychain.pug with your own. Refresh the page to see your live report.

blog/reflect-embed-modal.png

// call to render your unparameterized view
function render() {
    ui.view(document.getElementById('view-container'), 'your-token-here');
}

While that’s all it takes to embed a Reflect report into your application, you can also enforce user authentication through Reflect to partition aggregate data. In the Reflect studio, navigate to a view that contains a diversity of user entries. To provide a filtered-down and secure version of this report to each user, open the General Settings tab in the navbar and enable the Cryptographic Signing flag under Authentication.

Next, copy the unique view identifier as before and, this time, replace the sample token in the secure views/distribution.pug report. Ensure that the field and value attributes in your userParam object match up with those in routes/parameterized-user.js. Last step, copy the the access and secret tokens from your project settings page and save them to your .env file.

You have just built a secure, realtime reporting application for your customers in minutes.

Share your realtime reporting application with customers (0:30)

There’s plenty more to explore in Reflect—theming, custom controls, PDF exports—and an equal amount more in Auth0. We can’t wait to see where this boilerplate takes you and appreciate any feedback you and your customers have. Till next time, splining out.