The main use of Qlik Sense mashup API is to visualize data from Qlik Sense apps and reuse visualizations in an app, allowing your users to interact with the data. But you can use it for other things to, like running a reload or interacting with Qlik Sense server.

But a Qlik Sense app can be used in two different contexts: desktop and server. While visualizations and interactions with those work the same in Server and Desktop, the server API (which is a REST API, unlike the QIX Engine API which works over the web socket. So the first thing we need to do is check our environment, are we in Server or Desktop. Luckily, there is a method for that, the isPersonalMode method.

Once we know if we are in Desktop or Server we can acct accordingly. If we are in Desktop, we can just call the doReload method. While this might work in Server too, we really shouldn’t use it. In a server environment you might very likely have different Qix Engines for interaction with the user and reloads. In fact it is very likely that the engine we are connected to does not have the right database connections for the reload, so running the reload there would fail. Instead we call the Qlik Server for the reload, and let it determine which computer should do the actual job. We can do this with the callRepository method.

This would look something like this:

You find a full working example in the Github repository.

This post is based on a session I originally held at Qonnections 2015, under the title ‘5 things you did not know you can do with the Mashup API’.

If you are using the Qlik Sense standard client there is a Selection toolbar displayed at the top of the page. It has lots of useful functionality, including search support, so in many cases you would want to use this in a mashup, which is perfectly possible.

But sometimes the selection toolbar does not fit in your web page or you want something more compact. In that case you can listen to selection changes yourself and visualize the selection state.

selections

The way to get the selection state is the getList method. An example:

The reply will contain a qSelectionObject with:

  • qBackCount and qForwardCount, the number of steps forward and backward that is possible
  • a qSelections array, with on entry for every field that is selected
  • the array entries will contain qField – the field name,  qTotal – total number of different values in the field and qSelectedCount – the number of selected values

Using this you can make your own visualization of selection state, or perhaps hide and show visualizations based on selection states.

When you use the getObject. call of the Qlik Sense mashup API (also known as the Capabilities API or qlik.js) it works a bit like a black box: you just call it and it will inject some Qlik content into your page , you don’t have to bother about the content, it might be any type of chart, it might even be an extension. But it you want to, you can access the data of the visualization.

The key to this is the return value from getObject. The method returns, as it says in the documentation ‘a promise of an object model’. That means you can use the return value to get access to the data in the visualization, or even call some methods to modify the visualization automatically.

Only you have to understand:

  • how a promise works
  • and how to find data in the model you eventually get

Promise

The fact that getObject returns a Promise means that you will get an object with a then method. The then method will take a parameter, a function, that is called when getObject is ready, that is after a while, normally just some milliseconds, so to you it will look like immediately, but for the computer this is a long time.

What happens when you call getObject is:

  • the browser will call the QIX engine over the web socket for the definition of the object with the id you supplied
  • when the definition comes back it will call the engine to get the data

Only after these two calls will the promise resolve, and the method you supplied as a parameter to the then method will be called. That means that at this stage the object you get will be a model with valid data.

The model

A good way to find out the contents of model is to use the debugger in your browser and inspect it. Some important parts of the model:

  • layout: this is the data for the visualization. Expressions, hypercubes etc will be evaluated and contain data reflecting the current selections
  • events, most important is the Validated event, which will be triggered when there is new valid data in the model. a full list is here ( the page refers to AngularJS-based extensions, but this is general, the same events is used for all visualizations, whether they are extensions or not)

So, to sum this up, you can get the title of the visualization like this:

You find a full working example in the Github repository.

This post is based on a session I originally held at Qonnections 2015, under the title ‘5 things you did not know you can do with the Mashup API’.

One of the really powerful features of Qlik Sense API’s is the possibility to dynamically modify visualizations. You can build solutions that allows the user not only to make selections and have them reflected in all charts displayed (that’s the default, you will get that automatically if you don’t turn it off) but also to dynamically change chart properties and do things like

  • change dimension from for example Product to Product Lin (or to Division)
  • change measure from Sales Amount to Quantity or Margin or Cost
  • add an additional dimension and make a barchart into a stacked bar chart
  • modify ordering
  • limit the chart to only show Top 10, or bottom 5
  • change the chart type from Barchart to Linechart or to an extension

And all of this can be done for both built-in visualizations and extensions in the same way. The key to all of this is the applyPatches method and soft patches.

Soft patches

A soft patch is a temporary change to properties for a visualization. The fact that it is temporary means:

  • it will not be persisted either in Desktop or Server
  • it will not affect other users using the same app
  • once the Qix engine session is closed it will be gone, so when the user reconnects, visualizations will be back to their original state
  • the user can make soft patches to visualizations that me does not have the right to modify

You make sure that its a soft patch by setting the second parameter in the applyPatches call to true. The first parameter is the list of patches you want to apply. Since you might want to apply several patches, it is an array, where each entry has three values:

  • qPath: the path to the property you want to change, with slash (/) where javascrip/json usually has a dot
  • qOp: the operation you want to perform, one of “add”, “replace”, “remove”
  • qValue: the value you want to set. This should be a JSON value inside a string, so a boolean value would be “true” or “false”, a numeric value something like “-1” and a string (this is the tricky part) “\”new string\”” (that is a string in a string). You could also set a javascript object, use javascript standard JSON.stringify method in that case.

Perhaps this is clearer if we look at an example:

What we do in this example is that we show a list of dimensions and measures to the user. When the user clicks on one of them, we move it to be the first one in the sort order, and use applyPatches to update the array and the chart will be resorted. Since it is all done with soft patches, it will not affect other users.

You find a full working example in the Github repository.

This post is based on a session I originally held at Qonnections 2015, under the title ‘5 things you did not know you can do with the Mashup API’.

 

The Qlik Sense Mashup API (also known as Capabilities API or simply qlik.js) allows you to inject Qlik Sense charts with full interactivity into your web page with just a few lines of code. It also allows you to dynamically define hypercubes, lists or simple expressions, send them to Qlik calculation engine and get results back, so you can visualize the data yourself. If you use the APIs all this would be well known to you. But there is more.. Let’s have a look at some more advanced things you can do.

Show visualizations in a tab

Sometimes you want a user interface that is a bit more advanced than just showing visualizations when the page is loaded. For example you might want to show the visualization in a tab, something like this:

visualization-in-tabs

This examples uses jQuery tabs, but you could use any tabs implementation, the basic ideas are the same. What you need to do to make this work:

  • when the user wants to add a new visualization, call the getObject method, with the html element and the id of the visualization as parameters
  • when the user switches between tabs, you need to call the resize method, to make sure that the visualization displayed is updated.

A code example. Note that much of this is actually more jQuery than qlik, the only part that is really qlik is the two methods calls:

You’ll find a working example in the Github repository. Note that the key to this is only two calls:

  • call getObject the first time the user wants to see a new chart, not when the page loads
  • call resize whenever the user changes tabs