Neverending Prototype Mode

    qrs

    2.0.3 • Public • Published

    NPM versionBuild Statusdependencies

    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

    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

    Authenticating with a server certificate

    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:

    Plugin "Mime"

    Mime type definition

    Mime

    Handle Mime types in QRS.

    Params

    • {qrs}: base - Base class, instance of qrs.

    add

    Adds a mime type.

    When adding the mime type, the following validation logic will be performed:

    • All existing mime types will be grouped by mime, additionalHeaders and binary.
    • If there is already a mime type with the same information compared to the given one, the field extension will be updated. An example is listed below.

    Params

    • {Object}: mimeTypeDef
    • {string}: mimeTypeDef.mime - Mime type, e.g. "application/markdown".
    • {string}: mimeTypeDef.extensions - Comma delimited string of supported file extensions, e.g. "md,markdown".
    • {boolean}: mimeTypeDef.additionalHeaders - Additional headers, defaults to null.
    • {boolean}: mimeTypeDef.binary - Whether this is a binary file type or not.
    • returns {promise}

    Example

    // -----------------------------------------------------------------
    // Inserting logic
    // -----------------------------------------------------------------  *
     
    // Assuming that the following mime type is already stored:
    {
        extensions: "md"
        mime: "application/markdown",
        additionalHeaders: null,
        binary: false
    }
    // If you add the following mime type
    {
        extensions: "markdown"
        mime: "application/markdown",
        additionalHeaders: null,
        binary: false
    }
    //this would then result into:
    {
        extensions: "md,markdown"
        mime: "application/markdown",
        additionalHeaders: null,
        binary: false
    }
     
    // -----------------------------------------------------------------
    // Adding a mime type:
    // -----------------------------------------------------------------
     
    var mimeType = {
        extensions: "md"
        mime: "application/markdown",
        additionalHeaders: null,
        binary: false
    }
     
    qrs.mime.add( mimeType )
            .then( function (result ) {
                // work with the result
            }, function (err) {
                // error handling
    });
     

    get

    Returns a list of existing mime types.

    The list can be filtered by the file-extensions as shown in the example.

    Params

    • {string}: filter
    • returns {promise}

    Example

    getMimeTypes( 'html')
       .then( function (data) {
     
            // data now contains an array of mime types where the field extensions contains "html"
            // Results: html, xhtml, etc.
     
        })

    addMultiple

    Adds an array of mime types (See add for more information about mimeTypeDef).

    Params

    • {mimeTypeDef[]}: mimeTypeDefs - Array of mime type definitions.
    • returns {promise}

    addFromFile

    Add mime types defined in a file. Every line in the file is defined by the following entries, delimited by a semi-colon (;): - extensions - {string} file extension, multiple values separated by a comma, e.g. "md,markdown" - mime - {string} Mime type - additionalHeaders - {boolean} Additional defined headers, leave blank if unsure - binary - {boolean} Whether this is a binary format or not.

    Params

    • {String}: filePath - Absolute file path.
    • returns {promise}

    Example

    md;application/markdown;;false
    yml;text/yml;;false
    woff2;application/font-woff2;;true

    deleteById

    Delete a mime entry from the Qlik Sense Repository by its given Id.

    Params

    • {String}: id
    • returns {promise}

    getUpdateOrInsert

    Returns whether the mime type already exists or not.

    Params

    • {mimeTypeDef}: mimeTypeDef
    • returns {object}: result - Returned result.
    • returns {boolean}: result.isUpdate - Whether to update or add.

    Running tests

    Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

    $ npm install && npm test

    Contributing

    Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

    Author

    Stefan Walther

    License

    Copyright © 2018, Stefan Walther. MIT


    This file was generated by verb-generate-readme, v0.6.0, on January 21, 2018.

    Install

    npm i qrs

    DownloadsWeekly Downloads

    10

    Version

    2.0.3

    License

    MIT

    Last publish

    Collaborators

    • stefanwalther