Knowage Javascript API
Knowage SDK contains a Javascript API that helps users to embed parts of Knowage suite inside a web page or to retrieve information 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 Knowage SDK in a different origin from the Knowage server the browser will not let your script to communicate with Knowage.
There are two types of functions in Knowage SDK: 1. iFrame injection: they inject a Knowage page inside an iFrame 2. REST services: they use REST services of Knowage 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 Knowage 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 Knowage SDK functions the user has to be authenticated. If the user is already authenticated in Knowage 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
Sbi.sdk : object
Kind: static namespace of Sbi
- .sdk :
object
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: '/knowage/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 |
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 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 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
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.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 |