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 18 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 help documentation 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 the right resources.

1. Rename the template.env file to .env.dev.
2. Edit the .env.dev file with values that match your Qlik Cloud deployment:
   • OAUTH_BACKEND_CLIENT_ID and OAUTH_BACKEND_CLIENT_SECRET: specify the credentials obtained when you created the OAuth M2M client in the Administration activity center.
   • OAUTH_FRONTEND_CLIENT_ID and OAUTH_FRONTEND_CLIENT_SECRET: specify the credentials obtained when you created the OAuth M2M impersonation client in the Administration activity center.

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

   • TENANT_URI: specify the hostname of the Qlik Cloud tenant against which the app will run, such as z29kgagw312sl0g.eu.qlikcloud.com.
   • APP_ID: specify the ID for the Qlik Sense app that you uploaded to your tenant (used for analytics/sheet, classic/app, analytics/chart and classic/chart examples). For more information about IDs for common Qlik Sense embedded resources, see Find IDs for embedding.
   • ASSISTANT_ID: specify the GUID of the Qlik Answers assistant you wish to embed. Leave blank to omit this embedded UI.
3. (Optional) If you are using an app other than the provided Qlik Sense application, edit the .env.dev file with values that match your app:
   • SHEET_ID: specify a sheet ID from your app (used for the analytics/sheet and classic/app examples).
   • OBJECT_ID: specify a chart (object) ID from your app (used for the analytics/chart and classic/chart examples).
   • FIELD_ID: specify the name of a field from the Qlik Sense app (used for the filter pane example).
   • HYPERCUBE_DIMENSION: specify a field to use as a dimension for the hypercube (data) example.
   • HYPERCUBE_MEASURE: specify a measure expression to use as a measure for the hypercube (data) example.
   • MASTER_DIMENSION: specify a master dimension name used for the on-the-fly example.
   • MASTER_MEASURE: specify a master measure name used for the on-the-fly example.
4. (Optional) If you want to further configure your web app and integration, edit the following values in the .env.dev file:
   • SESSION_SECRET: specify a random long string that will be used to sign the session.
   • PORT: specify the port the web app will use when you run it with npm run dev.
   • USER_PREFIX: specify the prefix that new users will be created with when logging into the web app.

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 the project dependencies.

   npm install

3. Start the development server:

   npm run dev

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 3 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.