QIX

v12.1368.0

The JSON-RPC API over websocket that enables you to interact with the Qlik Associative Engine.

The QIX API is the primary API used for working with Qlik apps. It's based on the WebSocket protocol and requires some specific parameters to work correctly as seen below.

WebSockets

When you want to use the API, any websocket client implementation that follows the RFC specification should be supported. The URL format is:

wss://your-tenant.us.qlikcloud.com/app/<app id>

Browser example:

const websocket = new WebSocket('wss://your-tenant.us.qlikcloud.com/app/123e4567-e89b-12d3-a456-426655440000');

Headers

In a non-browser environment, most websocket client implementations support to add headers.

Use header Authorization: Bearer <token> with API key for authentication.

Session sharing

When using the QIX API you build up a state in what's called a session. A session is based on a tenant, a user, and the app. When opening a new websocket you'd either get a new unique session, or get attached to an existing session. When sharing a session, the state (like selections), is shared between all websocket connections.

The conditions for sharing a session is:

  • The websocket URL needs to be identical (tenant URL and app id)
  • The user needs to be the same:
    • in a browser environment the same user needs to be signed in
    • in a non-browser environment an API key from the same user and tenant needs to be used

JSON-RPC protocol

The QIX API leverages the JSON-RPC protocol. It implements a superset of this specification. All requests sent from the client should contain the following properties:

{
  // Protocol descriptor:
  "jsonrpc": "2.0",
  // Session-unique numeric id, referred to in the response
  // to connect the request and response:
  "id": 6,
  // The handle for the object to interact with:
  "handle": 2,
  // The object type of the handle above decides
  // which API methods you may invoke:
  "method": "ApiMethodName",
  // Parameters for the invoked API method:
  "params": {}
}

Request and response

Here is an example request/response pair. Note that there is only one static handle in the QIX API, and that's -1. This handle refers to the Global API.

In this example request, an app is opened using OpenDoc. If successful, the response contains a reference to the app handle, which can be used to do further requests towards the Doc (app) API, and so forth.

{
  "jsonrpc": "2.0",
  "id": 1,
  "handle": -1,
  "method": "OpenDoc",
  "params": {
    "qDocName": "<app id>"
  }
}

If that app exist, the response would look similar to this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "qReturn": {
      "qType": "Doc",
      "qHandle": 1,
      "qGenericId": "<app id>"
    }
  },
  "change": [1]
}

Note that qHandle contains the handle that might be used to make additional requests to invoke API methods towards the app. A property called change is also received on the response, an array that can be sent by QIX Engine on any responses and contains all open handles in your session that may have been invalidated and you should refetch data to ensure your application in a valid state.

Session apps

Session apps are non-persisted Qlik Sense apps created on-the-fly in server memory by the Qlik Associative Engine. You have to define a load script and trigger a data reload before any data model is accessible for each user session. Similarly, if you create a session app from an existing app, you have to trigger a reload after retrieving objects from the template app.

Session apps are attached to the active Qlik Associative Engine session. When a session ends, for example, by the user logging out, the session app is terminated and all related resources are released from server memory. Standard Qlik security rules ensure that only authenticated users can access data and visualizations from a session app.

WebSocket URL for session apps

The WebSocket URL for creating a session app has the following format:

wss://my-tenant.us.qlikcloud.com/app/SessionApp_{appId}

You must append a unique app ID to SessionApp_ in the path. The app ID can be a code-generated random number.

To create a session app from an app, you must add the template app ID as a query parameter to the URL:

wss://my-tenant.us.qlikcloud.com/app/SessionApp_{appId}?from={templateAppId}

Error Handling

When something happens unexpectedly, the WebSocket may be closed with an error code and message. The error code will be a 4-digit number and the message may or may not be empty. The code below should be used for monitoring this.

ws.on("close", (code, message) => {
    console.log(code);
    console.log(String(message));
});
4204
{"code":"QEP-104","traceId":"491a33e544de8dda40a9fc9b0cb53216"}

The following is a list of error codes and their causes:

  • 4202 - the WebSocket request appears to be malformed
  • 4203 - the request could not be fulfilled because of a permissions issue
  • 4204 - the request failed because something could not be found, this may be because the app id in the URL is wrong or the app has been deleted
  • 4205 - the request could not be fulfilled because the system is busy, consider sending the request again later

API references

For the API references, see the different classes listed in the left-side menu.

Variable

VariableForceContent(qs, qd)

deprecatedUse GenericVariable::SetProperties method instead

Sets the value of a dual variable overriding any input constraints.

Parameters

qs
string

String representation of a dual value. Set this parameter to "", if the string representation is to be Null.

qd
number

Numeric representation of a dual value.

Returns

Results for Variable.ForceContent
object

No description

Errors

No description

const result = await variable.forceContent({
  "qs": "value",
  "qd": 1
});
// console.log(result);
undefined

VariableGetContent()

deprecatedUse GenericVariable::GetProperties method instead

Returns the calculated value of a variable.

Returns

qContent

No description

Errors

No description

const result = await variable.getContent({});
// console.log(result);
{
  "qString": "value",
  "qIsNum": true
}

VariableGetNxProperties()

deprecatedUse GetProperties method instead

Gets the properties of a variable.

Returns

qProperties

No description

Errors

No description

const result = await variable.getNxProperties({});
// console.log(result);
{
  "qName": "value",
  "qNumberPresentation": {
    "qType": "value",
    "qnDec": 1,
    "qUseThou": 1,
    "qFmt": "value",
    "qDec": "value",
    "qThou": "value"
  },
  "qIncludeInBookmark": true,
  "qUsePredefListedValues": true,
  "qPreDefinedList": [
    "value"
  ]
}

VariableGetRawContent()

deprecatedUse GenericVariable::GetProperties method instead

Returns the raw value of a variable.

Returns

qReturn
string

No description

Errors

No description

const result = await variable.getRawContent({});
// console.log(result);
"value"

VariableSetContent(qContent, qUpdateMRU)

deprecatedUse GenericVariable::SetProperties method instead

Sets a value to a variable.

Parameters

qContent
string

Value of the variable.

qUpdateMRU
boolean

If set to true, the value is added to the Most Recently Used (MRU) list.

Returns

qReturn
boolean

No description

Errors

No description

const result = await variable.setContent({
  "qContent": "value",
  "qUpdateMRU": true
});
// console.log(result);
true

VariableSetNxProperties(qProperties)

deprecatedUse SetProperties method instead

Sets some properties to a variable.

Parameters

qProperties

Information about the properties of the variable

Returns

Results for Variable.SetNxProperties
object

No description

Errors

No description

const result = await variable.setNxProperties({
  "qProperties": {
    "qName": "value",
    "qNumberPresentation": {
      "qType": "value",
      "qnDec": 1,
      "qUseThou": 1,
      "qFmt": "value",
      "qDec": "value",
      "qThou": "value"
    },
    "qIncludeInBookmark": true,
    "qUsePredefListedValues": true,
    "qPreDefinedList": [
      "value"
    ]
  }
});
// console.log(result);
undefined
Was this page helpful?