Javascript SpagoBI API

SpagoBI SDK contains a javascript API that helps users to embed parts of SpagoBI Suite inside a web page or to retrieve informations about datasets and documents.

Same-origin policy

Because of this policy web browsers don't let a script in a web page to retrieve data from a url if this url has a different origin respect of the web page. The origin is different if the URI schema, host name or port are different. For more informations about the same-origin policy please refer to https://en.wikipedia.org/wiki/Same-origin_policy.

That means that if you use SpagoBI SDK in a different origin from the SpagoBI server the browser will not let your script to communicate with SpagoBI.

There are two types of functions in SpagoBI SDK: 1. iFrame injection: they inject a SpagoBI page inside an iFrame 2. REST services: they use REST services of SpagoBI to retrieve some kind of informations

For the first type of function same-origin policy is not a problem. For the second one it is. In order to solve the problem SpagoBI SDK use two different approaches: 1. jsonp (see https://en.wikipedia.org/wiki/JSONP for more details) 2. CORS (see https://en.wikipedia.org/wiki/Cross-origin_resource_sharing for more details)

The jsonp version of these functions are inside the Sbi.sdk.api namespace together with the functions of the first type (iFrame injection). The CORS version of the same functions (the ones based on REST services) are in the Sbi.sdk.cors.api namespace and have same names as jsonp counterpart.

For example, injectDocument(config) is a function of the first type and can be found in Sbi.sdk.api namespace while getDataSetList(config) is of the second type and can be found in Sbi.sdk.api (jsonp version) namespace as well as Sbi.sdk.cors.api (CORS version).

Jsonp vs CORS

New api that gives the same functionalities of these functions were developed using CORS instead of jsonp. There are three main advantages on using CORS over jsonp:

all the methods are available while in jsonp only GET request can be done;
if an error occurs it is possible to manage it with CORS, while in jsonp it is only possible to set a timeout;
jsonp has security problems (see later for an example).

However, jsonp is supported by all browser while CORS doesn't work properly in Internet Explorer 8 and 9 (in IE 7 and earlier versions is not supported at all).

If you use the version with jsonp please take note about this security problem: the authentication is made with a GET request, so users credentials are sent as query parameters. It would be better to not use "authenticate" function (in that way, the user should already logged in in order to use the api).

Authentication

In order to use SpagoBI SDK functions the user has to be authenticated. If the user is already authenticated in SpagoBI the SDK use cockies to retrieve the session and all functions can be used.

If the user is not already authenticated he has to log in. There is the authenticate function for that. As for functions based on REST services, the authenticate function is also available in both Sbi.sdk.api and Sbi.sdk.cors.api namespaces.

If you use the version with jsonp please take note about this security problem: the authentication is made with a GET request, so users credentials are sent as query parameters. It would be better to not use "authenticate" function (in that way, the user should already logged in in order to use the API)

For the functions that use REST services it is also available Basic Authentication. If the user is not authenticated the browser will show a pop up asking for user credentials the first time. Than the credentials will be saved in the cache of the browser and they will be used for all other REST services. The functions based on REST services and CORS give also the possibility to specify the credentials that will be set automatically in the (Basic Authentication) header of the request.

SDK Javascript reference

This documentation is generated from Javascript sources using jsdoc to markdown.

Sbi : object

Typedefs

ResponseCallback : function: This callback is called a response is returned by the server.

Sbi : `object`

Kind: global namespace

Sbi : object
- .sdk : object
  - .api : object
  - .cors : object
    - .api : object
      - .getDataSetList(config)
      - .executeDataSet(config)

Sbi.sdk : `object`

Kind: static namespace of Sbi

.sdk : object
- .api : object
- .cors : object
  - .api : object
    - .getDataSetList(config)
    - .executeDataSet(config)

sdk.api : `object`

Note that Sbi.sdk.api definition is defined in both api.js and api_jsonp.js. In api_jsonp.js there are functions that uses jsonp to avoid the same-origin policy. The same functions were also developed with CORS and they are defined in api_cors.js.

jsonp is deprecated, it is highly recommended to use CORS instead of it.

NB: CORS functions are inside Sbi.sdk.cors.api namespace and have same names as jsonp counterpart.

Kind: static namespace of sdk

.api : object

api.getDocumentHtml(config)

It returns the HTML code of an iFrame containing document visualization. In particular config is an object that must contain at least one between documentId and documentLabel. It can also have (optional) parameters (an object containing values of document parameters), executionRole, displayToolbar and iframe, an object containing the style, height and width of the iframe where the document will be rendered (height and width can also be put outside the iframe object).

Kind: static method of api

Param	Type	Description
config	`Object`	the configuration
config.documentId	`String`	the document id, must contain at least one between documentId and documentLabel
config.documentLabel	`String`	the document label, must contain at least one between documentId and documentLabel
[config.parameters]	`Object`	the values of document parameters
[config.executionRole]	`String`	the role of execution
[config.displayToolbar]	`Boolean`	display or not the toolbar
[config.displaySliders]	`Boolean`	display or not the sliders
[config.iframe]	`Object`	the style object of iframe
[config.iframe.height]	`String`	the height of iframe
[config.iframe.width]	`String`	the width of iframe
[config.iframe.style]	`String`	the style of iframe

Example

var html = Sbi.sdk.api.getDocumentHtml({
        documentLabel: 'RPT_WAREHOUSE_PROF'
        , executionRole: '/spagobi/user'
        , parameters: {warehouse_id: 19}
        , displayToolbar: false
        , displaySliders: false
        , iframe: {
            height: '500px'
            , width: '100%'
            , style: 'border: 0px;'
        }
    });

api.injectDocument(config)

It calls getDocumentHtml and inject the generated iFrame inside a specified tag. If the target tag is not specified in config variable, it chooses the tag as default. It can also have (optional) parameters (an object containing values of document parameters), executionRole, displayToolbar and iframe, an object containing the style, height and width of the iframe where the document will be rendered (height and width can also be put outside the iframe object).

Kind: static method of api
See: getDocumentHtml

Param	Type	Description
config	`Object`	the configuration
config.documentId	`String`	the document id, must contain at least one between documentId and documentLabel
config.documentLabel	`String`	the document label, must contain at least one between documentId and documentLabel
[config.parameters]	`Object`	the values of document parameters
[config.executionRole]	`String`	the role of execution
[config.displayToolbar]	`Boolean`	display or not the toolbar
[config.displaySliders]	`Boolean`	display or not the sliders
[config.iframe]	`Object`	the style object of iframe
[config.iframe.height]	`String`	the height of iframe
[config.iframe.width]	`String`	the width of iframe
[config.iframe.style]	`String`	the style of iframe

Example

execTest8 = function() {
    Sbi.sdk.api.injectWorksheet({
        datasetLabel: 'DS_DEMO_51_COCKPIT'
        , target: 'worksheet'
        , height: '600px'
        , width: '1100px'
        , iframe: {
            style: 'border: 0px;'
        }
    });
};

api.getWorksheetHtml(config)

It returns the HTML code of an iFrame containing worksheet visualization. config is an object that must contain datasetLabel and iframe, an object containing the style, height and width of the iframe where the worksheet and qbe will be rendered (height and width can also be put outside the iframe object).

Kind: static method of api

Param	Type	Description
config	`Object`	the configuration
config.target	`String`	the target
config.documentLabel	`String`	the document label, must contain at least one between documentId and documentLabel
[config.height]	`String`	the height of iframe, can be put inside iframe object
[config.width]	`String`	the width of iframe, can be put inside iframe object
config.iframe	`Object`	the style object of iframe
[config.iframe.height]	`String`	the height of iframe, can be put outside
[config.iframe.width]	`String`	the width of iframe
[config.iframe.style]	`String`	the style of iframe

api.injectWorksheet(config)

It calls getWorksheetHtml and inject the generated iFrame inside a specified tag. If the target tag is not specified in config variable, it chooses the tag as default config is an object that must contain datasetLabel and iframe, an object containing the style, height and width of the iframe where the worksheet and qbe will be rendered (height and width can also be put outside the iframe object).

Kind: static method of api

Param	Type	Default	Description
config	`Object`		the configuration
[config.target]	`String`	`"<body>"`	the target
config.documentLabel	`String`		the document label, must contain at least one between documentId and documentLabel
[config.height]	`String`		the height of iframe, can be put inside iframe object
[config.width]	`String`		the width of iframe, can be put inside iframe object
config.iframe	`Object`		the style object of iframe
[config.iframe.height]	`String`		the height of iframe, can be put outside
[config.iframe.width]	`String`		the width of iframe
[config.iframe.style]	`String`		the style of iframe

api.getQbeHtml(config)

It returns the HTML code of an iFrame containing qbe visualization. config is an object that must contain datasetLabel and iframe, an object containing the style, height and width of the iframe where the worksheet and qbe will be rendered (height and width can also be put outside the iframe object).

Kind: static method of api

Param	Type	Description
config	`Object`	the configuration
config.target	`String`	the target
config.documentLabel	`String`	the document label, must contain at least one between documentId and documentLabel
[config.height]	`String`	the height of iframe, can be put inside iframe object
[config.width]	`String`	the width of iframe, can be put inside iframe object
config.iframe	`Object`	the style object of iframe
[config.iframe.height]	`String`	the height of iframe, can be put outside
[config.iframe.width]	`String`	the width of iframe
[config.iframe.style]	`String`	the style of iframe

api.injectQbe(config)

It calls getQbeHtml and inject the generated iFrame inside a specified tag. If the target tag is not specified in config variable, it chooses the tag as default. config is an object that must contain datasetLabel and iframe, an object containing the style, height and width of the iframe where the worksheet and qbe will be rendered (height and width can also be put outside the iframe object).

Kind: static method of api

Param	Type	Default	Description
config	`Object`		the configuration
[config.target]	`String`	`"<body>"`	the target
config.documentLabel	`String`		the document label, must contain at least one between documentId and documentLabel
[config.height]	`String`		the height of iframe, can be put inside iframe object
[config.width]	`String`		the width of iframe, can be put inside iframe object
config.iframe	`Object`		the style object of iframe
[config.iframe.height]	`String`		the height of iframe, can be put outside
[config.iframe.width]	`String`		the width of iframe
[config.iframe.style]	`String`		the style of iframe

Example

execTest9 = function() {
        Sbi.sdk.api.injectQbe({
            datasetLabel: 'DS_DEMO_51_COCKPIT'
            , target: 'qbe'
            , height: '600px'
            , width: '1100px'
            , iframe: {
            style: 'border: 0px;'
          }
        });
    };

api.getDataSetList(config)

It returns the list of datasets

Kind: static method of api

Param	Type	Description
config	`Object`	the configuration
config.callback	`ResponseCallback`	function to be called after the response is returned by the server

Example

execTest6 = function() {
        Sbi.sdk.api.getDataSetList({
            callback: function( json, args, success ) {
                if (success){
                    var str = "";

                    for (var key in json){
                        str += "<tr><td>" + json[key].label + "</td><td>" + json[key].name + "</td><td>" + json[key].description + "</td></tr>";
                    }

                    document.getElementById('datasets').innerHTML = str;
                }
            }});
    };

api.executeDataSet(config)

It executes a dataset

Kind: static method of api

Param	Type	Description
config	`Object`	the configuration
config.documentLabel	`String`	the document label
[config.parameters]	`Object`	the values of dataset parameters
config.callback	`ResponseCallback`	function to be called after the response is returned by the server

Example

execTest7 = function() {
   Sbi.sdk.api.executeDataSet({
    datasetLabel: 'DS_DEMO_EXTCHART'
    , parameters: {
        par_year: 2011,
        par_family: 'Food'
    }
    , callback: function( json, args, success ) {
        if (success){
            var str = "<th>Id</th>";

            var fields = json.metaData.fields;
            for(var fieldIndex in fields) {
                if (fields[fieldIndex].hasOwnProperty('header'))
                    str += '<th>' + fields[fieldIndex]['header'] + '</th>';
            }

            str += '<tbody>';

            var rows = json.rows;
            for (var rowIndex in rows){
                str += '<tr>';
                for (var colIndex in rows[rowIndex]) {
                    str += '<td>' + rows[rowIndex][colIndex] + '</td>';
                }
                str += '</tr>';
            }

            str += '</tbody>';

            document.getElementById('results').innerHTML = str;
        }
        }});
};

sdk.cors : `object`

Kind: static namespace of sdk

.cors : object
- .api : object
  - .getDataSetList(config)
  - .executeDataSet(config)

cors.api : `object`

There are three main advantages on using CORS over jsonp:

all the methods are available while in jsonp only GET request can be done;
if an error occurs it is possible to manage it with CORS, while in jsonp it is only possible to set a timeout;
jsonp has security problems (see later for an example).

Kind: static namespace of cors
See: api

.api : object
- .getDataSetList(config)
- .executeDataSet(config)

api.getDataSetList(config)

It returns the list of datasets. This time config contains two callback functions: callbackOk and callbackError. This is because with CORS it is possible to know when the server returns an error, so we can define the behavior to have if there is an error. However, it is not mandatory to specify the callbackError function: there is a default one that create a pop up with status code and text describing the error.

Kind: static method of api

Param	Type	Description
config	`Object`	the configuration
config.callbackOk	`ResponseCallback`	function to be called after the ok response is returned by the server
[config.callbackError]	`ResponseCallback`	function to be called after the error response is returned by the server

Example

execTest6 = function() {
   Sbi.sdk.cors.api.getDataSetList({
    callbackOk: function(obj) {
        str = '';

        for (var key in obj){
            str += "<tr><td>" + obj[key].label + "</td><td>" + obj[key].name + "</td><td>" + obj[key].description + "</td></tr>";
            }

            document.getElementById('datasets').innerHTML = str;
        }
   });
    };

api.executeDataSet(config)

It executes a dataset. This time config contains two callback functions: callbackOk and callbackError. This is because with CORS it is possible to know when the server returns an error, so we can define the behavior to have if there is an error. However, it is not mandatory to specify the callbackError function: there is a default one that create a pop up with status code and text describing the error.

Kind: static method of api

Param	Type	Description
config	`Object`	the configuration
config.documentLabel	`String`	the document label
[config.parameters]	`Object`	the values of dataset parameters
config.callbackOk	`ResponseCallback`	function to be called after the ok response is returned by the server
[config.callbackError]	`ResponseCallback`	function to be called after the error response is returned by the server

Example

execTest7 = function() {
   Sbi.sdk.cors.api.executeDataSet({
    datasetLabel: 'DS_DEMO_EXTCHART'
    , parameters: {
        par_year: 1998,
        par_family: 'Food'
    }
    , callbackOk: function(obj) {
        var str = "<th>Id</th>";

            var fields = obj.metaData.fields;
            for(var fieldIndex in fields) {
                if (fields[fieldIndex].hasOwnProperty('header'))
                    str += '<th>' + fields[fieldIndex]['header'] + '</th>';
            }

            str += '<tbody>';

            var rows = obj.rows;
            for (var rowIndex in rows){
                str += '<tr>';
                for (var colIndex in rows[rowIndex]) {
                    str += '<td>' + rows[rowIndex][colIndex] + '</td>';
                }
                str += '</tr>';
            }

            str += '</tbody>';

            document.getElementById('results').innerHTML = str;
        }});
};

ResponseCallback : `function`

This callback is called a response is returned by the server.

Kind: global typedef

Param	Type	Description
json	`String`	json of response
args	`Array`
success	`Boolean`	true if it's a success response otherwise false

Javascript SpagoBI API

Same-origin policy

Jsonp vs CORS

Authentication

SDK Javascript reference

Typedefs

Sbi : object

Sbi.sdk : object

sdk.api : object

api.getDocumentHtml(config)

api.injectDocument(config)

api.getWorksheetHtml(config)

api.injectWorksheet(config)

api.getQbeHtml(config)

api.injectQbe(config)

api.getDataSetList(config)

api.executeDataSet(config)

sdk.cors : object

cors.api : object

api.getDataSetList(config)

api.executeDataSet(config)

ResponseCallback : function

Sbi : `object`

Sbi.sdk : `object`

sdk.api : `object`

sdk.cors : `object`

cors.api : `object`

ResponseCallback : `function`