Embedding BusinessQ into your web application

11. December 2017.
Gordan Savanovic
businessq

Hello everyone,

today we present you one of the features of BusinessQ, which is the integration of BusinessQ with other web applications.

BusinessQ helps our partners to quickly create new revenue streams and increase customer retention by embedding reporting, dashboarding and analytics directly into their existing SaaS solutions.

Typical integration of BusinessQ into your web application is when you have BusinessQ installed on your (or client’s) web server.

Technical details

Embedding BusinessQ in your app is simply done through the HTML tag <iframe> so that the src attribute is set as a path to your BusinessQ installations

Options

Single sign-on

Single sign-on (SSO) allows integration of multiple independent systems or applications. Users authenticate with their credentials on a single system, and they can then seamlessly access other connected independent systems without having to authenticate themselves again with the same or different credentials. BusinessQ uses tokens to achieve this integration.

Hiding the menu

This option allows you to hide the BusinessQ menu inside the iframe and together with manipulating iframe src attribute it is possible to navigate through BusinessQ directly from the application that has embedded BusinessQ. Which allows displaying only some parts of BusinessQ to the end user.

Token

The application which integrates BusinessQ will generate the token by encrypting a message with a specific format. It will pass the token to BusinessQ in URL. BusinessQ will, while initializing, read the token from URL, decrypt it and will use decoded message to authenticate the user.

By default, the message used for token generation is a JSON string with the following structure:

{
    “UserInfo”: {
        “UserName”:”email@example.com”
    },
    “RequestDate”:”2017-01-01 12:00:00″
}

“UserName” property contains the identifier unique to each user. BusinessQ will check the value against its repository. This means that every user that should be granted an access to BusinessQ, must be in its repository.

“RequestDate” contains the date and time when the token was generated. It can be represented in any known format. But to avoid uncertainty, especially with different time zones, we recommend using ISO 8601 standard. A token is valid for 1 hour.

Specified JSON should then be encoded using industry standard AES (Advanced Encryption Standard) encryption algorithm in counter (CTR) mode with the key length of 256 bits.

Password/key (and on custom solutions, for example, initialization vector) is stored in BusinessQ repository and can be updated at any time. The binary output of the encryption algorithm is then encoded using Base64 scheme.

An example of a javascript function that generates a token:

function generateToken(message, key){
//Message – JSON string with structure as described above, containing user information
//Key – sso key stored in BusinessQ
var token = Aes.Ctr.encrypt(message, key, 256);
//Aes – javascript library that implements AES
return token;
}

Examples

In order for BusinessQ to be integrated within the external web application, it is necessary to set an iframe HTML tag to the place where BusinessQ will be displayed:

</iframe>

The src attribute contains the path to the BusinessQ installation with the following parameters:

sso- Indicates SSO mode of authentication and its value is always ‘1’. (e.g. sso=1).
menu – if it’s set to ‘0’, the menu inside BusinessQ will not be displayed
token – a token that is generated by an application that integrates BusinessQ in the way described above
all after the ‘#’ sign is part of the navigation within BusinessQ. In this concrete example, it is a report with id 1 displayed in ‘view’ mode (Two basic entities within BusinessQ are reports and dashboards that can be displayed in two modes, edit, and view)

Example – report

HTML:

</iframe>

RESULT:

Example – dashboard

HTML:

</iframe>

RESULT:

Example – with BusinessQ menu displayed

HTML:

</iframe>

RESULT:

We hope that you enjoy using our application and we are trying to make it better every day. For any questions and suggestions contact us on info@qualia.hr.

We are developers of data visualization software BusinessQ. Try it for free and make reports and dashboards that make sense, without chart junk.