Qlik Sense Extension Development with qExt
Using modern web dev tools to develop badass extensions
Have you ever wanted a button to set a variable in a Qlik Sense app? Ever been asked to show data in a Sankey Diagram? If you want any custom functionality or visualization in Qlik Sense, your options are either tell the users it can’t be done, or use extensions to provide enhanced capabilities. The power of Sense extensions is no secret, but those who are new to extension development often spend too much time figuring out how to set up a development environment, and not enough time actually building the cool visualizations they envisioned.
At Axis Group, we have been working on our own development template that we use to build extensions. Recently, we decided to package this up so anyone can download it and spin up an extension development environment in 3 easy steps (here’s the qExt project on GitHub). We’ll show you how easy it is to generate a new extension project, and even automate the process of deploying your project to both a Desktop and Server environment.
First-time installation
Install NodeJS
If you don’t already have NodeJS on your local machine, install it so that you can use npm to install and run qExt.
Install qExt
In your Command Prompt or Terminal Window, install qExt globally
npm install -g qext
3 steps to create new project
1. Install template files
Now that qExt is installed, you can begin using it to create new projects. Change the working directory of your command line to the location you would like to build your extension and run the following command (replacing my-extension
with your desired extension name):
qext --create-extension my-extension --install
After all dependencies finish installing, you will notice that your new project contains a src
directory with template files for getting started. These files are linked together using ES6 modules; qExt uses Babel and Webpack to compile your code before it is deployed to Qlik Sense.
2. Define deployment location (QS Desktop)
Before you start writing code, we need to tell qExt where to deploy the bundled extension. You’ll notice a file deployment.config.json
in the generated project folder. Here, we’ll update the username within the desktop.destination
property (Don’t worry about the server configuration just yet, we will cover server deployment later on).
3. Build, Watch, and Deploy
The last step is to run the npm script that will watch our source code for any changes, and automatically bundle and deploy the zipped up extension file to the Extension folder in our Qlik Sense Documents. To do this, run:
npm run watch-webpack-deploy-desktop
Any time you make a change to any file in your src
directory, the entire directory will be bundled using webpack, zipped up, and then copied into your Extensions
directory.
The environment
When you create a new qExt project, the generated environment will include a directory called src
where you will do all of your development. qExt uses Webpack and Babel, so you can use ES6 and file imports to modularize your code.
In src
, you’ll find a JavaScript file named the same as your project (ex. my-extension.js)— This is the entry point where we import all of our module dependencies:
This way, you can handle each of these properties/functions in separate files, and if you don’t need all of these modules for your extension, just delete unnecessary ones from your directory.
The project directory also contains a style.scss
file that uses SASS to style the content of your extension. It includes the class name of the extension container, so as long as all of your css/sass is written within the scope of this class, your styles won’t affect other Qlik objects.
Deploying to Qlik Sense Server
The above solution is great for local QS Desktop development, but if you’re like me, you want to develop and test your Qlik Sense Extensions against a server environment. Manually deploying your extension to your Sense Server can be a tedious effort; Every time you make a change to your code, you need to zip up your source files and import to the QMC (oh, and don’t forget to delete your old extension 🙃).
While developing qExt, we decided to address this issue by using the Qlik Sense Repository Service APIs to automate all of those actions for a hands-free server deployment process. This has allowed us to develop extensions locally on OSX, while running Qlik Sense Server on VMware Fusion (if you’re interested in how I set up Qlik Sense Server on my Mac, let me know in the comments and I can write another article on that).
First-time setup
qExt uses the Qlik Sense QRS API to push extensions from the development environment to the Sense Server. To deploy extensions to the server, we will need to set up a virtual proxy so that Header Authentication can be used to allow the deleting and importing of extensions (we’ll walk through the basic setup, but for more detailed information, see Qlik’s Header Authentication Config walkthrough). Note that Header Authentication acts as a backdoor into your server, and should only be used under the following situations:
- Use only between systems that can fully trust each other
- Use only in combination with a firewall, proxy or routing solution
- Use only in a development environment
1. Create Virtual Proxy
- Go to QMC
- Select Virtual Proxy
- Click Create new
2. Identification
- Enter
header-authentication
in the Description - Enter
hdr
in the Prefix - Session inactivity can be left to the default
30
- Enter
X-Qlik-Session-hdr
in Session cookie header name
3. Authentication
- Set Anonymous access mode to
No anonymous user
- Set Authentication method to
Header authentication dynamic user directory
- Enter
hdr-usr
in Header authentication header name - Enter
$ud\\$id
in Header authentication dynamic user directory
4. Load Balancing
- Click
Add new server node
and add desired node (I am adding Central node)
2. Click apply to save settings
5. Linking Virtual Proxy to Proxy
- Under Associated items select Proxies
- Click the
Link
button at the bottom of the page - Select the proxy service node you want to link to and click Link (again, I’m using the Central node here)
Now you can deploy extensions to your server!
Remember the 3 steps we took above to create and deploy an extension to Desktop? It looked like this:
- Run
qext --create-extension [name] --install
anywhere you wish to start a new project - Update
deployment.config.json
file - In the new project directory, run
npm run watch-webpack-deploy-desktop
and start coding
If we want to deploy to the server instead, we just have to update the server.host
and server.headers.hdr-usr
properties in our deployment.config.json
file with the hostname of our server and the domain\user admin account that will be used to deploy:
and instead of deploying to desktop, as we previously did in step 3, run
npm run watch-webpack-deploy-server
The above will tell qExt to watch for any changes in the src
directory, bundle the updated files with Webpack and Babel, zip them up, and then will delete the old extension in your server and import the new one.
Try it yourself. You should see the extension in your Custom Objects pane from any Qlik Sense application. Add a console.log() to your paint.js file and save it; You should see the update in your developer console when you refresh the Sense app page.
Build badass extensions
With the above resources, you can now start developing Qlik Sense Extensions in 3 easy steps. Just remember:
- Run
qext --create-extension [name] --install
anywhere you wish to start a new project - Update
deployment.config.json
with either the desktop extension destination, or the server hostname and username. - In the new project directory, run the script to watch and deploy to either desktop or server
Desktop:
npm run watch-webpack-deploy-desktop
or Server:
npm run watch-webpack-deploy-server