A new version of my Chrome extension Add Sense is now available. If you’ve already installed an older version it should be updated automatically, if not you’ll find it here.
App box moved
Probably the first thng you will notice is that the app info box now has moved, from bottom right corner to top middle. The old placement blocked som parts of the Qlik Sense UI, hopefully the new one works better.
More sheet info
The sheet info box now has some more info, like if the sheet is published or not, and if you can modify it. One of the mistakes I’ve made most in Qlik Sense app development is that I forget publishing a sheet before publishing the app. This is a reminder to help you avoid that mistake.
Reintroducing ‘Enable copy’
A few versions ago I made a menu alternative to help you with use copy and paste in Qlik Sense. I wasn’t totally satisfied with how this worked, so in a previous version I removed the ‘Enable copy’ feature. But it seems like users used that, in ways I didn’t think of, so now it’s back again.
Property panel definition
Lastly I’ve added a small new feature: if you’re in advanced edit mode and the property panel is visible, you will be able to see it’s definition. That can help you if your property panel does not work as you expected.
Much of Qlik’s focus is today on their cloud products. Getting up and running with Qlik Sense Business (the name Qlik uses for their entry-level cloud product) is easy. And even if the hub is different and there is no QMC, it feels familiar. After all it’s the same engine behind the scenes. Many (probably most) extension will also work, since the extension API is the same, and the Capabilities API also the same – almost. But even though the methods are all there, some of them actually don’t give the same result.
The global object in the Capabilities API
The differences I have found are in the global object, as should be expected. (documentation is here). So let’s try it.
The first method is getAppList(). In Qlik Sense Desktop or Qlik Sense Enterprise (which is Qlik’s name on the product you install yourself on a windows server) this method will give you a list of all apps the currently authorized user has access to. In Qlik Sense Business it still works, but if you try it, it looks something like this:
In my Qlik Sense Business hub, I’ve got four apps, but getAppList only returns the one I am currently using. So if your extension uses getAppList to create a list of other apps, it won’t work in Qlik Sense Business.
Another frequently used method in the global object is getAuthenticatedUser(). You use it to find out the users id. In Qlik Sense Desktop you’ll get ‘Personal\\Me’, in Qlik Sense Enterprise you’ll get a string containing UserId and UserDirectory. In qlik Sense Business it looks like this:
So, while the format is the same as in Qlik Sense Enterprise, the content is different. The UserDirectory is empty, and the UserId is actually the IdP subject you can find in the cloud console (IdP stands for Identity Provider).
callRepository
The Capabilities APIs has one method designed to call the repository, originally built to call Qlik Sense Enterprise REST API called callRepository(). It is marked as Deprecated, but it is still there in Qlik Sense Enterprise, and looks like it’s there in Qlik Sense Business too. What happens if we try it?
Qlik Sense Cloud has the REST endpoint /api/v1/items to list apps the user has access to. If we try it, it looks like this:
We do get a warning in the console, but the call works, the data array actually contains the four apps I’ve got in my Qlik Sense Business hub. But since it is deprecated we probably shouldn’t use it but use some standard method of making a REST call instead.
Version 1.3.0 of my Chrome Extension Add Sense is now available here. If you already have it installed, you should get the update automatically. These are the changes
Changed icon set
The extension now uses Qlik’s Leonardo UI instead of material design icons. The loading of Material Design icons does not work without configuration changes in Qlik’s cloud products, while Leonardo UI is already loaded.
Fixed bug when properties where treated like HTML elements
Sometimes expressions containing set analysis where destroyed in the tool. Mostly this happened when there was a letter immediately after the < character. That has now been fixed.
Other changes
If the visualization on screen is in the library, you previously only got the link (containing the id of the master visualization) in the property popup. Now you get the master objects properties.
The default filename when you save properties to file now contains the id of the visualization. You can still use another filename if you want to.
I while ago I wrote a post on using CSS in Qlik Sense, with focus on extension development (you find it here). Much of it is of interest also if you are making Themes. While that post is still relevant, there are some recent changes in the Qlik Sense client that are important to know.
Inline styles
Qlik Sense now uses more inline styles. An example is headers, that are now styled something like this:
This is because you can now actually set header color etc for some of the built-in charts. Where this is possible you will find a ‘Styling’ button in the property panel under ‘Presentation’, that gives you some new options:
Based on your settings here, Qlik Sense will create an inline style. Even if you do not have this section (looks like it is undocumented, if you find any documentation on it, please let me know) Qlik Sense will still create inline styles. Since it is an inline style, you will need to use !important if you want to override it, whether in a theme or in an extension, something like this:
A common request is that you want to disable the maximize functionality for some objects. While expanding a chart or a table to full-page is often a good feature, for many extensions, like buttons, or most text objects it makes no sense. This once used to be possible to do with some CSS, but because of changes in the HTML structure is no longer possible. But in the latest release there is a new flag under Appearance/General that allows you the disable the hover menu:
This is almost the same, though not quite:
everything in the hover menu will disappear
instead you can use the context (right-click) menu, where everything is still available, so you can still make a button full screen
A new version of my Chrome extension for Qlik Sense, Add Sense, is now available in Chrome Web Store. This is a pretty big version, actually that’s why it has number 1.2.1, because a bug sneaked into 1.2.0 which I had to fix.
New app level operations
You reach the new functions from the app popup box:
In fact, most of the buttons are new. From the left to the right they are used for:
showing the script
listing the tables
exploring the data model (in Catwalk)
listing variables
listing dimensions
listing measures
listing extensions used
listing active objects
Data model
A number of the new functions helps you with the data model. You can see what tables are defined in the app, and list dimensions and measures (and copy their definition into a program of your choice, like Excel or something). But perhaps the best new function is the link to Catwalk. Click on the compass icon, and it will open Catwalk with your current app:
If you don’t know what Catwalk is it’s time to get to know it knopw. It’s an open source tool from Qlik that helps you explore the data model of a Qlik Sense app. If it doesn’t work on your server, you might need to whitelist it. Check the documentation! Originally I planned to do some visualization of the data model, but I realized that I cannot make anything better than Catwalk, so why not reuse it.
List all active objects
The Add Sense extension uses Angular and some CSS selectors to find Qlik objects in your page, whether it’s the standard Qlik Sense client or a mashup. This only works for visualizations that are either Qlik Sense standard visualizations or extensions built with the traditional Angular-based method. But in a custom built web app using Qlik you might choose to visualize the data in some other way. Qlik Sense objects used this way have previously not been available in Add Sense, you could not check their properties, monitor recalculation times etc.
With the new function to list all active objects that has changed. While the little boxes showed on the page start from the HTML DOM and Angular scopes, this function uses enigmajs and lists all objects active in the enigmajs session. It might look something like this:
Example from the demo app ‘History of the fortune 500’
It still needs to find the enigmajs session, which might not work in all cases. If you want to use the extension for a case where it does not work, please let me know, you might be able to fix that with just a very small change.
Dimensions and measures
The extension can now also list dimensions and measures.
Dimensions
You can use the copy function in the dialog to copy the contants to the clipboard and then into application of your choice, like Excel etc.
Measures
And that’s it for the new functions. Please let me know if there is anything you are missing.
Whether you are building extentions in Qlik Sense or including Qlik Sense objects in a mashup you very likely will need some CSS. There are even some things you can really only do with CSS. And since Qlik released Themes support there is also the possibility of adding your own stylesheets to the Qlik Sense client with or without other changes, like extensions or mashups.
But stylesheets are different. They are not like javascript, with a defined API with methods, parameters and return values. Instead they have their own logic, with CSS selectors, specificity and interdependance. When something breaks, you won’t get error messages but things will just look wrong, not be visible at all or stop working. And very little is documented.
The qv-object rule
When you build an extension you can include CSS rules. To make it possible for you to add rules that affect only your extension Qlik Sense will add a CSS class with the format ‘qv-object-[extension]’ to the HTML element your extension is rendered in. So if your extensions qext filename is xxxx.qext, it will add the CSS class ‘qv-object-xxxx’. The idea is that you should prefix all your CSS rules with qv-object-xxx, somthing like this:
If you don’t do this, your styling might affect other content in the page. Sometimes that is what you want, but for normal extensions you should not do that. You might break other stuff in the page and create bugs that are hard to find.
Extension HTML structure
The structure your extension is rendered into looks like this(this is a simplified structure):
a .qv-object-xxxx rule will affect the whole box the extension is rendered in, including title
a .qv-object-xxxx .qv-object-content rule will affect just the extension body, not titles etc
a .qv-object-xxxx .qv-object-title will affect the title and possibly the subtitle
hoover buttons are outside of the qv-object-xxxx element and cannot be styled based on the qv-object-xxxx class
Note that this structure is as far as I know undocumented. It has been pretty stable so far, but still might change in the future. The same structure is used for both built-in and extensions, might be good to know if you are building a mashup.
Loading your CSS
To make your CSS rules work you need to load them in the browser. They should be loaded once, even if your extension is used several times in the same page/sheet. The best place to do this is at the very start of your code, at the beginning of the callback function in the define call.
There are two ways of loading the CSS. First you could add a link to the CSS file to the HTML page. An easy way to do this is with the requirejs css plugin, like this:
define( [ "css!./style.css"], function () {
/* requirejs will add a link to the document, nothing more is needed */
You could do this yourself too, but there is really no reason to do this, and you need to be careful and handle all cases, like virtual proxies and when your extension is used in a mashup not served by Qlik Sense.
The other possibility is to add the contents of your stylesheet to a style element in the document header. That requires a bit more code:
You can also do it without using jQuery, with standard javascript, but that means a few more lines.
The first method, adding a link to the stylesheet, has the advantage that references to external resources, like images and fonts, works, provided that you include those files in your extension too. But if you are running the extension in a mashup on an external (not Qlik Sense) server you might run into problems, since there are security restrictions on loading CSS from other servers.
That’s why I generally use the second method, adding the stylesheet text to the document. Images referenced in the stylesheet then needs to be Base64-encoded and included in the stylesheet itself. That works well for small images, if they are not too many. But if you have many images, or need to load for example font files, you should probably go for the link method.
Sometimes you need to know who the user is in your Qlik Sense extension or mashup. Perhaps you want to help the user filling in some data, display notifications to the user or something else that I can’t even think of.
getAuthenticatedUser call
There is no property containing user id (at least not someone that I know of), you’ll need to call an API one way or the other. The relevant call in the API is getAuthenticatedUser(), available on the global object.
In an extension, you should use the global property available on the app, so the call would be app.global.getAuthenticatedUser(). In a mashup it depends.. If you need to do this before the app is opened, you could use qlik.getGlobal(config) to get the global object. But be aware that this will mean another open web socket. If you can wait, it’s better to use app.global, since that means you will reuse the existing web socket.
Like most API calls, getAuthenticatedUser() is asynchronous, so you need to call it like this:
If you run this in Qlik Sense Desktop, you should get the string ‘Personal\Me’. But in Qlik Sense Enterprise it’s a bit more complicated. Ehen I run it I get: ‘UserDirectory=UPPER88QS; UserId=erik’. So this is a string, which contains two key-value pairs. You’ll need to parse this, to grab the UserId, or if you really want both values (perhaps you have more than one UserDirectory? Perhaps this is different between production – test – development?
Using OSUser()
But there is another method. Youd could use the Qlik Script system function OSUser(). In a mashup this is probably not a great idea, since you would need to either create a generic object containing OSUser(), or call the Evaluate method, not even included in Capabilities API, only in Enigma.
But in an extension the framework always creates a generic object for you and gets the layout. So you could add ‘OSUser’ to your initialProperties, and get the result in your layout, something like this:
In most cases you would of course have other stuff in your properties too, and they can easily be combined. Don’t show this in your property panel, if you don’t want your users to be able to change it.
This will mean that you in layout.user will have the user the same way as when you called getAuthenticatedUser(), you will probably need to parse it, but you don’t have to handle the fact that is it asynchronous.
A warning
This is all client side. That means it’s not really safe, you should not use this to restrict user access – it’s OK to use this to hide operations from the user that they should not be allowed to use, but you need to verify the user serverside too, in a safe way, that can not be hacked. But that’s another topic…
Qlik Sense allows you to add extensions to your installation. In a server environment you do this by importing a zip file, containing one or several extensions. In Qlik Sense Desktop you can unzip (the same) zip file to a directory under Documents/Qlik/Sense/Extensions.
The qext file
The qext file is what defines the extension. It’s a JSON file, it has to be valid JSON, but very few properties are mandatory. The qext file defines the extension root, Qlik Sense will make files the directory where the qext file and all directories under it available for HTTP calls to the server. So if you add an extension with the file xxxx.qext, you can fetch the file from the server with:
HTTP GET /extensions/xxxx/xxxx.qext
And all other files in the extension can also be fetched the same way:
HTTP GET /extensions/xxxx/xxxx.js
Sub-directories can also be used:
HTTP GET /extensions/xxxx/lib/jquery.js
Not that the directory name on disk is not relevant. On Qlik Sense Desktop you can build your own directory structure. Extensions in Dashbord bundle and Visualization bundle are kept in their own sub-directory, which doesn’t affect the URL used to load them. But if you do build a structure for your extensions, be careful that you do not keep duplicates of the same extensions. If you do you will not know which copy is actually loaded.
Multiple qext files
You can also have multiple qext files in the same zip file, which will mean that several extensions, and their files, are made available. Qlik Sense Enterprise will not allow you to have more than one qext file in the same directory, you can do this in Qlik Sense Desktop, but it is confusing, so you probably shouldn’t.
Multiple qext files is useful when you want to use the same files in more than one extension, like some library, CSS files etc. You can then put common files in one directory and add a qext file in it to make it available for all extensions. By putting them in the same zip file you make sure that they are updated at the same time as the extensions using the library. Another effect is that if the user is using two different extensions that use the same library, files will only be downloaded once. If every extension has it’s own copy of a library, it will be downloaded multiple times.
For Qlik Sense Enterprise you have no control over how the extension files are stored. It is not hard to find the files on disk, but the repository is responsible for storing them and serving to the client.
The extension type
One of the fields you always should have in the qext file is the type. In a visualization extension, that you should be able to use in the Qlik Sense client, it should be set to ‘visualization’:
"type": "visualization",
If you set it to something else, the Qlik Sense client will not load it and your users will not be able to create visualizations using it.
For mashups it is usually set to ‘mashup’:
"type": "mashup",
This is not absolutely necessary, your mashup will still work even if you set the type to something else, but if you want to manage it and possibly edit the file in Qlik Sense dev-hub you need to set the type to ‘mashup’. That also means that if you want to hide your mashup in dev-hub, set the type to something else (perhaps ‘webapp’ ?).
There are also a few other types used by Qlik Sense: ‘visualization-template’ and ‘mashup-template’. These types are used for the templates used in dev-hub when you create a new visualization or mashup.
If you plan to build several mashups creating a good mashup template with the look-and-feel you want might be a good choice.
The wbfolder.wbl file
One of the most misunderstood file in extensions is the wbfolder.wbl file. It is simply a list of files in the extension, with one line for every file, terminated by semicolon:
The wbfolder.wbl file is not mandatory. It is not needed for your extension for work, if you do have one it does not need to contain all files. It is only used by the dev-hub editors. Without it you cannot open or duplicate the extension in dev-hub.
If you do have it, only the files listed in wbfolder.wbl will be available in the editors. Also only the files in wbfolder.wbl will be copied if you make a copy of the extension or mashup. The other files will stil be available over HTTP, Qlik Sense will serve them.
A scenario I have seen used, is that a web developer buiilds a mashup, but then users (super-users ??) can modify files in it, like HTML, CSS or configuration files. In that case you can add a wbfolder.wbl to the extension containing just the files users should be able modify, but not other stuff, like libraries, possibly some JavaScript etc.
Sometimes when you are working with the Qlik Sense APIs you need access to information that is not connected to the Qlik Sense document you are working with, but rather to the QIX Engine running.
You find the apis for this in the global object in the Capabilities APIs, or in the Global class in the Engine API. While the Capabilities APIs only include very few methods, the full list of calls in the Engine API is much longer.
Finding the Global object
While there is a method in the Capabilities API to get the global object, in most cases you should not use it. In fact if you are building an extension you never should. Instead you should use the global property on the app.
That is because the getGlobal() method will open a new web socket to the engine, while app.global property will use the web socket used for the app. There is not reason to open another web socket to the server when you already have one, and in an extension there always is one.
The only situation getGlobal() should be used is when you do not have an open web socket, like in a mashup before the app is opened. And in that case you might be better off with a REST call.
As I wrote in Part 1 Chrome Developer tools is perhaps the most important tool for a Qlik Sense extension developer. Some important points in part 1:
you should turn caching off in the network tab, and keep developer tools open to make sure files are not cached
Qlik Sense client catches program errors in your extension, so if you need to see them temporarily check the box ‘Pause on caught exceptions’. You can’t keep this box checked all the time though.
In this post we will continue with some more useful stuff.
Checking web socket traffic
As you probably know communication with the Qlik Engine is over web sockets. You find the web socket in the Network tab, just click on WS and you will find it. Click on the websocket and then on messages, and you will see the communcation, something like this:
Lots of information, lots of transactions. Some things you should know:
messages from client to server has a dark background, messages from server to client a white background
all messages are in JSON format
if you click on a message it will be displayed in a format that’s easier to read in the area below
you can filter messages by typing in text in the field where it says ‘Enter regex..’
Connect request and reply
What you see in the web socket log is simply a list of all messages sent and received, in chronological order. Since commands are processed in paralell, the reply for a specific request might not at all be anywhere near the request. Request and reply are connected with the ‘id’ attribute (that’s a feature in the json rpc protocol, which Qlik Sense is built on). This means we can filter on the id attribute to find the reply for a specific request. If you try typing in “id”:1, in the filter box you will get request #1 and it’s reply:
Handling handles
So now we know how to find a request and it’s reply, but to really understand what’s happening we also need to understand handles.
Handles is a Qlik Sense specific concept, not part of Json RPC but an addition to it, made by Qlik. The QIX protocol is object-oriented, meaning that all commands are sent to an object. When you connect to Qlik Sense engine, the only handle available is the global handle, -1.
The first thing you do in most cases is call OpenDoc to open your Qlik Sense app (or Doc, as its called in the QIX documentation). If that succeeds you will get a handle (called qHandle) back in the reply. You can them send Doc commands to this handle (almost always handle 1). If you type in the filter “handle”:1, you will see all app commands used:
As you can see there is a lot of them. Most of them fetches or creates objects in the app, with GetObject or CreateSessionObject. You do not see the replies, only the requests, since the replies do not contain the handle. But if we instead filter by the id of one of the GetObject calls, (in my case id 13) we can see what happens:
As you can see in the reply there is a new qHandle in the reply, #5. So now we can filter on “handle”:5, and see what commands were sent to this object. If you want to know what handle is used for your extension, there is as far as I know no way to get that information from standard Qlik, but you can use my Chrome Extension Add Sense.
Find commands that invalidates object
Handles are used not only to refer to objects when you send commands, but also for invalidation. When you change selections (make a new selection, clear selection, apply bookmark etc) QIX engine tells you what objects are no longer invalid. It does this with the ‘change’ array (another addition to JSON rpc) which contains handles for the invalidated objects. So if I for example want to find commands that invalidated opbject 13, I can filter on “change”:\[.*13.*\] (note: a regex, since the handle can be at any position in the array):
We only get the replies for commands that invalidated the object, to get the actual command you need to use the id field to find the actual command and handle.
