Qlik Community

Qlik Design Blog

All about product and Qlik solutions: scripting, data modeling, visual design, extensions, best practices, etc.

Employee
Employee

Integrating Qlik Sense into your Web App

You want to integrate Qlik Sense into your web app, but you're not sure where to begin. Don't worry, I've got you covered. We'll take a look at different ways to integrate Qlik Sense into your web app, which one to choose, and how to get started with each.

What should I use?

App Integration API or Single Integration API

Capability APIs

enigma.js

Use the App Integration API or Single Integration API if you just need to embed a few apps, sheets, or objects into your web app

Use the Capability APIs to embed Qlik Sense visualizations into your web app, create Qlik Sense visualizations on the fly, get data from fields, make selections, create objects, and more, with an API that attempts to simplify the process of communicating with the Qlik Engine JSON API.

Use enigma.js if you are a developer comfortable with referencing the Qlik Engine JSON API, you want as little between you and the Qlik Engine as possible, and you do not require embedding Qlik Sense visualizations into your web app. Requires a higher degree of skill than either the Integration APIs or the Capability APIs.

 

Using the App Integration API and Single Integration API

Using either of the Integration APIs is very simple, and the only prerequisite knowledge required is how to create an iFrame element in HTML. Each of the integration APIs allow some options to be supplied via the URL. Use the documentation for each as a reference to these options. NOTE – The client will have to be authenticated if authentication is required on the virtual proxy used for the Qlik Sense App or objects that will be embedded.

https://help.qlik.com/en-US/sense-developer/Subsystems/APIs/Content/Sense_ClientAPIs/app-integration...

https://help.qlik.com/en-US/sense-developer/Subsystems/APIs/Content/Sense_ClientAPIs/single-integrat...

 

Using the Capability APIs

Prerequisites

In order to use the Capability APIs you should have some knowledge of HTML, CSS, and JavaScript. Some knowledge of AngularJS and RequireJS is beneficial, but not necessarily and requirement.  It would be beneficial to know how to use your browser’s dev-tools, including knowing how to inspect messages sent and received across a websocket. Since the Capability APIs use the Qlik Engine JSON API, some knowledge of that would be good, but not necessarily required. It would also be beneficial to understand Qlik concepts such as generic objects and hypercubes.

Resources:

https://angularjs.org/

https://requirejs.org/

https://help.qlik.com/en-US/sense-developer/APIs/EngineAPI/index.html

https://help.qlik.com/en-US/sense-developer/June2019/Subsystems/Platform/Content/Sense_PlatformOverv...

Considerations

The Capability APIs use AngularJS and RequireJS, which are both global libraries which have the potential to interact with the rest of your web app. jQuery is also loaded with the Capability APIs which means if you another version of jQuery in your web app it will potentially be overwritten by the copy of jQuery loaded by the Capability APIs. There’s also some CSS that must be loaded to use the Capability APIs which has the potential to overwrite your web apps own styles. These things should be considered before using the Capability APIs. If any of these potential conflicts are an issue, consider using the App Integration API or Single Integration API, which both use iFrames to embed Qlik Sense content onto your page, which is isolated from affecting the rest of your web app. You could also consider creating a mashup with the Capability APIs and embedding the mashup in your web app in an iFrame to isolate it from the rest of your web app.

Getting Started

The document Getting started building mashups will guide you through setting up a mashup using the Capability APIs. It assumes that you are using Qlik Sense Desktop and that you want to use Qlik Sense to host your mashup files. If you instead want to use Qlik Sense Enterprise to host the mashup, then create the files the same way, but use the import extension capability of the QMC to upload your files. You can also simply host your mashup files outside of Qlik Sense entirely but be sure to add the origin to the whitelist of the virtual proxy in the QMC.

Authentication

Does the virtual proxy you are using require authentication? Then something to be aware of when using the Capability APIs is not only will Qlik Sense check for authentication when you connect to an app, it will also check for authentication when requesting files from behind the virtual proxy. If you’re hosting your mashup within Qlik Sense behind a virtual proxy that requires authentication then as soon as you try to load the mashup, Qlik Sense will check for authentication. Qlik Sense will also check for authentication when loading the necessary Capability API assets (require.js and related assets, CSS file) from behind a virtual proxy that requires authentication.

That means that you need to deal with authentication before you can successfully load any assets from behind the virtual proxy. The document Authentication Solutions is the place to start.

Usage

Once your mashup is setup you’ll have access to the qlik namespace. The qlik namespace provides all of the methods of the Root API. From here, you can, for example, use the openApp method to connect to a Qlik Sense app and get an app object with which you can use all of the methods of the App API. That is the general pattern of the Capability APIs. For example, the Visualization API get and create methods both return an instance of the QVisualization class which has methods related to modifying and displaying the visualization returned.

 

enigma.js

Prerequisites

In order to use enigma.js, you should be comfortable JavaScript, promises, and websockets. You will need Node.js.  Since enigma.js can be used anywhere that JavaScript can be executed, further prerequisites depend on how it will be used. enigma.js implements the methods of the Qlik Engine JSON API, so you should be comfortable referencing the Qlik Engine JSON API. Further knowledge about Qlik, including such topics as messages sent from the Qlik Proxy Service to clients, is helpful. Generally, you should be a developer that is very comfortable with JavaScript, referencing API materials, and using open source libraries. You should also be familiar with Qlik concepts such as generic objects and hypercubes.

References:

https://help.qlik.com/en-US/sense-developer/APIs/EngineAPI/index.html

https://help.qlik.com/en-US/sense-developer/Subsystems/ProxyServiceAPI/Content/Sense_ProxyServiceAPI...

https://help.qlik.com/en-US/sense-developer/June2019/Subsystems/Platform/Content/Sense_PlatformOverv...

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

https://developer.mozilla.org/en-US/docs/Glossary/WebSockets

Considerations

enigma.js enables communication with the Qlik Engine, but it does not enable embedding Qlik Sense charts. What you do with the information received from the Qlik Engine, such as creating visualizations, is entirely up to you.

Getting Started

There is an example for getting started using enigma.js both outside of and within the browser at https://github.com/qlik-oss/enigma.js#getting-started. Generally, using enigma.js either from outside or within the browser is similar. You can check out the examples at https://github.com/qlik-oss/enigma.js/blob/master/examples/README.md#runnable-examples as well as the API documentation at https://github.com/qlik-oss/enigma.js/blob/master/docs/api.md#api-documentation to further help you get started.

Authentication

Like the Capability APIs, enigma.js is not responsible for authentication, as explained at https://github.com/qlik-oss/enigma.js/blob/master/docs/concepts.md#authentication. You can reference the authentication examples at https://github.com/qlik-oss/enigma.js/tree/master/examples/authentication, and explore Authentication Solutions in Qlik Sense. Often, checking if users are authenticated by subscribing to the OnAuthenticationInformation message is helpful. (more information about subscribing to notification messages with enigma.js can be found at https://github.com/qlik-oss/enigma.js/blob/master/docs/api.md#event-notificationname).

Usage

Referencing the Qlik Engine JSON API is essential. For instance, you may need to use the API to find that the CreateSessionObject method returns a GenericObject on which you can use the GetHyperCubeData method to return an array of NxDataPage which includes an array of NxCellRows, with each one having the properties of an NxCell in case you want to create a hypercube, get data from it, and know what format to expect that data in.

You can use other Qlik Sense open source libraries, such as picasso.js and Leonardo UI, to help build your web app. picasso.js is a charting library streamlined for building custom, interactive, and powerful visualizations with Qlik integration in mind, and Leonardo UI is a UI component library which a look and feel similar to Qlik Sense. You can also find other Qlik open source software at https://github.com/qlik-oss.