This session covers:
- What APIs can do for you
- Using API keys
- Integrating objects in apps
- What to do when things go wrong
00:00 - Intro
00:42 - Why use APIs
01:45 - Demo Creating an App with APIs
05:12 - What APIs to use
06:26 - Where to find more about APIs
07:37 - Authenication and Initial Setup
10:14 - How to Embed a chart in an iFrame
13:43 - Using Authentication Keys
17:45 - Troubleshooting Authentication Keys
18:18 - Embedding in a SaaS Mashup with APIs
21:05 - Troubleshooting Embedding in a Mashup
25:08 - Using Fiddler
26:20 - Additional Resources
26:52 - Q & A
How to Create a Mashup
How to Embed a chart in an iFrame
For more information:
Leveraging APIs on Qlik Sense Enterprise SaaS - Article
Hi everyone. My name is Damien. I'm
working as a senior technical support
I've been working at Qlik since 2013 and
my main focus
is Qlik Sense APIs and authentication.
So, today's agenda is Leveraging APIs
in Qlik Sense SaaS. So, we are gonna first
about why use API; then
what API you can use; how to use them
and what to do when things go wrong.
Okay Damien, I've heard a lot about APIs
but what exactly can APIs do for you? Why
would you use them?
So, you would use API to automate some
or call them from an external program. So
perform some administrative tasks so
basically, everything that you can do
in the console in Qlik Sense Cloud. You
can do some front-end
action such as: applying a selection,
applying a bookmark.
Is it free to use APIs or is there
some sort of special licensing that's
So, you don't need a special license to
But based on the action that you are
gonna do; for example, if you want to do
an action inside an app, modifying an
app then you would need to have a
license assigned to the user because
users are allowed to modify an app. You
can call directly the Qlik
Associative Engine with your own data
and you can embed
Qlik Sense objects on your own website.
So, it's kind of just a different
interface with the program.
Can we see some of these APIs in action?
So, we are first going to Qlik Dev
and use one of the examples that is
I guess Qlik Dev would be where someone
would go to get started using APIs?
That's right. For Qlik Sense SaaS, that's
the best place to get started with APIs.
We're gonna first look into Qlik CLI.
What we're gonna show now is how to
app, add the load script, and then
reload the app
so just a few commands will create an
app add the load script and reload it on
your Qlik Sense SaaS tenant
that's correct. So first of all,
we're going to run this command. I'm
my Qlik Sense hub and verify that I
one app “Consumer Sales” in my tenant.
Okay and now I'm gonna run the command
the app. So this is just a regular
Windows command prompt?
Yes, that's just a regular Windows
and Qlik CLI has been installed prior
We are now getting the app id of the app
That just got created.
We can go back to the
and check the app.
That was quick.
So we can open
the app and check its contents.
Go to the script editor. We can see that
for now, we only have the default line in
the script editor.
Okay, we're now gonna run the command to
add the script to the app that you can
also find on this
same page. We need to put the app
in a Qlik script file. O
Okay, so you
already have a separate file that has
the script that you're going to insert
into this app?
That's correct. I've created already a
that I've placed on the C drive.
Here we can see the content of this file.
So that's just
auto generated script that let you
dummy data and you can insert this in a
Qlik Sense script
just by pressing ctrl 0 0 from the
script editor usually.
That's a great tip.
People may not be aware that if you just
go into script editor in Qlik Sense
type in ctrl 0 0, it'll auto generate
script, which will create dummy data for
That's a great tip Damien!
So now we're
gonna go to the
command prompt again and we are gonna
this line. And I need to
copy this app id.
The app has been saved you can go back
data load editor and refresh the page.
And there's your script.
Then the next
step would be
to reload this app. The command which is
also available on this
same page on Qlik, but there now the
command that we're gonna type is this
Same app id. Now I'm gonna go
back to the hub. I can go to
details. If I go to the reload history,
I can see that the app was reloaded
successfully and it took five seconds to
That's pretty cool. So three lines of
Code; you have an app with script and
reloaded. What are other kind of APIs
that you can do or what sort of
actions can you perform with APIs,
besides the three that you just showed
Basically, anything that can be performed
in the console
can also be confirmed with the rest APIs,
which are for administrative tasks.
any kind of
front-end action: which would be applying a
apply your bookmark; create alternate
state; all those kind of things.
And there's an RPC API where you
interact directly with the Qlik engine
Can be used to do any kind of action
is done inside an app. Then we have the
The libraries are used to facilitate the
use of the APIs.
Enimga.js is to communicate with
the Qlik engine
having to deal directly with json RPC.
And Enigma.go is the same thing for go.
And then you have Nebula.js that is
used to facilitate the creation of
And the demo you showed us
Before; that was with Qlik CLI?
That's correct. So the demo we did just
before was done with the tool that is
called Qlik CLI.
Okay. Where can we find out more
information about these APIs?
You can find more information about APIs
Qlik.Dev. Here, which are
getting you started the different things
that you need to
know before you use the APIs. Then the
different types of APIs are available
You can see everything that
is actually a public API currently.
Everything is in here. So you might
notice that some of them
are marker as “experimental.”
Yeah, I was wondering what that meant.
You can find what it means in the API
There is no deprecation period for
“Stable” - you have a six-month deprecation
period and “locked” have a 12-month
So, it's even more important in SaaS
because you don't have control on the
version that is run on the server as
it's constantly updated.
So which APIs would you recommend using
in a production environment?
So, in a production environment, it is
recommended to use a stable or locked
What other sort of setup is
required before you can actually start
In order to use the API, you must take
how you authenticate to the API and also
do some initial
setup for the authentication part. You
either authenticate with an API key
or through interactive authentication,
which is done through
the Qlik id or with your own IDP,
your identity provider.
Okay so one or the other, or
are there some situations where you
might need both?
Mainly API keys you would use for a
is run server side. Where interactive
authentication you would use
for a program that use on the client
side. So for example,
when embedding an object in a browser,
then you would have to go with the
And it's also good to note that
anonymous users are not supported.
In Qlik Sense SaaS, you will have to
if you want to use the APIs or embed a
Qlik Sense object in your website.
Well that makes sense. It's highly secure
so Qlik Sense SaaS
needs to know who is submitting commands
Then regarding the initial setup, we have
the web integration ID
and content security policy which are
secure the ways that Qlik Sense objects
are integrated in a website.
Do you think you could show us an
example of actually embedding in a
So I'm gonna show how to embed Qlik
in an iFrame.
I see we're back on your
tenant management console.
The first thing that we need to do would
be to set up
the web integration and the content
In this case, I will be running my iFrame
on my IIS server which is installed on
my server here, which is called
Okay and that's just a machine you've
already set up a web server using IIS.
Yes, that's correct.
Here I'm getting my web integration id
that I will use later in my sample
and I will create also the content
In this case, I'm also using the
qlik.server2.domain.local and I will select
What is “frame ancestors” specifically or
why did you add that?
“Frame ancestors” means the parent
In here in the origin I've put my parent
and I will be allowed to embed in an
only from this website. Now I'm gonna
use a sample that is available in our
knowledge base that can easily be found
from our support knowledge base or just
Like just typing “Qlik Cloud Services
What I'm gonna do is just copy all of
So this is basically a script that will
allow you to embed a Qlik object into
That's right. What I'm gonna do now is
just create a new file.
Paste the script. Save it. I'm gonna
move it to the is folder later on. What
the only reason why I'm not doing it
directly is that I don't have
rights to save directly in the IIS folder.
Now I've saved my file and you see that
I have the coloring
making this much more easier to read. The
next thing I'm gonna do is replace
“your tenant” by my actual tenant name.
That’ss a pretty handy way of updating
things like that.
Yes, control F to show this window and
this button will just replace all. We are
gonna now copy the
web integration id that was just created
and paste it here. Then the next thing
that we are gonna need to update
is this link with the iFrame here.
We're gonna use a demo app for this
“Consumer Sales” so it's not imported by
default in a Qlik Sense
Cloud environment but it can be
We need to go and fetch an actual object
For example, there is a map object here.
Just right click,
choose share and then choose embed.
Then you have the iFrame link here to
You can just click on “copy” and we're
gonna replace this whole block
here with iFrame code that we've just
Then we can just save this file. And I'm
now this file in my IIS root folder
in here. Now I'm gonna
run Chrome as another user just to show
the whole flow
of how this sample will redirect you to
identity provider if you're not logged
in yet. Add a new person here and
I prefer to do that instead of running
as an incognito session because incognito
some specific security settings that
would make it look different from an
And this could be an alternative
to running the application as a
different user because you're just
a new user to run the application. Great
That's correct. I'm now going to type the
name of my IIS server. All right.
you're visiting that page you created.
Yes. I'm getting redirected now to my
identity provider which is Auth Zero in
Now we can see the iFrame loading
and we can also interact with this chart
by just clicking and making a selection.
And this is your iFrame page. Just
kind of blank at the top, blank at the
bottom but it has the object
embedded in the center,
That's correct, yes.
So what do you do when things don't go
perfectly as expected? How would you go
something going wrong?
When things go wrong,
we have different way of troubleshooting
based on which API
we want to troubleshoot. PowerShell or
cURL if you're on Mac or Linux.
To troubleshoot rest APIs, then browser
developer tools must be used. To
troubleshoot web applications
and check how things can be done from
the hub, for example.
And we have Fiddler which is a network
Okay, what are we looking at?
So here we
have a script
that is creating a new API
keys. In this case, I'm creating
an API key which would be named “test4”
and has a validity of one day. As an
administrator you also have a bit
more control on the API key. For example,
you can enable them; that's the first
step. When you create an API key
there's a tutorial for that on Qlik Dev.
There’s also if you go in tutorial and go
to generate your first API key.
You have the whole procedure on how to
Basically you would need to enable them
Then you set a maximum token expiration
in this and then you can also set a
number of active API keys per user. So
you make sure that users don't create
tons of API keys
which would lower the security of the
system. Soing this
from the API is actually very handy
an API key expired you would need to
So that's my current API key that is
valid and I'm using
this one to request a new one. So when
you renew an API key you would need to
apply the same logic in your own code.
Before the expiration date,
run this kind of command; and get a new
API key and then update it from your
Which would make it much more easier
you only need to get the API key from
the UI the first time you get one.
So Damien, when working with API keys,
what do you recommend?
I like to use PowerShell to troubleshoot
because you can see exactly what body
you are passing,
which header you are passing, and you can
in this case narrow down
if there's a logic problem in your own
or if you're just passing the wrong
And where did you get the code that
we're looking at?
This little sample was
the reference of this API on Qlik Dev.
If you would go to
APIs and go to API keys then you have
“create an API key resource” with the
documentation on how to do it.
But if you're not very sure
on how that should be done, a good tip to
is to go directly through the hub or
through the console.
In this case, we go to the hub because
the API keys are created from the hub.
In settings, and you go to “API keys.”
And you would open the browser developer
And how did you open the browser
So that's done by pressing f12. You can
also find them
in the menu here, developer tools.
And going to the network tab here.
Then you would just do the action that
you are trying to accomplish with the
API. Put the name here, click on “generate.”
So here this succeeded. And you can
just click here and see the API
that was sent which is they currently
And if I just paste, you would see
that nothing has changed.
If you go a bit more down here and
look at the body, you would see for
That's great seeing the
demonstration that the APIs are really
just performing the same actions as the
And that you can find the exact code to
use via the developer tools.
Great tip Damien! So far everything's
been going right.
What could go wrong here?
What could go
wrong is that you have; for example, a
format in the expiry. And that would -
In this case, it's because I've reached
the maximum number of
API key that you're getting this error.
For that -
So I would need to actually delete the
I'm just gonna do it from the UI.
this time. I can delete this
test4 and go back to
PowerShell and try to create a new one.
a wrong format and that would give you
this kind of error.
The next example,
that is embedding into a mashup
and also how to troubleshoot when it
mashup. For this example, I'm gonna
use this sample that can also be found
support knowledge base. And gonna copy
I would need to create two files this
What tool do you use to create those
I'm gonna go in with Visual Studio to
create a new file.
Paste the code here. Save.
I'm going to call it “helpdesk.html.”
I'm also going to replace your tenant by
Is there anything else that
needs to be updated in this file?
Not in this file. The second file that we
Just gonna copy this whole code. Create a
Paste it here. I'm just gonna save it as
So if you call it something else,
you would also need to update it here.
And what is this mashup that you're
creating supposed to do?
will just show one object in
a dev element and can add a few more
And see what to troubleshoot when it
First of all, I'm going to replace your
tenant by my tenant name.
Then I'm going to update the web
And again, that's the id that allows your
private web server to interact with your
Qlik Sense SaaS environment?
Yes. Now we're gonna actually
need to update the app id.
And also the object id is the object
that we want to show.
Just gonna go back to the hub again and
pick up my favorite
So this time we can pick up this
chart. Go in “share” and “embed”
but this time we will just need to copy
object id here. And paste it
here and then update the app id.
The easiest way is just to copy it from the
Then just save the file. And now we are
copy those two files that we just
created to our IIS
So I'm just gonna reuse that same
just go to “helpdesk.html.”
That was a great demo when everything is
working. Would you be able to show us an
example where things
aren't behaving as expected, so we can
see how to troubleshoot that?
This example is actually exactly the
same one, but I've added these two lines.
One line which is to show the current
Selections in an object.
And another line which is
done to apply a bookmark.
Okay and that bookmark is called “Product
That's correct. And I've also moved
around the object and
resized so that it looks a little bit
Now we're gonna see this example
in our browser with the browser
developer tools open
so that I can see what is happening. I'm
in the network tab,
and I have filtered on websocket.
In my bookmark I have two selections
applied, but this bookmark
seemed to not have been applied. I'm now
going to check
in the websocket messages why that
bookmark didn't get applied.
I'm gonna search for “apply”
which would tell me - that's exactly the
command that I run – “apply
bookmark.” So it was actually sent. The
request was sent; I can confirm that
from here. And now I'm gonna check the
response of this request.
For that need to search for the ID
So hopefully the response from Qlik
Sense will tell us what happened?
That's correct. And here we can see
“qSuccess” that was “false” and means
that applying this bookmark did not
We can see here that the parameter that
was passed was “product
group.” So let's go and check the
documentation for “apply bookmark”
and see if we did things correctly. We
is part of the capability
I'm now gonna go to the help site. The
is actually almost the same in Qlik
Sense for Windows and
Qlik Sense for SaaS. And on
you also have the same documentation on
You have to pass a bookmark id. So the
bookmark id here
which should look in this example like
But what we've passed is the bookmark
name, which is incorrect.
Okay so; in our code, we entered the name
of the bookmark instead of the actual
string which is the bookmark id?
That's correct. So the bookmark id
actually would wither be in this format
or this format.
It would have been so
much nicer if it returned an
error message instead of just not
working. But this is a great
troubleshooting tip, so you can see
why that actually happened and the
reasons behind it.
We're gonna find this
bookmark id in order to apply it. There's
not really an easy way to find this
bookmark id from the UI,
unfortunately. We are gonna apply this
bookmark from the UI
and check from the developer tools its
id in the same way that we were
shooting our mashup,
we would open the browser developer
tools with f12 or through the chrome
“more tools”, “browser developer tools.” In the
network tab -
and refresh the page.
Then filter on WS - web sockets
and take this WebSocket here.
Now we're gonna apply this bookmark.
So search for “apply” and we are finding
this method with “apply bookmark”
and in the parameter. Here we see the
bookmark id. So we can copy the bookmark
id from here;
and just put it in our code here. Just
again to my IIS server.
Just to be sure that my mashup works now;
Remove the bookmark first, and
close out of this. And now I'm gonna go
back to my mashup.
And refresh the page.
And I see here that I now have - my
applied with the two selection.
tool that we had was a Fiddler which I
can briefly talk about.
And when would you use Fiddler?
Fiddler can be used
to trace the network. it's is a little
bit similar to what you see actually
in the browser the development tool - network tab.
But you would use it where
you are troubleshooting an API that is
not run from the browser.
So for example, if you run something on
server. An application on your server
that is sending requests to
Qlik cloud; then you would use Fiddler
to troubleshoot if the request is going
What kind of application might that be,
just as an example?
For example, if you
want to run
an automation tool on your server: a
JS application that is triggering tasks,
then triggering another task on
all those kind of things. And as it
doesn't run in a browser, you won't be
able to use the network
tab, but you would be able to use Fiddler.
install Fiddler on the machine or from
where that application is running
and you would be able to see the same
kind of things that you see in the
in the browser developer tool.
are some other resources people can use
to help troubleshoot?
When things go wrong, you can use some of
those additional resources.
Collaboration and assistance on Qlik
On the Qlik Branch slack channel.
There's documentation on qlik.dev and
and finally, if you find a defect, you can
report it to Qlik Support.
Okay everyone now it's time for
Q and A.
Please submit your questions through
the Q and A panel on the left side of your
Damien, which question would you like to
The first question uh is
how to set up a Qlik Sense object in a
mashup to automatically refresh.
It's not very clear to me if refresh
means to refresh the page or refresh the
So to refresh the page, you would need to do
it from the mashup code. To
refresh so just reload the page so that
it shows the most recent state.
If refresh refers to refresh data then
you would need to trigger
the reload through the either to the
more documentation can go basically
found on Qlik.dev on how to
to do that well actually for the rest
is you will need to do it from the
close here create a reload
reload an app specified by an app id
and if you want to do it through the
also in the capability API
I have a question for you Damien an
example like this
like reloading where there are several
different APIs that can perform the same
how do you decide which one to use like
for reloading the way that you would
decide which one to use would be
if you want to do it as
an administrator or as an app developer
basically this the one from the from the
capability API would be the same thing
then pressing the reload button
in the data load editor and that can
only be performed by
a user that is a professional user and
that would also
block the app while the reload is being
performed while if you do it through a
that won't unlock the app when the
reloaded perform and it will just
refresh once it's finished if you're
using the app
in a custom interface and are doing
modification on the app and you want to
reload from that interface then you will
want to use the capability API to reload
while if you just want it to reload
transparently to the user then you would
use the rest API to reload it as a task
okay next question the next question
is will this same API
calls work with QlikView server
the QlikView server has a very
structure and APIs than the Qlik Sense
some of the API calls that we can find
here on Qlik Dev actually command to
Qlik Sense on premise and Qlik Sense
but we are completely different on the
one from QlikView server
so the answer would be no you cannot use
it with QlikView server
the next question is can you enable a
for user to manually trigger a load from
using next an extension that's actually
you can program an extension that would
a task to reload the the app or just
reload the app to the capability API
like you would press the reload button
from the data load editor.
However this requires different sets
of rights. If you read it from the
capability API the user that click that
need to have operational license
assigned and also
have rights to modify that app well if
you do it on
as a task then it will need the user
will need to
have sufficient administrative
privileges to run the task
the next question is can you integrate
API with Qlik Sense SaaS and Qlik
Sense on Windows
as I said a bit earlier
some of those API like the capability
are command to Qlik Sense on Windows
and Qlik Sense says more than 90 percent
of the capability API is actually uh the
same in quick Sense
SaaS and Qlik Sense on Windows as well
Qlik Sense engine API it is on our pc
is exactly the same also there are some
a few exceptions that
do not work in SaaS or do not work in
Windows but they are mostly the same
and then when it comes to the rest API
they are completely different
than the one in Windows because that's
different services that are running in
when it comes to everything that is
the next question is what is the
recommended API to call to trigger
task when it comes to trigger reload
the the best way is to do it with with
the rest API
whether reloads API is that you can
description just shown earlier here
so that's the easiest way to trigger a
task and the most common one also
okay the next question
is does accessing a mashup require a
license for the user
any user that would access a mashup will
need a license
if the user is only visualizing the
he will only need an analyzer license
if the user is actually doing some
change to the app through the master
then he would need a professional
that makes Sense okay Damien we have
time for one last question
the last question is
is it possible to export an app as a qvf
file with the API you can export an app
with the rest
API you would go in this case to apps
and you can search for export
here export a specific app and you have
on how to export it here
so we're done with this session for
today thank you everybody for attending
okay great thank you everyone we hope
you enjoyed this session
thanks to Damien for presenting we
appreciate getting experts like Damien
to share with us
here's our legal disclaimer and thank
you once again
have a great rest of your day