STT - Leveraging APIs on Qlik Sense Enterprise SaaS

[Troy_Raney]

This session covers:

• What APIs can do for you
• Using API keys
• Integrating objects in apps
• What to do when things go wrong

Chapters:

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

Resources:

Qlik Dev
How to Create a Mashup
How to Embed a chart in an iFrame
Qlik Branch

For more information:

Leveraging APIs on Qlik Sense Enterprise SaaS - Article

Video transcript:

Hi everyone. My name is Damien. I'm

working as a senior technical support

engineer.

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

talk

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

different tasks

or call them from an external program. So

you can

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

required?

So, you don't need a special license to

use APIs.

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

professional

license assigned to the user because

only professional

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?

Of course.

So, we are first going to Qlik Dev

and use one of the examples that is

available.

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

create an

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

gonna show

my Qlik Sense hub and verify that I

only have

one app “Consumer Sales” in my tenant.

Okay and now I'm gonna run the command

to create

the app. So this is just a regular

Windows command prompt?

Yes, that's just a regular Windows

command prompt,

and Qlik CLI has been installed prior

to this.

We are now getting the app id of the app

That just got created.

We can go back to the

hub

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

file

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

create some

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

and

type in ctrl 0 0, it'll auto generate

this

script, which will create dummy data for

testing apps.

That's a great tip Damien!

So now we're

gonna go to the

command prompt again and we are gonna

type

this line. And I need to

copy this app id.

The app has been saved you can go back

to the

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

one.

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

reload it.

That's pretty cool. So three lines of

Code; you have an app with script and

it's

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

us?

Basically, anything that can be performed

in the console

can also be confirmed with the rest APIs,

which are for administrative tasks.

We have the JavaScript API which is for

any kind of

front-end action: which would be applying a

selection;

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

through WebSockets.

Can be used to do any kind of action

that

is done inside an app. Then we have the

libraries.

The libraries are used to facilitate the

use of the APIs.

Enimga.js is to communicate with

the Qlik engine

API through JavaScript instead of

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

extensions

and mashups.

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

on

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

here.

You can see everything that

is actually a public API currently.

And the JavaScript API and another

RPC API.

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

governance section.

There is no deprecation period for

Experimental.

“Stable” - you have a six-month deprecation

period and “locked” have a 12-month

deprecation period.

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

API.

What other sort of setup is

required before you can actually start

using APIs?

In order to use the API, you must take

into consideration

how you authenticate to the API and also

do some initial

setup for the authentication part. You

can

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

program that

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

interactive authentication.

And it's also good to note that

anonymous users are not supported.

In Qlik Sense SaaS, you will have to

authenticate

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

to it.

Then regarding the initial setup, we have

the web integration ID

and content security policy which are

used to

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

website?

So I'm gonna show how to embed Qlik

Sense

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

security policy.

In this case, I will be running my iFrame

on my IIS server which is installed on

my server here, which is called 
“qlik.server2.domain.local.”

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

security policy.

In this case, I'm also using the 
qlik.server2.domain.local and I will select

frame ancestors.

What is “frame ancestors” specifically or

why did you add that?

“Frame ancestors” means the parent

Website.

In here in the origin I've put my parent

website

and I will be allowed to embed in an

iFrame

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

on Google.

Like just typing “Qlik Cloud Services

iFrame.”

What I'm gonna do is just copy all of

this.

So this is basically a script that will

allow you to embed a Qlik object into

an iFrame?

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

then just

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

purpose.

“Consumer Sales” so it's not imported by

default in a Qlik Sense

Cloud environment but it can be

downloaded

from demos.qlik.com.

We need to go and fetch an actual object

that

exists.

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

this object.

You can just click on “copy” and we're

gonna replace this whole block

here with iFrame code that we've just

copied.

Then we can just save this file. And I'm

gonna place

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

your

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

sessions have

some specific security settings that

would make it look different from an

actual session.

And this could be an alternative

to running the application as a

different user because you're just

creating

a new user to run the application. Great

tip!

That's correct. I'm now going to type the

name of my IIS server. All right.

So now

you're visiting that page you created.

Yes. I'm getting redirected now to my

identity provider which is Auth Zero in

this case.

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.
Very cool.

So what do you do when things don't go

perfectly as expected? How would you go

about troubleshooting

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

trace tool.

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

enable them.

Basically you would need to enable them

Here.

Then you set a maximum token expiration

in this and then you can also set a

number of active API keys per user. So

that

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

because when

an API key expired you would need to

renew it.

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

code.

Which would make it much more easier

because

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

that

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

code;

or if you're just passing the wrong

argument.

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

remember

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

Tools.

And how did you open the browser

developer tools?

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

have here.

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

example, expiry.

That's great seeing the

demonstration that the APIs are really

just performing the same actions as the

console.

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

wrong

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

API key.

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.

But with

a wrong format and that would give you

this kind of error.

Error 400.

The next example,

that is embedding into a mashup

and also how to troubleshoot when it

comes to

mashup. For this example, I'm gonna

use this sample that can also be found

from the

support knowledge base. And gonna copy

this code.

I would need to create two files this

Time.

What tool do you use to create those

mashup files?

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

