QIX

v12.1532.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
  • 4230 - the request could not be fulfilled because there are too many open apps in your organization
  • 4240 - the request could not be fulfilled because there are no available engines

API references

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

Field

FieldClear()

Clears the selections in a specific field.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.clear({});
true

FieldClearAllButThis(qSoftLock?)

Maintains the selections in the current field while clearing the selections in the other fields.

Parameters

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.clearAllButThis({
  "qSoftLock": true
});
true

FieldGetAndMode()

Returns the AND mode status of a field.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.getAndMode({});
true

FieldGetCardinal()

Retrieves the number of distinct values in a field.

Returns

qReturn
optional
integer

No description

Errors

No description

const result = await field.getCardinal({});
1

FieldGetNxProperties()

Gets the properties of a field.

The property _OneAndOnlyOne_ is set to true if one and only value has been selected in the field prior setting the property.

Returns

qProperties

No description

Errors

No description

const result = await field.getNxProperties({});
{
  "qOneAndOnlyOne": true
}

FieldLock()

Locks all selected values of a specific field.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.lock({});
true

FieldLowLevelSelect(qValues, qToggleMode, qSoftLock?)

Selects some values in a field, by entering the element numbers related to the values to select.

Parameters

qValues
Array<integer<int32>>

Indexes (or element numbers) of the values to select.

qToggleMode
boolean

Set to true to keep any selections present in the list object. If this parameter is set to false, selections made before accepting the list object search become alternative.

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.lowLevelSelect({
  "qValues": [
    1
  ],
  "qToggleMode": true,
  "qSoftLock": true
});
true

FieldSelect(qMatch, qSoftLock?, qExcludedValuesMode?)

Selects field values matching a search string.

Parameters

qMatch
string

String to search for. Can contain wild cards or numeric search criteria.

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

qExcludedValuesMode
optional
integer

Include excluded values in search.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.select({
  "qMatch": "value",
  "qSoftLock": true,
  "qExcludedValuesMode": 1
});
true

FieldSelectAll(qSoftLock?)

Selects all values of a field. Excluded values are also selected.

Parameters

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.selectAll({
  "qSoftLock": true
});
true

FieldSelectAlternative(qSoftLock?)

Selects all alternatives values in a specific field.

In a field that contains at least one selected value, the values that are neither selected nor excluded are alternatives values.

Parameters

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.selectAlternative({
  "qSoftLock": true
});
true

FieldSelectExcluded(qSoftLock?)

Inverts the current selections.

Parameters

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.selectExcluded({
  "qSoftLock": true
});
true

FieldSelectPossible(qSoftLock?)

Selects all possible values in a specific field.

Parameters

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.selectPossible({
  "qSoftLock": true
});
true

FieldSelectValues(qFieldValues, qToggleMode?, qSoftLock?)

Selects some values in a field, by entering the values to select.

Parameters

qFieldValues

List of the values to select.

qToggleMode
optional
boolean

The default value is false.

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.selectValues({
  "qFieldValues": [
    {
      "qText": "value",
      "qIsNumeric": true,
      "qNumber": 1
    }
  ],
  "qToggleMode": true,
  "qSoftLock": true
});
true

FieldSetAndMode(qAndMode)

Sets a field in the AND mode.

Parameters

qAndMode
boolean

Specifies if the AND mode applies to the field. Set this parameter to true to enter the AND mode.

Returns

Results for Field.SetAndMode
optional
object

No description

Errors

No description

const result = await field.setAndMode({
  "qAndMode": true
});
undefined

FieldSetNxProperties(qProperties)

Sets some properties to a field.

Parameters

qProperties

Information about the properties of the field.

Returns

Results for Field.SetNxProperties
optional
object

No description

Errors

No description

const result = await field.setNxProperties({
  "qProperties": {
    "qOneAndOnlyOne": true
  }
});
undefined

FieldToggleSelect(qMatch, qSoftLock?, qExcludedValuesMode?)

Toggle selects field values matching a search string.

Parameters

qMatch
string

String to search for. Can contain wild cards or numeric search criteria.

qSoftLock
optional
boolean

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false.

qExcludedValuesMode
optional
integer

Include excluded values in search.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.toggleSelect({
  "qMatch": "value",
  "qSoftLock": true,
  "qExcludedValuesMode": 1
});
true

FieldUnlock()

Unlocks all selected values of a specific field if the target (or handle ) is a field.

Returns

qReturn
optional
boolean

No description

Errors

No description

const result = await field.unlock({});
true
Was this page helpful?