nebula.js/docs/web-integration.md

id, title

id	title
web-integration	Quick start

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

It will include the following steps:

1. Setup a Qlik Cloud Services 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, we recommend VSCode.

Setup a Qlik Cloud Services account

Though nebula.js works and can be integrated with all Qlik Sense products, this will guide you on how to integrate with Qlik Cloud Services.

Perform the following steps:

1. Register for a subscription on Qlik Cloud Services.
2. Configure your deployment.
3. Create a new web integration from the Management console.
   1. You will later on 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 will be assigned to it, this is the qlik-web-integration-id you will 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 QCS has a global unique identifier (GUID) which you will 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://qcs.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-qcs

The command will scaffold a web project into the hello-qcs 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 will need to make modifications later on to bring everything together.

Configure connection

To configure the connection you will need:

• The QCS 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://qcs.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 will run on http://localhost:1234.

When opening the page, you may be re-routed to your QCS tenant to login if the session timed out since you did the setup. Once logged in, you will be re-routed back to the develoment server where you should see the same bar chart:

The visualization is fully interactive, any selections you make will be 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 does not 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),
    },
  ],
});