Qlik Sense API & Enigma.js – Разработка / Development. Документация

enigma.create(config)

Пример:

const enigma = require('enigma.js');
const schema = require('enigma.js/schemas/12.20.0.json');
const WebSocket = require('ws');
const config = {
  schema,
  url: 'ws://localhost:9076/app/engineData',
  createSocket: url => new WebSocket(url),
};
const session = enigma.create(config);

Configuration

This section describes the configuration object that is sent into enigma.create(config).

Пример:

const enigma = require('enigma.js');
const WebSocket = require('ws');
const bluebird = require('bluebird');
const schema = require('enigma.js/schemas/12.20.0.json');

const config = {
  schema,
  url: 'ws://localhost:4848/app/engineData',
  createSocket: url => new WebSocket(url),
  Promise: bluebird,
  suspendOnClose: true,
  mixins: [{ types: ['Global'], init: () => console.log('Mixin ran') }],
  protocol: { delta: false },
};

enigma.create(config).open().then((global) => {
  // global === QIX global interface
  process.exit(0);
});

Mixins

The mixin concept allows you to add or override QIX Engine API functionality. A mixin is basically a JavaScript object describing which types it modifies, and a list of functions for extending and overriding the API for those types.

QIX Engine types like for example GenericObject, Doc, GenericBookmark, are supported but also custom GenericObjecttypes such as barchart, story and myCustomType. An API will get both their generic type as well as custom type mixins applied.

Mixins that are bound to several different types can find the current API type in the genericType or type members. this.type would for instance return GenericObject and this.genericType would return barchart.

See the Mixins examples on how to use it, below is an outline of what the mixin API consists of.

mixin.init(args)

This function will be executed for each generated API.

See below what args contains.

mixin.extend.myNonExistingMethod(param1, param2, ...)

mixin.extend is an object containing methods to extend the generated API with. These method names cannot already exist or enigma.js will throw an error.

mixin.override.someExistingMethod(base, param1, param2, ...)

mixin.override is an object containing methods that overrides existing API methods. These method names needs to exist already* or engima.js will throw an error. Be careful when overriding, you may break expected behaviors in other mixins or your application.

base is a reference to the previous mixin method, can be used to invoke the mixin chain before this mixin method.

Interceptors

Interceptors is a concept similar to mixins, but run on a lower level. The interceptor concept can augment either the requests (i.e. before sent to QIX Engine), or the responses (i.e. after QIX Engine has sent a response).

The interceptor promises runs in parallel to the regular promises used in enigma.js, which means that it can be really useful when you want to normalize behaviors in your application.

See the Interceptor examples on how to use it, below is an outline of what the interceptor API consists of.

Requests

interceptor.onFulfilled(session, request)

This method is invoked when a request is about to be sent to QIX Engine.

session refers to the session executing the interceptor.

request is the JSON-RPC request that will be sent.

Responses

interceptor.onRejected(session, request, error)

This method is invoked when a previous interceptor has rejected the promise, use this to handle for example errors before they are sent into mixins.

session refers to the session executing the interceptor.

request is the JSON-RPC request resulting in this error. You may use .retry() to retry sending it to QIX Engine.

error is whatever the previous interceptor rejected with.

interceptor.onFulfilled(session, request, result)

This method is invoked when a promise has been successfully resolved, use this to modify the result or reject the promise chain before it is sent to mixins.

session refers to the session executing the interceptor.

request is the JSON-RPC request resulting in this response.

result is whatever the previous interceptor resolved with.

Session API

You retrieve a session by calling enigma.create(config).

session.config

The session.config property contains a reference to the configuration object used by the session. Default values for optional parameters will be filled in.

session.open()

Returns a promise.

Establishes the websocket against the configured URL. Eventually resolved with the QIX global interface when the connection has been established.

Пример:

session.open().then((global) => {
  global.openDoc('my-document.qvf');
});

session.close()

Returns a promise.

Closes the websocket and cleans up internal caches, also triggers the closed event on all generated APIs. Eventually resolved when the websocket has been closed.

Note: you need to manually invoke this when you want to close a session and config.suspendOnClose is true.

Пример:

session.close().then(() => console.log('Session was properly closed'));

session.suspend()

Returns a promise.

Suspends the enigma.js session by closing the websocket and rejecting all method calls until it has been resumed again.

Пример:

session.suspend().then(() => console.log('We are now suspended'));

session.resume([onlyIfAttached=false])

Returns a promise.

Resume a previously suspended enigma.js session by re-creating the websocket and, if possible, re-open the document as well as refreshing the internal caches. If successful, changed events will be triggered on all generated APIs, and on the ones it was unable to restore, the closed event will be triggered.

onlyIfAttached can be used to only allow resuming if the QIX Engine session was reattached properly.

Eventually resolved when the websocket (and potentially the previously opened document, and generated APIs) has been restored, rejected when it fails any of those steps, or when onlyIfAttached is true and a new QIX Engine session was created.

Пример:

// assuming suspended state:
doc.on('changed', () => console.log('Document was restored'));
object.on('changed', () => console.log('model1 was restored'));
sessionObject.on('closed', () => console.log('Session object could not be restored (new QIX Engine session)'));
session.resume().then(() => console.log('Session was properly resumed'));

Event: opened

Handle opened state. This event is triggered whenever the websocket is connected and ready for communication.

Пример:

