Working with Indicee Elements

(1)

Working with Indicee Elements

(2)

Embed Indicee Elements into your Web Content

3 Single Sign-On (SSO) using SAML

3

Configure an Identity Provider for SSO 4

Add your Identity Provider Information to the Indicee Administration Tool 5

Actions and Options

5 Create a Report

7 View a Report

8 Edit a Report

8 Create a Dashboard

9 View a Dashboard

10 Edit a Dashboard

10 View the Landing Page

11 Navigation Events

11 Error and Session Timeout Handling

12

(3)

Embed Indicee Elements into your Web Content

This document is for developers who want to use the Indicee Elements JavaScript API to integrate Indicee business intelligence content into their own static web pages or dynamic web applications. Indicee Elements support Single Sign-On using SAML.

Indicee’s main UI elements: the report writer, report viewer and the dashboard system are directly embeddable into external content or applications. This makes it easy to use the Indicee Platform to quickly add report and dashboard elements to your own application. Indicee supports the embedding of Elements directly into web content, similar to the way in which Google Maps may be included on a page.

The following Indicee Elements can be used: • Report Viewer

The basic report viewer that displays a given Indicee report that has been pre-authored and saved.

• Report Writer

The report authoring environment for performing ad hoc analysis or creating new reports. This includes the report rendering area, the Question Panel and other configuration and options panels.

• Dashboard Viewer

The dashboard viewer. This can load and display Dashboard documents that have been pre-authored and saved.

• Dashboard Writer

The dashboard authoring environment.

Single Sign-On (SSO) using SAML

Basic authentication is used if you just serve the HTML page to a browser. This will result in the user being prompted for their Indicee login credentials (unless this information has already been cached).

(4)

After the user has been authenticated, the Indicee Elements content that is embedded in the page is loaded and displayed.

Indicee Elements provides the hooks necessary for you to control the acquisition of Indicee credentials for authentication so that the automatic login dialog can be avoided. Indicee Elements also supports Single Sign-On (SSO) using SAML.

It is optional, but highly recommended, that you configure single sign-on (SSO). Configuring single sign-on lets users connect to the Indicee Elements automatically, without having to log into it separately. Indicee provides Single Sign-On (SSO) using the SAML standard. SAML allows you to provide a token that Indicee trusts that will indicate that the user has

authenticated (and which Indicee account is to be used for the logged-in user). In this way, your own web authentication mechanisms can be used and Indicee Elements can be embedded in pages without any further need to prompt the user for credentials.

Configure an Identity Provider for SSO

To configure an identity provider, refer to the documentation for that identity provider. Within your third-party identity provider, enter the information for Indicee. The information is as follows:

Name: Indicee

ACS URL: https://secure.indicee.com/elements/elements.jsp

Entity Id: https://secure.indicee.com/elements/elements.jsp

The information you need to set up your identity provider in Indicee is:

• Provider URL: This is the URL that Indicee will do an HTTP POST to in order to authorize a user.

• Provider Certificate: This is a certificate to access the identity provider that is encrypted using the X.509 standard. This information is usually contained in a metadata file that is created by the identity provider. Save this certificate file to your computer.

(5)

Add your Identity Provider Information to the Indicee Administration Tool

To open the Indicee administration tool:

1. In a web browser, type the URL for the Indicee administration tool. This will be the URL that you normally use to access the Indicee web application with “/admin” added to the end of it. It might look something like this: “http://secure.indicee.com/admin”.

After you sign in, the Indicee Administration page is displayed. It shows all of the

organizations or parts of organizations and their users for which you have administrative rights.

Note: To use the web-based Indicee administration tool, your user account must have been granted administration rights to your organization’s account hierarchy or a part of it. 2. Click the Single Sign-On tab.

3. Click the Add a new identity provider button at the top of the list of identity providers. 4. In the Domain field, type any unique name. It will be used as the reference of the new

identity provider.

5. In the Provider URL field, type the SP-initiated POST endpoint of the identity provider. This is the URL that Indicee will send an HttpPost request to in order to get the credentials of the user.

6. In the Provider Certificate field, copy and paste the identity provider’s certificate that you saved to your computer earlier. It must begin with "---BEGIN CERTIFICATE---" and end with "---END CERTIFICATE---".

7. Click Save.

Actions and Options

The following actions are supported: • viewReport • editReport • createReport • viewDashboard • createDashboard • editDashboard • viewLandingPage

To integrate Indicee Elements into your pages, add <script> tags to fetch the API code from Indicee's servers and add JavaScript code to your page to make calls on the Elements API's

(6)

interfaces to request content to be displayed within your page. Indicee Elements works by embedding JavaScript into your web page that modifies a specific DIV element in the page so that it will display the required Indicee Element. When your page is displayed in a user’s browser, this script is executed and after the user has been authenticated by Indicee, the appropriate content is fetched and displayed. The sequence of events is as follows: 1. The browser fetches your page

2. The browser fetches Elements JavaScript 3. Elements API authenticates Indicee user

4. Elements API fetches requested Indicee content

Indicee identifies reports in the system using a qualified name (IQN) which is our own URI format. To obtain the qualifiedName for a given report, look at the URL bar while using the Indicee application. The report_id parameter in the URL is the "qualifiedName" to use.

