Working with Indicee Elements

Transcription

1 Working with Indicee Elements How to Embed Indicee in Your Product 2012 Indicee, Inc. All rights reserved. 1

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 Global Options Indicee, Inc. All rights reserved. 2

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) Indicee, Inc. All rights reserved. 3

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 Indicee, Inc. All rights reserved. 4

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: 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 2012 Indicee, Inc. All rights reserved. 5

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: "iqn.2://indicee.com/1491/0/report/28d8e0f3-41a5-4b9c-8b8d-7bac71a8ae56" 2012 Indicee, Inc. All rights reserved. 6

7 Create a Report action: "createreport" ); 2012 Indicee, Inc. All rights reserved. 7

8 View a Report action: "viewreport", qualifiedname: "iqn.2://indicee.com/1491/0/report/ 28d8e0f3-41a5-4b9c-8b8d-7bac71a8ae56" ); Edit a Report action: "editreport", qualifiedname: "iqn.2://indicee.com/1491/0/report/ 28d8e0f3-41a5-4b9c-8b8d-7bac71a8ae56" ); 2012 Indicee, Inc. All rights reserved. 8

9 Create a Dashboard action: "createdashboard" ); 2012 Indicee, Inc. All rights reserved. 9

10 View a Dashboard action: "viewdashboard", qualifiedname: "iqn.2://indicee.com/1491/0/compositereport/ 6d2df1ef-326b c9-7e84446edbfc" ); Edit a Dashboard action: "editdashboard", qualifiedname: "iqn.2://indicee.com/1491/0/compositereport/ 6d2df1ef-326b c9-7e84446edbfc" ); 2012 Indicee, Inc. All rights reserved. 10

11 View the Landing Page Displays whatever dashboard has been set up at the user's "landing page" using the administration console. action: "viewlandingpage" ); 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. action: "viewdashboard", qualifiedname: "iqn.2://indicee.com/1491/0/compositereport/ 6d2df1ef-326b c9-7e84446edbfc", navigationcallback: function (navdata) { alert("navigation: " + navdata.type + " " + navdata.qualifiedname); ); 2012 Indicee, Inc. All rights reserved. 11

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,... ); Currently both sessionerrorcallback and errorcallback default to "do nothing". The timeout handler does not default to "reload". If you are using SAML, you might want to reload automatically Indicee, Inc. All rights reserved. 12

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: password: "Passw0rd" ); indicee.elements.setglobaloptions({ url: "https://secure.indicee.com/elements/elements.jsp" ); 2012 Indicee, Inc. All rights reserved. 13