session.on('opened', () => console.log('We are connected'));

Event: closed

Handle closed state. This event is triggered when the underlying websocket is closed and config.suspendOnClose is false.

Пример:

session.on('closed', () => console.log('The session was closed'));

Event: suspended

Handle suspended state. This event is triggered in two cases (listed below). It is useful in scenarios where you for example want to block interaction in your application until you are resumed again.

• If config.suspendOnClose is true and there was a network disconnect (socked closed)
• If you ran session.suspend()

Пример:

session.on('suspended', (evt) => console.log(evt.initiator));

The evt.initiator value is a string indicating what triggered the suspended state. Possible values: network, manual.

Event: resumed

Handle resumed state. This event is triggered when the session was properly resumed. It is useful in scenarios where you for example can close blocking modal dialogs and allow the user to interact with your application again.

Пример:

session.on('resumed', () => console.log('The session was resumed'));

Back to top

Event: notification:<name>

Handle a specific JSON-RPC notification event. These events depend on the product you use QIX Engine from.

Пример:

session.on('notification:OnConnected', (data) => console.log(data));

Read more:

• Sense Proxy JSON-RPC notifications on Qlik Sense Help

Event: notification:*

Handle all JSON-RPC notification events.

Пример:

session.on('notification:*', (eventName, data) => console.log(eventName, data));

Event: traffic:sent

Handle outgoing websocket messages.

Generally used in debugging purposes.

Пример:

session.on('traffic:sent', (req) => console.log(req));

Event: traffic:received

Handle incoming websocket messages.

Generally used in debugging purposes.

Пример:

session.on('traffic:received', (res) => console.log(res));

Event: traffic:*

Handle all websocket messages.

Generally used in debugging purposes.

Пример:

session.on('traffic:*', (direction, msg) => console.log(direction, msg));

Generated API

The API for generated APIs depends on the QIX Engine schema you pass into your Configuration, and on what QIX struct the API has.

All API calls made using the generated APIs will return promises which are either resolved or rejected depending on how the QIX Engine responds.

Read more: Generic object model

Пример:

global.openDoc('my-document.qvf').then((doc) => {
  doc.createObject({ qInfo: { qType: 'my-object' } }).then(api => { /* do something with api */ });
  doc.getObject('object-id').then(api => { /* do something with api */ });
  doc.getBookmark('bookmark-id').then(api => { /* do something with api */ });
});

promise.requestId

The requestId property is injected onto promises that enigma.js returns to give you better control in scenarios like cancelling heavy calculation requests and the like.

Read more: JSON-RPC protocol

Example of cancelling a request:

const request = doc.evaluate('SUM([myfield]');
global.cancelRequest(request.requestId);
request.catch(() => {
  console.log('Evaluation was cancelled.');
});

api.id

This property contains the unique identifier for this API.

Пример:

doc.getObject('object-id').then((api) => {
   // api.id === 'object-id'
});

api.type

This property contains the schema class name for this API.

Пример:

doc.getObject('object-id').then((api) => {
   // api.type === 'GenericObject'
});

api.genericType

Despite the name, this property corresponds to the qInfo.qType property on your generic object’s properties object.

Пример:

doc.getObject('object-id').then((api) => {
   // api.genericType === 'linechart'
});

api.session

This property contains a reference to the session that this API belongs to.

Пример:

doc.session.suspend();

api.handle

This property contains the handle QIX Engine assigned to the API. Used internally in enigma.js for caches and JSON-RPC requests.

Пример:

doc.getObject('object-id').then((api) => {
   // typeof api.handle === 'number'
});

Event: changed

Handle changes on the API. The changed event is triggered whenever enigma.js or QIX Engine has identified potential changes on the underlying properties or hypercubes and you should re-fetch your data.

Пример:

api.on('changed', () => {
  api.getLayout().then(layout => /* do something with the new layout */);
});

Event: closed

Handle closed API. The closed event is triggered whenever QIX Engine considers an API closed. It usually means that it no longer exist in the QIX Engine document or session.

Пример:

api.on('closed', () => {
  /* do something in your application, perhaps route your user to an overview page */
});

Event: traffic:sent

Handle outgoing websocket messages for a specific generated API.

Generally used in debugging purposes.

Пример:

api.on('traffic:sent', (req) => console.log(req));

Event: traffic:received

Handle incoming websocket messages for a specific generated API.

Generally used in debugging purposes.

Пример:

api.on('traffic:received', (res) => console.log(res));

Event: traffic:*

Handle all websocket messages for a specific generated API.

Generally used in debugging purposes.

Пример:

api.on('traffic:*', (direction, msg) => console.log(direction, msg));

Sense utilities API

The Sense Utilities API is a standalone module delivered with enigma.js. It can be used to generate Qlik Sense websocket URLs using a configuration, similar to how enigma.js worked in version 1.

Configuration

This section describes the configuration object that is sent into SenseUtilities.buildUrl(config).

SenseUtilities.buildUrl(config)

Returns a string (websocket URL).

See Configuration for the configuration options.

Example in browser (commonjs syntax):

const enigma = require('enigma.js');
const schema = require('enigma.js/schemas/12.20.0.json');
const SenseUtilities = require('enigma.js/sense-utilities');
const url = SenseUtilities.buildUrl({ host: 'my-sense-host', appId: 'some-app' });
const session = enigma.create({ schema, url });