Navigation

Dashboard

Overview

Estimated Time to Complete: 25 minutes

What We’ll Build

In this tutorial, we’ll create a real-time dashboard that displays customer purchase data from the point-of-sale system of a hypothetical pizza restaurant. The dashboard will have an automatically updating chart of recent customer purchases and a table of the most popular toppings from the last 100 pizza orders.

We’ll use Stitch to do the following:

  • Record customer purchases in a MongoDB Atlas cluster with a webhook function.
  • Query customer purchase data for order totals and popular toppings with server-side functions.
  • Prevent unauthorized users and clients from accessing data by requiring email/password authentication.

Prerequisites

You must have the following before beginning this tutorial:

  • A MongoDB Atlas cluster running MongoDB version 3.4 or greater. You can complete this tutorial with a free M0 MongoDB Atlas cluster. For information on creating an M0 cluster, see the Atlas Getting Started Guide

  • A MongoDB Atlas User API Key for your cluster.

  • A properly installed copy of stitch-cli that has been added to your system PATH.

  • Node.js version 6.0.0 or newer. See the Node.js docs for installation instructions.

  • A local copy or clone of the stitch-examples Github repository.
    This tutorial uses the dashboard directory within this repository.

Procedure

A. Import a New Stitch Application

Estimated Time to Complete: 10 minutes

All of the Stitch components needed to run the dashboard are available in a pre-configured application directory named dashboard-stitch within the dashboard/appdir directory of the stitch-examples repository.

dashboard-stitch contains configurations for the following Stitch entities:

  • An email/password authentication provider.

  • A MongoDB service that will link with your Atlas cluster.
    The service has custom read and write rules defined for the SalesReporting.Receipts collection. The rules remove sensitive fields, such as a customer’s credit card number, from read results and require specific fields to be included when inserting new documents.
  • A Stitch function named salesTimeline.
    The function returns data from MongoDB for orders made between the provided start and end timestamps.
  • A Stitch function named getPopularToppings.
    The function returns a sorted count of the most popular toppings from the last 100 pizza orders stored in MongoDB.
  • An HTTP service named PizzaOrderAPI.
    The service exposes a webhook named addOrder that adds customer order data to MongoDB when it is sent in the body of a POST request to the webhook. The webhook requires a secret query parameter to validate requests.

In this section, we will use the stitch-cli import command to create a new Stitch application that is populated with these entities.

1
2

Authenticate a MongoDB Atlas User

To import the pre-configured application directory, users must authenticate with Atlas using an API key.

Pass your Atlas User API key to stitch-cli to authenticate with MongoDB Atlas:

stitch-cli login --username=<MongoDB Cloud username> --api-key=<MongoDB Atlas API Key>
3

Optional: Update MongoDB Atlas Cluster Name

The mongodb-atlas service will attempt to link to an Atlas cluster in your project based on the value of clusterName in its configuration file. The service is pre-configured assuming that your Atlas cluster uses the default name, Cluster0.

If your Atlas cluster is not named Cluster0, edit the value of clusterName in the dashboard-stitch/services/mongodb-atlas/config.json file to match your cluster’s name.

Warning

If the clusterName value doesn’t match a cluster in your Atlas project, Stitch will not be able to link the mongodb-atlas service and the import will fail.

4

Import the Application Directory

Run the following command from within the dashboard-stitch directory to create and populate your Stitch application:

stitch-cli import

You will be prompted by stitch-cli to create a new application. Respond affirmatively, then provide your Atlas Project ID and a descriptive name of your choosing for the application, e.g. dashbord-tutorial. You can find your Atlas Project ID listed on the Settings page of the Atlas UI.

If you’ve set everything up correctly, stitch-cli will inform you that the app was successfully created and imported.

B. Set Up the Dashboard Client

Estimated Time to Complete: 15 minutes

We’ve successfully created a Stitch application and imported everything it needs to connect to MongoDB. Now we need to connect the client code with the Stitch application so that the dashboard can query and display your data.

The dashboard client code is located in the stitch-examples/dashboard directory. There are two files that communicate with Stitch:

dashboard.js
This file contains the dashboard client JavaScript code. It queries data from MongoDB using the salesTimeline and getPopularToppings functions that we imported in the previous section.
data_generator.js
This script simulates customer orders being entered into a point-of-sale system at a pizza shop. The order data is uploaded to MongoDB Atlas by including it as the body of a POST request sent to the addOrder webhook.

In this section, we’ll configure these files to connect to Stitch. We’ll also add a new user to the application so we can authenticate the dashboard client and run the addOrder webhook without bypassing MongoDB collection rules.

1

Create an Email/Password User

  1. Open your application in the Stitch UI.

  2. Select Users from the left-side navigation.

  3. Click Add New User.

  4. Enter the following user information then click Create:

    Username example@email.com
    Password mypassword
2

Configure the addOrder Webhook to Run as the New User

In order to enforce the SalesReporting.Receipts collection rules on all webhook requests, we must run the addOrder webhook as a Stitch user.

In the Stitch UI:

  1. Select Services from the left-side navigation.
  2. Select the PizzaOrderAPI service then click the addOrder webhook.
  3. From the Settings tab, set Run Webhook As to User Id then click the Select User button that appears.
  4. Choose the email/password user that you just created from the list of users then click Select User.
  5. Click Save to save your changes to the webhook configuration.

The webhook function should now run as if the user example@email.com called it directly whenever the webhook processes a request.

Important

While on the addOrder configuration page, note the values of the Webhook URL and Secret. We’ll use these in the next step to connect our data generation script to Stitch.

3

Configure the Data Generation Script

data_generator.js generates new pizza orders and uploads them to MongoDB Atlas using the addOrder webhook. To connect the script to our webhook, we need to provide it the webhook URL with the webhook secret appended as a query parameter.

In data_generator.js, find and replace <YOUR WEBHOOK> with the Webhook URL you got from the addOrder configuration page. Make sure to append the secret as in the following prototype:

<webhook url>?secret=yummypizza

After updating data_generator.js with your webhook, navigate to the stitch-examples/dashboard directory and run the following command to install all Node.js dependencies:

npm install
4

Connect the Dashboard Client to your Stitch Applications

In stitch-examples/dashboard/dashboard.js, find and replace <YOUR APP ID> with your Stitch application’s App ID.

Note

You can find your application’s App ID in stitch-examples/appdir/dashboard-stitch/stitch.json or on the Clients page of the Stitch UI.

5

Run the Data Generation Script

Run the following command in the dashboard directory to begin uploading simulated order data to your MongoDB Atlas cluster:

node data_generator.js

If data_generator.js was properly configured, you should see a continuous stream of documents being output in your shell as they are inserted into your Atlas cluster.

Important

The data generation script will continue to upload new data to your Atlas cluster indefinitely. Make sure that you terminate the script process when you are finished with this tutorial.

6

Launch the Dashboard

From a new shell window, run the following command in the dashboard directory to begin serving the dashboard locally:

npm start

C. Log In to the Dashboard

Nice work! The dashboard is now set up to communicate with your Stitch application and is being served locally. All that’s left to do is to log in and see the results.

Navigate to localhost:8080 in your browser. You should see a login form near the top of the page as well as a Popular Toppings table and Recent Pizza Sales chart. Enter the credentials of the email/password user that we created in the Create an Email/Password User step then click Log In:

Username example@email.com
Password mypassword

Assuming data_generator.js is running in the background, you should see the chart and table displaying data in real time.