For example, with the following URL:

https://secure.indicee.com/?#home/mystuff/report?report_id=iqn.2://indicee.com/1491/0/ report/28d8e0f3-41a5-4b9c-8b8d-7bac71a8ae56

The "qualifiedName" would be:

(7)

Create a Report

<!DOCTYPE html> <html>

<head>

<script type="text/javascript"

src="https://secure.indicee.com/elements/elements_api.js"> </script>

var x = new indicee.elements.Element(document.getElementById("el_canvas"), {

action: "createReport" });

} </script> </head>

<body onload="initialize()" style="font-family: sans-serif"> <h1>My Elements Application</h1>

<div id="el_canvas"

style="position: absolute; left: 20px; top: 80px; right: 20px; bottom: 20px; border: 1px solid #808080">

</div> </body> </html>

(8)

View a Report

<head>

action: "viewReport", qualifiedName: "iqn.2://indicee.com/1491/0/report/ 28d8e0f3-41a5-4b9c-8b8d-7bac71a8ae56" }); } </script> </head>

<div id="el_canvas"

style="position: absolute; left: 20px; top: 80px; right: 20px; bottom: 20px; border: 1px solid #808080"> </div> </body> </html>

Edit a Report

<!DOCTYPE html> <html> <head>

action: "editReport", qualifiedName: "iqn.2://indicee.com/1491/0/report/ 28d8e0f3-41a5-4b9c-8b8d-7bac71a8ae56" }); } </script> </head>

<div id="el_canvas"

(9)

Create a Dashboard

<head>

action: "createDashboard" });

} </script> </head>

<div id="el_canvas"

(10)

View a Dashboard

<head>

action: "viewDashboard", qualifiedName: "iqn.2://indicee.com/1491/0/compositereport/ 6d2df1ef-326b-4027-98c9-7e84446edbfc" }); } </script> </head>

<div id="el_canvas"

style="position: absolute; left: 20px; top: 80px; right: 20px; bottom: 20px; border: 1px solid #808080"> </div> </body> </html>

Edit a Dashboard

<!DOCTYPE html> <html> <head>

action: "editDashboard", qualifiedName: "iqn.2://indicee.com/1491/0/compositereport/ 6d2df1ef-326b-4027-98c9-7e84446edbfc" }); } </script> </head>

<div id="el_canvas"

(11)

View the Landing Page

Displays whatever dashboard has been set up at the user's "landing page" using the administration console.

<head>

action: "viewLandingPage" });

} </script> </head>

<div id="el_canvas"

Navigation Events

The options object supports a field "navigationCallback" which contains a function which takes one argument. The function will be invoked when users click on navigation elements within dashboards, with an object argument describing the navigation.

<!DOCTYPE html> <html> <head> <script type="text/javascript" src="https://secure.indicee.com/elements/elements_api.js"> </script> <script type="text/javascript"> function initialize() {

var x = new indicee.elements.Element(document.getElementById("el_canvas"), { action: "viewDashboard",

qualifiedName: "iqn.2://indicee.com/1491/0/compositereport/ 6d2df1ef-326b-4027-98c9-7e84446edbfc",

navigationCallback: function (navData) {

alert("Navigation: " + navData.type + " " + navData.qualifiedName); }

}); } </script> </head>

<div id="el_canvas"

(12)

In the sample code, navData.type describes the type of the target object ("dashboard" or "report".) The qualifiedName field contains the qualified name of the target. It is up to the containing application to implement the handling of this navigation by using other Elements API calls to open the target for the user.

Error and Session Timeout Handling

Errors and timeouts cause events to be raised which can be caught by callbacks supplied in the Elements "options" map. The client code can deal with the error in any way it sees fit. For example, this allows an Element to be easily reloaded if the session times out. This is

particularly useful for applications using SAML because if the user is still has a valid session in the client application, the reload API will transparently re-login the user to Indicee via SAML. However, the user will lose their session state at indicee.

The callbacks are as follows:

• sessionErrorCallback(msg) - receives notification of session errors

msg.sessionErrorType: one of sessionTimeout, unavailable, authorization, service • errorCallback(msg) - receives notification of application errors

msg.errorType: one of browser, server, requestTimeout

msg.userRef: error user reference (i.e UUID for throwable_report table.) msg.className: exception classname

msg.message: error message

The new reload API can be invoked as follows: var element = new Element(...);

...

element.reload();

"this" is now bound on the element for which the callback is being invoked - i.e the callbacks passed in essentially become methods on the element. This means you can now write: indicee.elements.setGlobalOptions({ sessionErrorCallback: function() { this.reload(); }, ... });

The "reload" and "remove" functions have also now been exported in the indicee.elements namespace, so you can shortcut this further to:

indicee.elements.setGlobalOptions({

sessionErrorCallback: indicee.elements.reload, ...

});

(13)

Global Options

If you are using more than one instance of Indicee Elements and want to set common options, use setGlobalOptions, which will affect all instances running in the current window. This should be done before any Element instances are created. Options specified in the Element

constructor override those specified by setGlobalOptions. Here are some examples: indicee.elements.setGlobalOptions({

username: "[email protected]", password: "Passw0rd" }); indicee.elements.setGlobalOptions({