Working with Qlik Sense variables

Introduction

Variables are a powerful feature in Qlik Sense that allow you to store and reuse values across your app. This guide shows you how to use qlik-embed to create, interact with, and delete variables in Qlik Sense.

A complete example is available at the end of this guide.

Prerequisites

To use the example page in this guide, ensure that you have the following:

An existing app ID and sheet ID to embed. This example uses this demo app that you can freely download and use.
A SPA OAuth2 client configured.

Variable substitution and vocabulary

Throughout this tutorial, variables will be used to communicate value placement. The variable substitution format is VARIABLE_NAME or <VARIABLE_NAME>. Here is a list of variables that appear in the sample code.

Variable	Description
`QLIK_TENANT_URL`	The domain for the tenant you are accessing. Equivalent to `tenant.region.qlikcloud.com`.
`QLIK_OAUTH_CLIENT_ID`	The clientId of the OAuth SPA you configured.
`QLIK_REDIRECT_URI`	The Redirect URL for the OAuth2 client to provide an access token.
`QLIK_APP_ID`	The unique identifier of the application.
`QLIK_OBJECT_ID`	The unique identifier of the sheet.

This example loads these values from process.env, which you can set in a .env file and reference when running the example with node.js 20+ using node --env-file=.env server.js.

You must connect to the Qlik Sense app before manipulating fields or selection. You do this with the qix.openAppSession method.

import { auth, qix } from "https://cdn.jsdelivr.net/npm/@qlik/api/index.js";

// Retrieve settings from environment
const QLIK_TENANT_URL = process.env.QLIK_TENANT_URL;
const QLIK_OAUTH_CLIENT_ID = process.env.QLIK_OAUTH_CLIENT_ID;
const QLIK_APP_ID = process.env.QLIK_APP_ID;
const QLIK_REDIRECT_URI = process.env.QLIK_REDIRECT_URI;


// OAuth authentication settings
const hostConfig = {
    host: QLIK_TENANT_URL,
    authType: "oauth2",
    clientId: QLIK_OAUTH_CLIENT_ID,
    redirectUri: QLIK_REDIRECT_URI
};

auth.setDefaultHostConfig(hostConfig);

let app;
let variables;

async function initQlik() {
    try {
        const session = await qix.openAppSession(QLIK_APP_ID);
        app = await session.getDoc();
        await listVariables(app);
    } catch (error) {
        console.error("Error initializing Qlik:", error);
    }
}

Examples of use

Learn what you can do with the Variable API.

Create a new variable

Use the createVariableEx method of a Qix Doc object to create a new variable.

async function createVariable(app, name) {
    try {
        const result = app.createVariableEx({
            qInfo: {
                qId: "13",
                qType: "variable",
            },
            qName: `${name}`,
            qDefinition: "sum(Ascii)",
        });
        await listVariables(app);
    } catch (error) {
        console.error("Failed to create variable", error);
    }
}

List variables

Use the qVariableList.qItems property from the layout of an app Session object.

async function listVariables(app) {
    const sessionObjectDef = {
        qInfo: {
            qType: "VariableList",
        },
        qVariableListDef: {
            qType: "variable",
            qData: {
                tags: "/tags",
            },
        },
    };

    try {
        const sessionObject = await app.createSessionObject(sessionObjectDef);
        const layout = await sessionObject.getLayout();
        variables = layout.qVariableList.qItems;
        displayVariables(variables);
    } catch (error) {
        console.error("Error getting variables:", error);
    }
}

Delete variables

Use the app.destroyVariableById method of a Qix Doc object to delete a variable identified by Id.

async function destroyVariables(variables) {
    variables.forEach(async (variable) => {
        await app.destroyVariableById(variable.qInfo.qId);
    });
    await listVariables(app);
}

Full code example

Below is an example built using qlik-api and qlik-embed web components.

Style sheet: web-component-variable.css

body,
html {
    margin: 0;
    padding: 0;
    font-family: sans-serif;
    font-size: 14px;
    background-color: #f5f5f5;
    color: #333;
    height: 100%;
    width: 100%;
}

div.flex-container {
    display: flex;
    flex-wrap: wrap;
    margin: 0 45px 45px 0;
    flex-direction: column;
    height: 50%;
}

.qvobject {
    flex: 1 1 auto;
    height: 300px;
    min-width: 400px;
    margin: 45px 0 0 45px;
}

