Build a simple mashup using nebula.js

This guide walks you through creating a simple mashup that connects to Qlik Sense SaaS and visualizes some data.

It includes the following steps:

  1. Setup a Qlik Sense SaaS account
  2. Create a simple web project
  3. Configure connection
  4. Visualize data

and requires that you have:

  • node.js v10.0.0+ installed on your machine
  • A decent IDE, VSCode is recommended.

Setup a Qlik Sense SaaS account

Though nebula.js works and can be integrated with all Qlik Sense products, this guides you on how to integrate with Qlik Sense SaaS

Perform the following steps:

  1. Register for a subscription on Qlik Sense SaaS.
  2. Configure your deployment.
  3. Create a new web integration from the Management console.
    1. You later run the mashup from your local machine, to allow this connection to happen you should add http://localhost:1234 to the whitelist of origins.
    2. Once the web integration has been created an ID has been assigned to it, this is the qlik-web-integration-id you need later on.
  4. Upload an app
    1. If you don't have an app or data already prepared, you can download the movies dataset from the github repository and upload it to the cloud.

Each app on Qlik Sense SaaS has a global unique identifier (GUID) which you need later on. The GUID can be extracted from the URL and is the part that follows /app. For example, if the URL is https://your-tenant.us.qlikcloud.com/sense/app/7fc4d85c-0e07-4160-90a9-c2ca4a45fd81 , then the GUID of the app is 7fc4d85c-0e07-4160-90a9-c2ca4a45fd81.

Create a simple web project

The quickest way to create a web project is to use the nebula.js command line interface:

npx @nebula.js/cli create mashup hello-saas

The command scaffolds a web project into the hello-saas folder with the following structure:

  • /src
    • configure.js - Initial configuration of nebula.js
    • connect.js - Connection setup with enigma.js
    • index.html - A minimal html page
    • index.js - Connect and visualize

/src/index.js is where you need to make modifications later on to bring everything together.

Configure connection

To configure the connection you need the following:

  • The Qlik Sense SaaS tenant URL.
  • The qlik-web-integration-id.
  • the GUID of the app you want to open.

Open up src/index.js and update the <> placeholders with the correct values, for example:

const app = await connect({
  url: 'https://your-tenant.us.qlikcloud.com',
  webIntegrationId: '8Ys9sBVyq6i2lxtclPWaaZhQr7OgwKaT',
  appId: '7fc4d85c-0e07-4160-90a9-c2ca4a45fd81',
});

Visualize data

The movies dataset you uploaded earlier has a bar chart on the first sheet with the id EAjjuyE, you can render that same bar chart in your mashup by providing the id and an element to render the visualization into:

n.render({
  element: document.querySelector('.object'),
  id: 'EAjjuyE',
});

Start the web development server by executing the following in a terminal:

npm run start

The server is run on http://localhost:1234.

When opening the page, you may be re-routed to your Qlik Sense SaaS tenant to sign in if the session timed out since you did the setup. Once signed in, you are re-routed back to the develoment server where you should see the same bar chart:

mashup sample

The visualization is fully interactive, any selections you make are reflected in the current app selections toolbar at the top.

More visualizations

Render on the fly

You can render a visualization without having to create it in the app by providing the type and some data fields:

n.render({
  element: document.querySelector('.object'),
  type: 'barchart',
  fields: ['title', '=avg(rating')],
});

More types

The core stardust module doesn't contain any visualizations, each visualization is its own separate module and needs to be loaded and registered before it can be used.

Official visualizations from Qlik are published under the @nebula.js scope and are prefixed with sn-.

The available visualizations are as follows:

  • Bar chart: @nebula.js/sn-bar-chart
  • Line chart: @nebula.js/sn-line-chart
  • Pie chart: @nebula.js/sn-pie-chart
  • Sankey chart: @nebula.js/sn-sankey-chart
  • Funnel chart: @nebula.js/sn-funnel-chart
  • Mekko chart: @nebula.js/sn-mekko-chart

The template you created your mashup from only includes the bar-chart module, you can add more types by installing each one you want to use:

npm install @nebula.js/sn-pie-chart

Then modify /src/configure.js to include the new modules:

import piechart from '@nebula.js/sn-pie-chart';
//...

embed.createConfiguration({
  // ...
  types: [
    // ...
    {
      name: 'piechart',
      load: () => Promise.resolve(piechart)
    }
  ];
}