my actual

tenant name.

Is there anything else that

needs to be updated in this file?

Not in this file. The second file that we

are going to create is a JavaScript file.

Just gonna copy this whole code. Create a

new file.

Paste it here. I'm just gonna save it as

“helpdesk.js”

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?

This mashup

will just show one object in

a dev element and can add a few more

actions.

And see what to troubleshoot when it

goes wrong.

First of all, I'm going to replace your

tenant by my tenant name.

Then I'm going to update the web

integration id.

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

“Consumer Sales.”

So this time we can pick up this

colorful

chart. Go in “share” and “embed”

but this time we will just need to copy

this

object id here. And paste it

here and then update the app id.

The easiest way is just to copy it from the

URL here.

Then just save the file. And now we are

gonna

copy those two files that we just

created to our IIS

web server.

So I'm just gonna reuse that same

session and

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

Group”?

That's correct. And I've also moved

around the object and

resized so that it looks a little bit

nicer.

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

number 4.

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

succeed.

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

were using

“app.bookmark.apply” which 
is part of the capability

API.

I'm now gonna go to the help site. The

capability API

is actually almost the same in Qlik

Sense for Windows and

Qlik Sense for SaaS. And on

help.qlik.com

you also have the same documentation on

qlik.dev.

You have to pass a bookmark id. So the

bookmark id here

which should look in this example like

this.

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

here

this method with “apply bookmark”

and in the parameter. Here we see the

actual

bookmark id. So we can copy the bookmark

id from here;

and just put it in our code here. Just

save. Copy

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

bookmark got

applied with the two selection.

The last

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

your

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

through.

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

completion;

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.

Just

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

network tab

in the browser developer tool.

So what

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

Community.

On the Qlik Branch slack channel.

There's documentation on qlik.dev and

help.Qlik.com.

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

On24 console.

Damien, which question would you like to

address first?

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

data.

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

Javascript API or through the errors API

more documentation can go basically

found on Qlik.dev on how to

to do that well actually for the rest

APIs

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

Javascript APIs androids

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

function

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

task

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

it

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

different

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

SaaS

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

reload button

for user to manually trigger a load from

an app

using next an extension that's actually

possible

you can program an extension that would

call either

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

button will

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

the same

API with Qlik Sense SaaS and Qlik

Sense on Windows

as I said a bit earlier

some of those API like the capability

API

are command to Qlik Sense on Windows

and Qlik Sense says more than 90 percent

of what

of the capability API is actually uh the

same in quick Sense

SaaS and Qlik Sense on Windows as well

as

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

those outcome

different services that are running in

the background

when it comes to everything that is

administrative

the next question is what is the

recommended API to call to trigger

reload

task when it comes to trigger reload

tasks

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

object then

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

license

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

the documentation

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

[Carl_Hunter]

Thanks guys, really good webinar.

I have a question - how do you see SaaS working for a QAP like experience? i.e. creating mashups and distributing to anonomous users?

[Troy_Raney]

Hi @Carl_Hunter ,

Thanks. Currently anonymous users are not supported. I wish I could say that they will be in the future, but I can't say that.

Best regards,
Troy

[Carl_Hunter]

Hi @Troy_Raney, thanks for the response. I guess my  follow-up question is, how do we see a QAP like experience working with SaaS, or, will it simply not, or, will it require users to be authenticated via whatever IDP first? 

[Damien_V]

Hello @Carl_Hunter 

I can't say too much about the roadmap, as plans could change.

In the current situation, each user needs to be authenticated, and as we do not have any core-based license or capacity analyzer license for Qlik Sense SaaS yet, you will need to purchase an analyzer license for each person viewing the site.

Best regards,

Damien

[Jeffrey_Goldberg]

Hi @Carl_Hunter ,

Today, you can achieve a QAP-like experience by pointing your mashups to read from a Qlik Sense Enterprise SaaS instance instead of a windows instance. There are some differences to be aware of, including but not limited to:

1. Authentication is different as you have probably experienced. We just released JWT authorization capabilities in Qlik Sense Enterprise SaaS which works very similarly to the windows JWT virtual proxy. You can learn more about setting it up here: https://qlik.dev/tutorials/create-signed-tokens-for-jwt-authorization.
You will need to contact your account manager to request this functionality.

2. Another key difference is how inclusion (fka whitelist) lists work in SaaS compared to Windows. In SaaS, web integration IDs enable the cross site capabilities most mashups require. These replace the inclusion list added to the virtual proxy. You can learn more about web integrations here: https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/mc-adminster-web-i...

3. Content Security Policy (CSP) is needed if you are embedding Qlik using iframes. You can learn more about CSP here: https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/mc-administer-cont...this does not exist in Qlik Sense Enterprise on Windows.

Regarding your question on anonymous:

Currently, anonymous usage is not supported in Qlik Sense Enterprise SaaS. It is a requested capability and we are investigating, analyzing, and designing a mechanism to offer it. As stated earlier in the thread, no timeframes available for when.

Hope this helps.

jg

[Carl_Hunter]

Hi @Jeffrey_Goldberg , brilliant, thanks for the detailed answer, I'm sure others will find it incredibly useful too 👍