.buttons-container {
    position: fixed;
    top: 10px;
    left: 10px;
    z-index: 1000;
}

button {
    margin-right: 10px;
}

div.list-container {
    flex: 1 1 auto;
    border: 1px solid;
    border-color: black;
    background-color: white;
    margin: 45px 0 0 45px;
    padding: 20px;
}

.viz {
    height: 500px;
    border: 1px solid #bbb;
    box-shadow: 1px 1px 10px rgba(0, 0, 0, 0.2);
}

JavaScript: web-component-variable.js

import { auth, qix } from "https://cdn.jsdelivr.net/npm/@qlik/api/index.js";

// Retrieve settings from environment
const QLIK_TENANT_URL = process.env.QLIK_TENANT_URL;
const QLIK_OAUTH_CLIENT_ID = process.env.QLIK_OAUTH_CLIENT_ID;
const QLIK_APP_ID = process.env.QLIK_APP_ID;
const QLIK_REDIRECT_URI = process.env.QLIK_REDIRECT_URI;


// OAuth authentication settings
const hostConfig = {
    host: QLIK_TENANT_URL,
    authType: "oauth2",
    clientId: QLIK_OAUTH_CLIENT_ID,
    redirectUri: QLIK_REDIRECT_URI
};

auth.setDefaultHostConfig(hostConfig);

let app;
let variables;

async function initQlik() {
    try {
        const session = await qix.openAppSession(QLIK_APP_ID);
        app = await session.getDoc();
        await listVariables(app);
    } catch (error) {
        console.error("Error initializing Qlik:", error);
    }
}

async function listVariables(app) {
    const sessionObjectDef = {
        qInfo: {
            qType: "VariableList",
        },
        qVariableListDef: {
            qType: "variable",
            qData: {
                tags: "/tags",
            },
        },
    };

    try {
        const sessionObject = await app.createSessionObject(sessionObjectDef);
        const layout = await sessionObject.getLayout();
        variables = layout.qVariableList.qItems;
        displayVariables(variables);
    } catch (error) {
        console.error("Error getting variables:", error);
    }
}

function displayVariables(variables) {
    const selectionsList = document.getElementById("selectionsList");
    selectionsList.innerHTML = "";

    variables.forEach((variable) => {
        const listItem = document.createElement("li");
        listItem.textContent = `Name: ${variable.qName}, Value: ${variable.qDefinition}`;
        selectionsList.appendChild(listItem);
    });
}

async function createVariable(app, name) {
    try {
        const result = app.createVariableEx({
            qInfo: {
                qId: "13",
                qType: "variable",
            },
            qName: `${name}`,
            qDefinition: "sum(Ascii)",
        });
        await listVariables(app);
    } catch (error) {
        console.error("Failed to create variable", error);
    }
}

async function destroyVariables(variables) {
    variables.forEach(async (variable) => {
        await app.destroyVariableById(variable.qInfo.qId);
    });
    await listVariables(app);
}

document.addEventListener("DOMContentLoaded", async () => {
    await initQlik();
    document.getElementById("createVariableButton").addEventListener("click", () => {
        const variableName = document.getElementById("variableNameInput").value;
        if (variableName) {
            createVariable(app, variableName);
        } else {
            alert("Please enter a variable name");
        }
    });
    document.getElementById("destroyVariableButton").addEventListener("click", () => {
        destroyVariables(variables);
    });
});

HTML: web-component-variable.html

<!doctype html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <link rel="stylesheet" href="https://clip.eu.qlik-stage.com/resources/autogenerated/qlik-styles.css" />
    <link rel="stylesheet" href="web-component-variable.css" />
    <script src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js"></script>
    <script type="module" src="web-component-variable.js"></script>
</head>

<body>
    <div class="buttons-container">
        <input type="text" id="variableNameInput" placeholder="Enter variable name" />
        <button id="createVariableButton">Create Variable</button>
        <button id="destroyVariableButton">Delete Variables</button>
    </div>
    <div class="viz">
        <qlik-embed ui="analytics/chart" app-id="%QLIK_APP_ID%" object-id="%QLIK_APP_OBJECT_ID%" />
    </div>
    <div class="list-container">
        <h3>Variables</h3>
        <ul id="selectionsList"></ul>
    </div>
</body>

</html>