Embed Qlik analytics and Qlik Answers using qlik-embed and OAuth impersonation

Overview

This tutorial shows how to easily deploy analytics and AI into your solution with a seamless login experience for your users, even when your web app or portal does not have a backend identity provider for user authentication.

This project leverages qlik-embed, qlik/api, and OAuth machine-to-machine impersonation capabilities. It showcases several embedding techniques, such as:

• qlik-embed classic/app: full sheet embed supporting the native experience.
• qlik-embed analytics/sheet: lightweight full sheet embed.
• qlik-embed classic/chart: load legacy charts in a similar manner to classic/app.
• qlik-embed analytics/chart: lightweight charts in a similar manner to analytics/sheet.
• qlik-embed analytics/chart on-the-fly: lightweight charts generated on-the-fly (the chart doesn’t need to be in the Qlik Sense app, it is defined in the web app instead).
• qlik-embed ai/assistant: provides access to AI assistants in Qlik Answers.
• qlik-embed analytics/field: lightweight way to render a list box containing dimension values.
• qlik-embed analytics/selections: lightweight way to render a full Qlik Sense selections bar.
• qlik-embed retrieval of hypercube data from an existing object.
• qlik/api retrieval of hypercube data without an existing qlik-embed object.

What you’ll learn

By the end of this step-by-step tutorial, you’ll have:

• Embedded Qlik Sense analytics into your solution using various qlik-embed techniques.
• Configured OAuth impersonation for a seamless user login experience.
• Deployed a working example of an embedded Qlik Sense app.

Prerequisites

• Node.js version 20 or higher.
• A backend OAuth M2M client with scopes user_default and admin_classic, and allowed origins set to http://localhost:3000.
• A frontend OAuth M2M impersonation client with scope user_default, and allowed origins set to http://localhost:3000.

Step 1: Set up your local project

In this step, you’ll set up a local development environment by cloning the GitHub repository or downloading the project files.

Method 1: Clone the GitHub repository

Clone the GitHub repository using the git clone command.

git clone https://github.com/qlik-oss/qlik-cloud-embed-oauth-impersonation.git

Method 2: Download and extract the project files

Alternatively, you can download and extract the project files.

1. On the project’s GitHub page, click Code.
2. Select Download ZIP.
3. Extract the content of the ZIP file in the folder of your choice.

Step 2: Upload the demo Qlik Sense app

In this step, you’ll upload a demo Qlik Sense app that serves as the data source for the embedded analytics examples.

1. Upload the demo Qlik Sense app to your tenant.
2. Open the app and copy the ID (it will be a GUID similar to 946d5af4-e089-42d3-9ba7-1d21adb68472).
   Note

   The project files contain some hard-coded values for this demo Qlik Sense app.

3. Move the app to a new shared space.
4. Edit the space configuration to provide Can view access to anyone in the tenant.
   Note

   In a production deployment, ensure the logged-in user has access to the app.

Step 3 (optional): Create a Qlik Answers assistant

In this optional step, you’ll create a Qlik Answers assistant that allows users to interact with indexed knowledgebase content using natural language questions.

1. Follow the Qlik Answers documentation on Qlik Help to set up a new knowledgebase and assistant, and index the knowledgebase data ready for users to ask questions.
2. Provide View and Can consume data roles to all users in the tenant for the spaces containing the knowledgebase, assistant, and any data connections used by the knowledgebase.

Step 4: Set up environment variables

In this step, you’ll configure environment variables to securely store sensitive information and connect to required resources.

1. Rename the template.env file to .env.

2. Edit the .env file with values that match your Qlik Cloud deployment.

   • OAUTH_BACKEND_CLIENT_ID and OAUTH_BACKEND_CLIENT_SECRET: credentials for the backend OAuth M2M client.
   • OAUTH_FRONTEND_CLIENT_ID and OAUTH_FRONTEND_CLIENT_SECRET: credentials for the frontend OAuth M2M impersonation client.
     Note

     Keep these secrets safe as they provide wide access to your tenant.

   • TENANT_URI: the hostname of your Qlik Cloud tenant, for example z29kgagw312sl0g.eu.qlikcloud.com (required).
   • APP_ID: the GUID for the Qlik Sense app you uploaded to your tenant.
   • ASSISTANT_ID: the GUID of the Qlik Answers assistant you wish to embed. Leave blank to omit this UI.

3. (Optional) If you are using an app other than the provided demo Qlik Sense application, add the following optional variables to .env to configure embedded examples:

   • SHEET_ID: a sheet ID from your app (analytics/sheet and classic/app examples).
   • OBJECT_ID: a chart/object ID from your app (analytics/chart and classic/chart examples).
   • FIELD_ID: a field name from your app (filter pane example).
   • HYPERCUBE_DIMENSION: field to use as the hypercube dimension (data example).
   • HYPERCUBE_MEASURE: measure expression to use for the hypercube (data example).
   • MASTER_DIMENSION and MASTER_MEASURE: master items used by the on-the-fly chart example.

4. (Optional) If you wish to further configure your web app and integration, update these values in .env.

   • SESSION_SECRET: specify a random long string that will be used to sign the session.
   • PORT: port the web app listens on (defaults to 3000).
   • USER_PREFIX: prefix used when the app creates demo users.

Step 5: Install the dependencies and run the app

Now that the project is configured, you can install the required dependencies and run the app locally to view the embedded analytics.

1. Open a terminal window and navigate to the folder containing the project files you extracted or cloned.

cd <project-folder>

2. Install dependencies.

npm install

3. Start the server:

npm start

4. Open http://localhost:3000 in your browser.

You should see your web app running locally with embedded Qlik Sense analytics rendered using various qlik-embed techniques.

Troubleshooting

• If the app does not load, verify the environment variable values configured in step 4 and review any error messages in the terminal.
• If you get authorization errors, verify the scopes configured for your OAuth M2M clients.

Next steps

Now that you have a working example, you can experiment with other qlik-embed parameters.