QIX

v12.1394.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.

GenericBookmark

GenericBookmarkApply()

Applies a bookmark.

The operation is successful if **qSuccess** is set to true.

Returns

qSuccess
boolean

No description

Errors

No description

const result = await genericBookmark.apply({});
// console.log(result);
true

GenericBookmarkApplyPatches(qPatches)

Applies a patch to the properties of an object. Allows an update to some of the properties. It should not be possible to patch "/qInfo/qId", and it will be forbidden in the near future.

Applying a patch takes less time than resetting all the properties.

Parameters

qPatches

Array of patches.

Returns

Results for GenericBookmark.ApplyPatches
object

No description

Errors

No description

const result = await genericBookmark.applyPatches({
  "qPatches": [
    {
      "qOp": "value",
      "qPath": "value",
      "qValue": "value"
    }
  ]
});
// console.log(result);
undefined

GenericBookmarkApprove()

Adds the generic bookmark to the list of approved objects

This operation is possible only in Qlik Sense Enterprise.

Returns

Results for GenericBookmark.Approve
object

No description

Errors

No description

const result = await genericBookmark.approve({});
// console.log(result);
undefined

GenericBookmarkGetFieldValues(qField, qGetExcludedValues, qDataPage)

Retrieves the values of a field.

Fieldvalue

NameDescriptionType
qTextText related to the field value.String
qIsNumericIs set to true if the value is a numeric.
Default is false.
Boolean
qNumberNumeric value of the field.
This parameter is displayed if qIsNumeric is set to true.
Double

Parameters

qField
string

Name of the field.

qGetExcludedValues
boolean

If set to true, only excluded values are returned.

qDataPage

Range of returned values.

Returns

qFieldValues

No description

Errors

No description

const result = await genericBookmark.getFieldValues({
  "qField": "value",
  "qGetExcludedValues": true,
  "qDataPage": {
    "qStartIndex": 1,
    "qEndIndex": 1
  }
});
// console.log(result);
[
  {
    "qText": "value",
    "qIsNumeric": true,
    "qNumber": 1
  }
]

GenericBookmarkGetInfo()

Returns:

  • The type of the object.
  • The identifier of the object.

Returns

qInfo

No description

Errors

No description

const result = await genericBookmark.getInfo({});
// console.log(result);
{
  "qId": "value",
  "qType": "value"
}

GenericBookmarkGetLayout()

Evaluates an object and displays its properties including the dynamic properties. If the member delta is set to true in the request object, only the delta is evaluated.

Returns

qLayout

No description

Errors

No description

const result = await genericBookmark.getLayout({});
// console.log(result);
{
  "qInfo": {
    "qId": "value",
    "qType": "value"
  },
  "qMeta": {
    "qName": "value"
  },
  "qBookmark": {
    "qStateData": [
      {
        "qStateName": "value",
        "qFieldItems": [
          {
            "qDef": {
              "qName": "value",
              "qType": "value"
            },
            "qLocked": true,
            "qSelectInfo": {
              "qTextSearch": "value",
              "qRangeLo": 1,
              "qRangeHi": 1,
              "qNumberFormat": {
                "qType": "value",
                "qnDec": 1,
                "qUseThou": 1,
                "qFmt": "value",
                "qDec": "value",
                "qThou": "value"
              },
              "qRangeInfo": [
                {
                  "qRangeLo": 1,
                  "qRangeHi": 1,
                  "qMeasure": "value"
                }
              ],
              "qSoftLock": true,
              "qContinuousRangeInfo": [
                {
                  "qMin": 1,
                  "qMax": 1,
                  "qMinInclEq": true,
                  "qMaxInclEq": true
                }
              ],
              "qSelectFieldSearch": true
            },
            "qValues": [
              {
                "qText": "value",
                "qIsNumeric": true,
                "qNumber": 1
              }
            ],
            "qExcludedValues": [
              {
                "qText": "value",
                "qIsNumeric": true,
                "qNumber": 1
              }
            ],
            "qAndMode": true,
            "qOneAndOnlyOne": true
          }
        ]
      }
    ],
    "qUtcModifyTime": 1,
    "qVariableItems": [
      {
        "qName": "value",
        "qValue": {
          "qText": "value",
          "qIsNumeric": true,
          "qNumber": 1
        }
      }
    ],
    "qPatches": [
      {
        "qInfo": {
          "qId": "value",
          "qType": "value"
        },
        "qPatches": [
          {
            "qOp": "value",
            "qPath": "value",
            "qValue": "value"
          }
        ],
        "qChildren": [
          null
        ]
      }
    ]
  },
  "qFieldInfos": [
    {
      "qFieldName": "value",
      "qValuesCount": 1,
      "qExcludedValuesCount": 1
    }
  ]
}

GenericBookmarkGetProperties()

Shows the properties of an object.

If the member delta is set to true in the request object, only the delta is retrieved.
The following is always returned in the output:

Returns

qProp

No description

Errors

No description

const result = await genericBookmark.getProperties({});
// console.log(result);
{
  "qInfo": {
    "qId": "value",
    "qType": "value"
  },
  "qMetaDef": {},
  "qIncludeVariables": true,
  "qDistinctValues": true
}

GenericBookmarkPublish()

Publishes a bookmark.

This operation is not applicable for Qlik Sense Desktop.

Returns

Results for GenericBookmark.Publish
object

No description

Errors

No description

const result = await genericBookmark.publish({});
// console.log(result);
undefined

GenericBookmarkSetProperties(qProp)

Sets some properties for a bookmark.

Parameters

qProp

Information about the bookmark.

Returns

Results for GenericBookmark.SetProperties
object

No description

Errors

No description

const result = await genericBookmark.setProperties({
  "qProp": {
    "qInfo": {
      "qId": "value",
      "qType": "value"
    },
    "qMetaDef": {},
    "qIncludeVariables": true,
    "qDistinctValues": true
  }
});
// console.log(result);
undefined

GenericBookmarkUnApprove()

Removes the generic bookmark from the list of approved objects

This operation is possible only in Qlik Sense Enterprise.

Returns

Results for GenericBookmark.UnApprove
object

No description

Errors

No description

const result = await genericBookmark.unApprove({});
// console.log(result);
undefined

GenericBookmarkUnPublish()

Unpublishes a bookmark.

This operation is not applicable for Qlik Sense Desktop.

Returns

Results for GenericBookmark.UnPublish
object

No description

Errors

No description

const result = await genericBookmark.unPublish({});
// console.log(result);
undefined
Was this page helpful?