qrs

Node.js library to communicate with Qlik Sense Repository Service (QRS) API.

NOTE: This solution is not actively maintained anymore. Contributors to take over are highly welcome. Alternatively use qrs-interact

Installation

Install with npm:

$ npm install --save qrs

Table of Contents

• Usage
• Configuration Options
• Server Setup
• API
• Plugins
• Running tests
• Contributing
• Author
• License

Usage

var QRS = require('qrs');
var config = {
	"host": 'qsSingle',
	"useSSL": false,	
	"xrfkey": 'ABCDEFG123456789',
	"authentication": "header",
	"headerKey": 'hdr-usr',
	"headerValue": 'qsSingle\\swr'		
};
var qrs = new QRS( config );

// Now run your command like
qrs.get('qrs/about', function( data ) {
	
	// do something with the result
	
});

Configuration Options

The configuration passed to the constructor of qrs drives how authentication is handled.

Typical configurations

Example using header authentication

var config = {
	authentication: 'header',
	host: 'server.mydomain.com',
	useSSL: true,
	virtualProxy: 'hdr',
	headerKey: 'hdr-usr',
	headerValue: 'mydomain\\justme'
}; 

Example using certificates

var config = {
	authentication: 'certificates',
	host: 'server.mydomain.com',
	useSSL: true,
	cert: 'C:\\CertStore\\client.pem',
	key: 'C:\\CertStore\\client_key.pem',
	ca: 'C:\\CertStore\\root.pem',
	port: 4242,
	headerKey: 'X-Qlik-User',
	headerValue: 'UserDirectory:Internal;UserId:sa_repository'
};

All options

• authentication - Authentication method, can be "windows", "certificates" or "header", defaults to "windows".
• host - Qualified / fully qualified name or IP-address of the server where the Qlik Sense Repository server is running on, defaults to "127.0.0.1"
• useSSL - Whether to use SSL or not, defaults to false.
• headerKey - Header key.
• headerValue - Header value.
• virtualProxy - Name of the virtual proxy.
• port - Port to be used.
• cert - Path to client certificate file (client.pem).
• key - Path to client key file (client_key.pem).
• ca - Path to ca file (root.pem)

Server Setup

There are several options to ensure that communication between this node.js module and Qlik Sense server is working properly:

Authenticating with HTTP headers

• Using Header Authentication in Qlik Sense: Setup and Configuration
• Authenticating with HTTP headers in Qlik Sense Help for Developers 2.1.1

Authenticating with a server certificate

• Authenticating with Certificates: Setup and Configuration
• Authenticating with the server certificate in Qlik Sense Help for Developer 2.1.1

API

qrs

Work with Qlik Sense's REST based Repository API (qrs) from within node.js.

Configuration options:

Params

• qrsConfig {Object}: Global configuration options

Example

