Get to know the Engine API with Qixplorer

[Ouadie]

For those of us who want to go beyond the out-of-the-box capabilities of Qlik Sense and want to leverage the full potential of the platform to create complex visualizations or satisfy custom development needs, understanding the Engine API is fundamental to taking advantage of what Qlik Sense hides under the hood.

The Qlik Engine API is a websocket protocol that uses JSON RPC 2.0 to communicate between the Qlik Associative Engine and clients. It works independently of any platform and programming language as long as it supports WebSockets and can parse JSON.

A great place to get your feet wet with trying out the Engine API is through Qixplorer (You might remember this as the Engine API Explorer on Qlik Managed). The tool that you can access at https://qixplorer.qlik.dev features a newly reimagined user interface and additional updates for a better experience.

Right off the bat, you can see that the format is divided into 4 main sections:

• Left: This is where you configure your connection to the tenant, pick the app, and browse through methods made available for your selected object.
• Middle: This is where you can see your requests and responses
• Bottom: This area is where you can construct and modify your requests and execute them
• Right: This is a neat feature that shows you inline documentation as you explore API methods

Other settings include a Light/Dark mode toggle at the top left, as well as a Layout toggle that lets you switch between the Original Layout (side by side request and response sections) or, my favorite, the Chat Layout.

How to use Qixplorer?

The first thing you would need to create a new connection to your Qlik Cloud tenant is a Web Integration ID. You can grab that by going to your tenant’s Management Console, under Web, Create a new integration and add https://qixplorer.qlik.dev as an origin.

Once you have the generated ID in hand, create a new connection on Qixplorer as shown below:

The next step is to choose the app you want to connect to from the second dropdown.

Once you select that, you will see that a first request and response have been made automatically. That’s the “OpenDoc” method, it is responsible for opening an app. More about it here.

Notice that a few items are now highlighted on the Left panel that you can start using - including the Doc and Global classes that can be expanded to reveal all the methods you can execute. You can also use the pre-defined Macros to list sheets, dimensions etc...

⚠️Before we continue, keep in mind that when using Qixplorer, you are performing changes directly on your apps, so when executing API methods to update or delete within Qixplorer, it will affect the objects in your apps.

Examples of using Qixplorer

• Using Macros to list sheets in our app

From the Macros dropdown, click on “ListSheets”.

Notice that the Request section at the bottom has our generated JSON with the methods needed to list sheets.
Click on Execute and view the JSON returned in the Response section.

P.S: notice that two separate requests have been made by our Macro: CreateSessionObject and GetLayout.

• Using a method from Global

Let’s create an App in our tenant directly from Qixplorer.

First, select the “CreateApp” method from the Global dropdown.

Notice that the right panel has been populated with the inline documentation for our method. This makes it really convenient to view the definition and parameters at a glance.

Within the Request section that now contains the editable JSON, enter a name for the app we’re creating in the “qAppName” property.

Our request and response look like this:

{
  "handle": -1,
  "method": "CreateApp",
  "params": {
    "qLocale": "",
    "qLocalizedScriptMainSection": "",
    "qAppName": "test-qixplorer"
  }
}

You can check your tenant to view the newly created app:

• Using a method from Doc and GenericObject

Let’s retrieve the calculated data from a Table object in our app.

First, we need to get the object. Under ”Doc”, scroll down to GetObject and change the “qId” property to our Table's object id.

Now that we got the object, you can go to ”GenericObject”, then “Select Object” and click on table.

Next, scroll down to the “GetHyperCubeData” method under “GenericObject” and modify the JSON as follows to set the qHeight (number of rows to retrieve) and qWidth (number of columns)

{
  "handle": 2,
  "method": "GetHyperCubeData",
  "params": {
    "qPages": [
      {
        "qHeight": 1000,
        "qWidth": 5,
        "qTop": 0,
        "qLeft": 0
      }
    ],
    "qPath": "/qHyperCubeDef"
  }
}

Click on execute and examine the response:

The Engine API is without a doubt very powerful as it exposes methods that can be used to tap directly into the associative engine and manipulate complex data structures. Having a tool like Qixplorer is a great way to try out the API and learn more about all the methods available in a single place.

Let me know in the comments how you use Qixplorer on you end!