{
"scriptappy": "1.0.0",
"info": {
"name": "enigma.js",
"description": "JavaScript library for consuming Qlik backend services",
"version": "2.7.3",
"license": "MIT",
"stability": "stable",
"x-qlik-visibility": "public",
"x-qlik-stability": "stable"
},
"entries": {
"Enigma.create": {
"description": "Function used to create a QIX session.",
"kind": "function",
"params": [
{
"name": "config",
"description": "The configuration object for the QIX session.",
"type": "#/definitions/Configuration"
}
],
"returns": {
"description": "Returns a new QIX session.",
"type": "#/definitions/Session"
},
"examples": [
"Example minimal session creation\nconst enigma = require('enigma.js');\nconst schema = require('enigma.js/schemas/12.20.0.json');\nconst WebSocket = require('ws');\nconst config = {\n schema,\n url: 'ws://localhost:9076/app/engineData',\n createSocket: url => new WebSocket(url),\n};\nconst session = enigma.create(config);"
]
},
"errorCodes": {
"description": "This is a list of error codes that can be thrown from enigma.js API calls.",
"kind": "object",
"entries": {
"NOT_CONNECTED": {
"description": "You're trying to send data on a socket that's not connected.",
"defaultValue": -1,
"type": "number"
},
"OBJECT_NOT_FOUND": {
"description": "The object you're trying to fetch does not exist.",
"defaultValue": -2,
"type": "number"
},
"EXPECTED_ARRAY_OF_PATCHES": {
"description": "Unexpected RPC response, expected array of patches.",
"defaultValue": -3,
"type": "number"
},
"PATCH_HAS_NO_PARENT": {
"description": "Not an object that can be patched.",
"defaultValue": -4,
"type": "number"
},
"ENTRY_ALREADY_DEFINED": {
"description": "This entry is already defined with another key.",
"defaultValue": -5,
"type": "number"
},
"NO_CONFIG_SUPPLIED": {
"description": "You need to supply a configuration.",
"defaultValue": -6,
"type": "number"
},
"PROMISE_REQUIRED": {
"description": "There's no promise object available (polyfill required?).",
"defaultValue": -7,
"type": "number"
},
"SCHEMA_STRUCT_TYPE_NOT_FOUND": {
"description": "The schema struct type you requested does not exist.",
"defaultValue": -8,
"type": "number"
},
"SCHEMA_MIXIN_CANT_OVERRIDE_FUNCTION": {
"description": "Can't override this function.",
"defaultValue": -9,
"type": "number"
},
"SCHEMA_MIXIN_EXTEND_NOT_ALLOWED": {
"description": "Extend is not allowed for this mixin.",
"defaultValue": -10,
"type": "number"
},
"SESSION_SUSPENDED": {
"description": "Session suspended - no interaction allowed.",
"defaultValue": -11,
"type": "number"
},
"SESSION_NOT_ATTACHED": {
"description": "onlyIfAttached supplied, but you got SESSION_CREATED.",
"defaultValue": -12,
"type": "number"
}
},
"examples": [
"Handling an enigma.js error\nconst { NOT_CONNECTED } = require('enigma.js/error-codes');\ntry {\n const layout = await model.getLayout();\n} catch (err) {\n if (err.code === NOT_CONNECTED) {\n console.log('Tried to communicate on a session that is closed');\n }\n}"
]
},
"SenseUtilities.buildUrl": {
"description": "Function used to build a URL.",
"kind": "function",
"params": [
{
"name": "urlConfig",
"description": "The URL configuration object.",
"type": "#/definitions/SenseConfiguration"
}
],
"returns": {
"description": "Returns the websocket URL.",
"type": "string"
},
"examples": [
"Example of building and using a Qlik Sense-compatible WebSocket URL\nconst enigma = require('enigma.js');\nconst schema = require('enigma.js/schemas/12.20.0.json');\nconst SenseUtilities = require('enigma.js/sense-utilities');\nconst url = SenseUtilities.buildUrl({ host: 'my-sense-host', appId: 'some-app' });\nconst session = enigma.create({ schema, url });"
]
}
},
"definitions": {
"API": {
"description": "The API for generated APIs depends on the QIX Engine schema you pass into your Configuration, and\non what QIX struct the API has.\n\nAll API calls made using the generated APIs will return promises that are either resolved or\nrejected depending on how the QIX Engine responds.",
"kind": "interface",
"entries": {
"id": {
"description": "Contains the unique identifier for this API.",
"type": "string"
},
"type": {
"description": "Contains the schema class name for this API.",
"type": "string"
},
"genericType": {
"description": "Corresponds to the qInfo.qType property on the generic object's\nproperties object.",
"type": "string"
},
"session": {
"description": "Contains a reference to the session that this API belongs to.",
"type": "#/definitions/Session"
},
"handle": {
"description": "Contains the handle QIX Engine assigned to the API. Used interally in\nenigma.js for caches and JSON-RPC requests.",
"type": "number"
}
},
"examples": [
"Example using `global` and `generic object` struct APIs\nglobal.openDoc('my-document.qvf').then((doc) => {\n doc.createObject({ qInfo: { qType: 'my-object' } }).then(api => { });\n doc.getObject('object-id').then(api => { });\n doc.getBookmark('bookmark-id').then(api => { });\n});"
],
"events": {
"changed": {
"description": "Handles changes on the API. The changed event is triggered whenever enigma.js or QIX Engine has\nidentified potential changes on the underlying properties or hypercubes and you should re-fetch\nyour data.",
"kind": "event",
"params": [],
"examples": [
"Bind the `changed` event\napi.on('changed', () => {\n api.getLayout().then(layout => { });\n});"
]
},
"closed": {
"description": "Handles closed API. The closed event is triggered whenever QIX Engine considers an API closed.\nIt usually means that it no longer exists in the QIX Engine document or session.",
"kind": "event",
"params": [],
"examples": [
"Bind the `closed` event\napi.on('closed', () => {\n console.log(api.id, 'was closed');\n});"
]
},
"traffic": {
"description": "Handles JSON-RPC requests/responses for this API. Generally used in debugging purposes.\n`traffic:*` will handle all websocket messages, `traffic:sent` will handle outgoing messages\nand `traffic:received` will handle incoming messages.",
"kind": "event",
"params": [],
"examples": [
"Bind the traffic events\n// bind both in- and outbound traffic to console.log:\napi.on('traffic:*', console.log);\n// bind outbound traffic to console.log:\napi.on('traffic:sent', console.log);\n// bind inbound traffic to console.log:\napi.on('traffic:received', console.log);"
]
}
}
},
"Configuration": {
"description": "The enigma.js configuration object.",
"kind": "interface",
"entries": {
"schema": {
"description": "Object containing the specification for the API to generate.\nCorresponds to a specific version of the QIX Engine API.",
"type": "Object"
},
"url": {
"description": "String containing a proper websocket URL to QIX Engine.",
"type": "string"
},
"createSocket": {
"description": "A function to use when instantiating the WebSocket,\nmandatory for Node.js.",
"optional": true,
"type": "function"
},
"Promise": {
"description": "ES6-compatible Promise library.",
"optional": true,
"type": "Object"
},
"suspendOnClose": {
"description": "Set to true if the session should be suspended\ninstead of closed when the websocket is closed.",
"optional": true,
"defaultValue": false,
"type": "boolean"
},
"mixins": {
"description": "Mixins to extend/augment the QIX Engine API. Mixins\nare applied in the array order.",
"optional": true,
"defaultValue": "[]",
"kind": "array",
"items": {
"type": "#/definitions/Mixin"
}
},
"requestInterceptors": {
"description": "Interceptors for augmenting requests before they\nare sent to QIX Engine. Interceptors are applied in the array order.",
"optional": true,
"defaultValue": "[]",
"type": "Array"
},
"responseInterceptors": {
"description": "Interceptors for augmenting responses before they\nare passed into mixins and end-users. Interceptors are applied in the array order.",
"optional": true,
"defaultValue": "[]",
"type": "Array"
},
"protocol": {
"description": "An object containing additional JSON-RPC request parameters.",
"optional": true,
"defaultValue": "{}",
"kind": "object",
"entries": {
"delta": {
"description": "Set to false to disable the use of the\nbandwidth-reducing delta protocol.",
"optional": true,
"defaultValue": true,
"type": "boolean"
}
}
}
},
"examples": [
"Example defining a configuration object\nconst enigma = require('enigma.js');\nconst WebSocket = require('ws');\nconst bluebird = require('bluebird');\nconst schema = require('enigma.js/schemas/12.20.0.json');\n\nconst config = {\n schema,\n url: 'ws://localhost:4848/app/engineData',\n createSocket: url => new WebSocket(url),\n Promise: bluebird,\n suspendOnClose: true,\n mixins: [{ types: ['Global'], init: () => console.log('Mixin ran') }],\n protocol: { delta: false },\n};\n\nenigma.create(config).open().then((global) => {\n // global === QIX global interface\n process.exit(0);\n});"
]
},
"EnigmaError": {
"description": "Error containing a custom error code.",
"extends": [
{
"type": "Error"
}
],
"kind": "class",
"constructor": {
"kind": "function",
"params": []
},
"entries": {
"code": {
"description": "The error code as defined by `errorCodes`.",
"type": "number"
},
"enigmaError": {
"defaultValue": true,
"type": "boolean"
}
}
},
"Interceptor": {
"description": "Interceptor is a concept similar to mixins, but runs on a lower level. The interceptor concept\ncan augment either the requests (i.e. before sent to QIX Engine), or the responses (i.e. after\nQIX Engine has sent a response). The interceptor promises run in parallel to the regular\npromises used in enigma.js, which means that it can be really useful when you want to normalize\nbehaviors in your application.",
"kind": "interface",
"entries": {}
},
"InterceptorRequest": {
"implements": [
{
"type": "#/definitions/Interceptor"
}
],
"kind": "class",
"constructor": {
"kind": "function",
"params": []
},
"entries": {
"onFulfilled": {
"description": "This method is invoked when a request is about to be sent to QIX Engine.",
"kind": "function",
"params": [
{
"name": "session",
"description": "The session executing the interceptor.",
"type": "#/definitions/Session"
},
{
"name": "request",
"description": "The JSON-RPC request that will be sent.",
"type": "Object"
}
]
}
},
"examples": [
"Implement a request interceptor\nconst enigma = require('enigma.js');\nconst WebSocket = require('ws');\nconst schema = require('enigma.js/schemas/12.20.0.json');\n\nconst session = enigma.create({\n schema,\n url: 'ws://localhost:9076/app/engineData',\n createSocket: (url) => new WebSocket(url),\n requestInterceptors: [{\n onFulfilled: function logRequest(sessionReference, request) {\n console.log('Request being sent', request);\n return request;\n }\n },\n});"
]
},
"InterceptorResponse": {
"implements": [
{
"type": "#/definitions/Interceptor"
}
],
"kind": "class",
"constructor": {
"kind": "function",
"params": []
},
"entries": {
"onFulfilled": {
"description": "This method is invoked when a promise has been successfully resolved;\nuse this to modify the result or reject the promise chain before it is sent\nto mixins.",
"kind": "function",
"params": [
{
"name": "session",
"description": "The session executing the interceptor.",
"type": "#/definitions/Session"
},
{
"name": "request",
"description": "The JSON-RPC request resulting in this response.",
"type": "Object"
},
{
"name": "result",
"description": "Whatever the previous interceptor is resolved with.",
"type": "Object"
}
]
},
"onRejected": {
"description": "This method is invoked when a previous interceptor has rejected the\npromise; use this to handle, for example, errors before they are sent into mixins.",
"kind": "function",
"params": [
{
"name": "session",
"description": "The session executing the interceptor. You may use .retry() to retry\nsending it to QIX Engine.",
"type": "#/definitions/Session"
},
{
"name": "request",
"description": "The JSON-RPC request resulting in this error.",
"type": "Object"
},
{
"name": "error",
"description": "Whatever the previous interceptor is rejected with.",
"type": "Object"
}
]
}
},
"examples": [
"Implement a request interceptor\nconst enigma = require('enigma.js');\nconst WebSocket = require('ws');\nconst schema = require('enigma.js/schemas/12.20.0.json');\n\nconst session = enigma.create({\n schema,\n url: 'ws://localhost:9076/app/engineData',\n createSocket: (url) => new WebSocket(url),\n responseInterceptors: [{\n onRejected: function logError(sessionReference, request, error) {\n console.log('Error returned from QIX engine', error, 'Originating request:', request);\n // throw error so it's continued to be rejected:\n throw error;\n }\n },\n});"
]
},
"Mixin": {
"description": "The mixin concept allows you to add or override QIX Engine API functionality. A mixin is\nbasically a JavaScript object describing which types it modifies, and a list of functions\nfor extending and overriding the API for those types.\n\nQIX Engine types like, for example, GenericObject, Doc, GenericBookmark, are supported but\nalso custom GenericObject types such as barchart, story and myCustomType. An API will get\nboth their generic type as well as custom type mixins applied.\n\nMixins that are bound to several different types can find the current API type in the\n`genericType` or `type` members. `this.type` would, for instance, return `GenericObject` and\n`this.genericType` would return `barchart`.\n\nSee the Mixins examples on how to use it. Below is an outline of what the mixin API consists of.",
"kind": "interface",
"entries": {
"types": {
"description": "String or array of strings containing the API-types that\nwill be mixed in.",
"kind": "union",
"items": [
{
"type": "string"
},
{
"kind": "array",
"items": {
"type": "string"
}
}
],
"type": "any"
},
"extend": {
"description": "Object literal containing the methods that will be extended on the\nspecified API.",
"optional": true,
"type": "Object"
},
"override": {
"description": "Object literal containing the methods to override existing methods.",
"optional": true,
"type": "Object"
},
"init": {
"description": "Init function that, if defined, will run when an API is instantiated.\nIt runs with Promise and API object as parameters.",
"optional": true,
"type": "function"
}
}
},
"SenseConfiguration": {
"description": "This object describes the configuration that is sent into `buildUrl(config)`.",
"kind": "object",
"entries": {
"appId": {
"description": "The app ID. If omitted, only the global object is returned.\n Otherwise both global and app object are returned.",
"optional": true,
"type": "string"
},
"noData": {
"description": "Whether to open the app without data.",
"optional": true,
"defaultValue": false,
"type": "boolean"
},
"secure": {
"description": "Set to false if an unsecure WebSocket should be used.",
"optional": true,
"defaultValue": true,
"type": "boolean"
},
"host": {
"description": "Host address.",
"optional": true,
"type": "string"
},
"port": {
"description": "Port to connect to.",
"optional": true,
"type": "number"
},
"prefix": {
"description": "The absolute base path to use when connecting.\n Used for proxy prefixes.",
"optional": true,
"defaultValue": "\"/\"",
"type": "string"
},
"subpath": {
"description": "The subpath.",
"optional": true,
"defaultValue": "\"\"",
"type": "string"
},
"route": {
"description": "Used to instruct Proxy to route to the correct receiver.",
"optional": true,
"defaultValue": "\"\"",
"type": "string"
},
"identity": {
"description": "Identity to use.",
"optional": true,
"defaultValue": "\"\"",
"type": "string"
},
"urlParams": {
"description": "Used to add parameters to the WebSocket URL.",
"optional": true,
"defaultValue": "{}",
"type": "Object"
},
"ttl": {
"description": "A value in seconds that QIX Engine should keep the session\n alive after socket disconnect (only works if QIX Engine supports it).",
"optional": true,
"type": "number"
}
},
"type": "Object"
},
"Session": {
"description": "The QIX Engine session object.",
"kind": "class",
"constructor": {
"kind": "function",
"params": []
},
"entries": {
"close": {
"description": "Closes the websocket and cleans up internal caches. Also triggers the closed event\non all generated APIs. Note that you have to manually invoke this when you want to\nclose a session and config.suspendOnClose is true.",
"kind": "function",
"params": [
{
"name": "code",
"description": "The reason code for closing the connection.",
"optional": true,
"defaultValue": 1000,
"type": "number"
},
{
"name": "reason",
"description": "The human readable string describing why the connection is closed.",
"optional": true,
"defaultValue": "\"\"",
"type": "string"
}
],
"returns": {
"description": "Eventually resolved when the websocket has been closed.",
"type": "Promise",
"generics": [
{
"type": "Object"
}
]
},
"emits": [
{
"type": "#/definitions/Session/events/closed"
}
],
"examples": [
"Closing a session\nsession.close().then(() => {\n console.log('Session was closed');\n});"
]
},
"open": {
"description": "Establishes the websocket against the configured URL and returns the Global instance.",
"kind": "function",
"params": [],
"returns": {
"description": "Eventually resolved if the connection was successful.",
"type": "Promise",
"generics": [
{
"type": "Object"
}
]
},
"emits": [
{
"type": "#/definitions/Session/events/opened"
}
],
"examples": [
"Opening a sesssion\nsession.open().then(() => {\n console.log('Session was opened');\n});"
]
},
"resume": {
"description": "Resumes a previously suspended enigma.js session by recreating the websocket and,\nif possible, reopen the document as well as refreshing the internal cashes. If successful,\nchanged events will be triggered on all generated APIs, and on the ones it was unable to\nrestore, the closed event will be triggered.",
"kind": "function",
"params": [
{
"name": "onlyIfAttached",
"description": "If true, resume only if the session was reattached properly.",
"type": "boolean"
}
],
"returns": {
"description": "Eventually resolved when the websocket (and potentially the\npreviously opened document, and generated APIs) has been restored; it is rejected when it fails\nany of those steps, or when onlyIfAttached is true and a new session was created.",
"type": "Promise",
"generics": [
{
"type": "Object"
}
]
},
"emits": [
{
"type": "#/definitions/Session/events/resumed"
}
],
"examples": [
"Resuming a session\nsession.resume(true).then(() => {\n console.log('Session was resumed by re-attaching');\n});"
]
},
"send": {
"description": "Function used to send data on the RPC socket.",
"kind": "function",
"params": [
{
"name": "request",
"description": "The request to be sent. (data and some meta info)",
"type": "Object"
}
],
"returns": {
"description": "Returns a promise instance.",
"type": "Object"
}
},
"suspend": {
"description": "Suspends the enigma.js session by closing the websocket and rejecting all method calls\nuntil it is has resumed again.",
"kind": "function",
"params": [
{
"name": "code",
"description": "The reason code for suspending the connection.",
"optional": true,
"defaultValue": 4000,
"type": "number"
},
{
"name": "reason",
"description": "The human readable string describing\nwhy the connection is suspended.",
"optional": true,
"defaultValue": "\"\"",
"type": "string"
}
],
"returns": {
"description": "Eventually resolved when the websocket has been closed.",
"type": "Promise",
"generics": [
{
"type": "Object"
}
]
},
"emits": [
{
"type": "#/definitions/Session/events/suspended"
}
],
"examples": [
"Suspending a session\nsession.suspend().then(() => {\n console.log('Session was suspended');\n});"
]
}
},
"events": {
"closed": {
"description": "Handles closed state. This event is triggered when the underlying websocket is closed and\nconfig.suspendOnClose is false.",
"kind": "event",
"params": [],
"examples": [
"Handling session closed\nsession.on('closed', () => {\n console.log('Session was closed, clean up!');\n});"
]
},
"notification": {
"description": "Handles all JSON-RPC notification events, 'notification:* or handles a specific JSON-RPC\nnotification event, 'notification:OnConnected'. These events depend on the product from which\nyou use QIX Engine.",
"kind": "event",
"params": [],
"examples": [
"Bind the notification events\n// bind all notifications to console.log:\nsession.on('notification:*', console.log);\n// bind a specific notification to console.log:\nsession.on('notification:OnConnected', console.log);"
]
},
"opened": {
"description": "Handles opened state. This event is triggered whenever the websocket is connected and\nready for communication.",
"kind": "event",
"params": [],
"examples": [
"Bind the session opened event\nsession.on('opened', () => {\n console.log('Session was opened');\n});"
]
},
"resumed": {
"description": "Handles resumed state. This event is triggered when the session was properly resumed. It is\nuseful in scenarios where, for example, you can close blocking modal dialogs and allow the\nuser to interact with your application again.",
"kind": "event",
"params": [],
"examples": [
"Handling session resumed\nsession.on('resumed', () => {\n console.log('Session was resumed, we can close that \"reconnecting\" dialog now');\n});"
]
},
"suspended": {
"description": "Handles suspended state. This event is triggered in two cases (listed below). It is useful\nin scenarios where, for example, you want to block interaction with your application until\nyou resume again. Or, if config.suspendOnClose is true and there was a network disconnect\n(socket closed) or if you ran session.suspend().",
"kind": "event",
"params": [
{
"name": "evt",
"description": "Event object.",
"kind": "object",
"entries": {
"initiator": {
"description": "String indication what triggered the suspended state. Possible\nvalues network, manual.",
"type": "string"
}
}
}
],
"examples": [
"Handling session suspended\nsession.on('suspended', () => {\n console.log('Session was suspended, retrying...');\n session.resume();\n});"
]
},
"traffic": {
"description": "Handles websocket messages. Generally used for debugging purposes. `traffic:*` will handle all\nwebsocket messages, `traffic:sent` will handle outgoing messages, and `traffic:received` will\nhandle incoming messages.",
"kind": "event",
"params": [],
"examples": [
"Bind the traffic events\n// bind both in- and outbound traffic to console.log:\nsession.on('traffic:*', console.log);\n// bind outbound traffic to console.log:\nsession.on('traffic:sent', console.log);\n// bind inbound traffic to console.log:\nsession.on('traffic:received', console.log);"
]
}
}
}
}
}