var QRS = require('qrs');
var config =  {

var qrs = new QRS( config );

.request

(Internal) generic method to send requests to QRS. Typically this method is only used internally, use get, post, put or delete.

Params

• method {String}: Http method, can be GET, POST, PUT or DELETE (defaults to GET).
• endpoint {String}: Endpoint to be used. Check the online documentation of the Qlik Sense Repository API to get a list of all endpoints available.
• urlParams {Array<string,object>}: Additional URL parameters, defined as key/value array, for example [{"key": "foo", "value": valueObj}].
• jsonBody {Object}: JSON object to be used as the body for the Http request.
• body {String}: Body, if not defined as Json object, body needs to be passed as a buffer to e.g. upload a file.
• additionalRequestOptions {Object}: Additional request options.
• additionalHeaders {Object}: Additional headers.
• returns {promise}: Returns a promise.

Example

var QRS = require('qrs');

var qrsConfig = ...; // Set configuration options
var qrs = new QRS( qrsConfig );

qrs.request( 'GET', 'qrs/about', null, null)
   .then( function( data ) {
			console.log( 'about', data );
		}, function ( err ) {
			console.error( 'An error occurred: ', err);
		});

.get

Same as request() but with method: 'GET'.

Params

• endpoint {String}: QRS endpoint to be used.
• urlParams {Array<string,object>}: Additional URL parameters, defined as key/value array, for example [{"key": "foo", "value": valueObj}].
• returns {promise}: Returns a promise.

Example

qrs.get( 'qrs/about')
       .then( function ( data) {
			console.log('about: ', data );
		}, function ( err ) {
			console.error( err );
		});

.post

Same as request() but with method: 'POST'.

Params

• endpoint {String}: QRS endpoint to be used.
• urlParams {Array<string,object>}: Additional URL parameters, defined as key/value array, for example [{"key": "foo", "value": valueObj}].
• jsonBody {Object}: Body to be posted, defined as JSON object.
• returns {promise}: Returns a promise.

.postFile

Post a file, actually same as post(), instead of posting a JSON body, posts a file buffer.

Params

• endpoint {String}: QRS endpoint to be used.
• urlParams {Array<string,object>}: Additional URL parameters, defined as key/value array, for example [{"key": "foo", "value": valueObj}]
• {String}: filePath Absolute or relative file path.
• returns {promise}: Returns a promise.

.put

Same as request() but with method: 'PUT'.

.delete

Same as request() but with method: 'DELETE'.

.getUrl

Return the Url for the REST call considering the given configuration options

Params

• endpoint {string}: Endpoint for the qrs call.
• urlParams {Object[]}: Additional URL parameters as key/value array.
• urlParam.key {String}: Key.
• urlParam.value {Object}: Value.
• returns {String}: The constructed Url.

.setConfig

Set global configurations options for qrs. Can be used to change the configuration options after qrs has been initialized.

Params

• qrsConfig {Object}: Global configuration options

Example

var QRS = require('qrs');
var configCert = {
	authentication: 'certificates',
	...
};
var qrs = new QRS( configCert );

// Talking to the server using certificates
qrs.get('qrs/about', function( result ) {
	// ...
});

// Change configuration options, e.g.
var configHeader = {
	authentication: 'header',
	...
};

qrs.setConfig( configHeader);

// Talking to the server, now using header authentication.
qrs.get('qrs/about', function( result ) {
 // ...
});

.getConfig

Return the current configuration options.

• returns {qrsConfig} qrsConfig: Configuration object.

Example

var QRS = require('qrs');
var config = {
	host: 'myserver.domain.com';
};
var qrs = new QRS( config );
var host = qrs.getConfig( 'host' );
console.log(host); //<== 'myserver.domain.com'

.set

Change a single configuration property.

Params

• key {String}: Key of the property
• val {Object}: Value

Example

var QRS = require('qrs');
var config = {
	host: 'myserver.domain.com';
};
var qrs = new QRS( config );

qrs.get('qrs/about', function( result ) {
	// about from myserver.domain.com
});

qrs.set('host', 'mysecondserver.domain.com');
qrs.get('qrs/about', function( result ) {
 // about from mysecondserver.domain.com
});

.getConfigValue

Retrieve a single configuration property.

Params

• key {String}: Key of the property
• returns {Object}: Value of the requested property, otherwise undefined.

.plugins

Returns an array of loaded plugins. Use registerPlugin() to load a plugin.

.registerPlugin

Register a plugin to work with the base class of qrs. Have a look at some of the already existing plugins like ./lib/sugar/ep-mime.js

Params

• {Object}: plugin

Example

// -----------------------------------------------------------
// Define the plugin.
// ~~
// Purpose: Do something great with extensions.
// Filename: ep-extension.js
// -----------------------------------------------------------

function Extension ( base ) {

	function doSomething() {
		base.get( 'qrs/extension/schema')
			.then( function( result ) {
				// result now holding the result from the server
			}, function (err) {
				// error handling
			});

		return {
			doSomething: doSomething
		};
}

module.exports = Extension;

// -----------------------------------------------------------
// Register and use it
// -----------------------------------------------------------

var qrs = new QRS( config );
qrs.registerPlugin('./ep-extension.js');

// Use the plugin
qrs.extension.upload( myFile, function( result ) {
		// The file has been uploaded
});

Plugins

Think of plugins as some kind of sugar layer with additional business logic on top of qrs. It is easy to either add new plugins to the qrs repository or just to load some external code/plugin. The list of built-in plugins is probably and hopefully a growing one (and hopefully not only created by the author of this document).

The following plugins are available with the current version of qrs: