Update: added sample codes for .NET InfoView as well as for Java InfoView.  

Introduction

BusinessObjects Enterprise XI 3.1 Service Pack 2 introduces new APIs that a developer may use to extend the usability of Web Intelligence.  Last time, I blogged about the Web Intelligence Calculation Extension Points, an API for creating new custom functions for use in Web Intelligence documents.

In this blog, I'll briefly describe the Web Intelligence Interactive Viewing Extension and Integration Points API.  This link will direct you to a download page, where you can obtain documentation and samples for this API, as well as for the Web Intelligence Java Reporting Panel (JRP) and Rich Client (WRC) Extension Points. 

I previously wrote about the JRC+WRC Extension Points in my blog Integrate Google Maps with the Web Intelligence Rich Client.  Where that extension allows for enhancements to the Java-based JRP and WRC UI, the Interactive Viewing extension allows for enhancements to the DHTML-based Interactive Viewer. 

Both extensions are Innovation Center prototype geared towards OEM/Partner customers for integrating and extending the Web Intelligence Viewers and Editors.  Although full support is provided only for OEM/Partners, the APIs are available without any additional downloads, and the download link for the docs contain an Evaluation License to allow other developers to "check out" the functionality.

The Interactive Viewing extensions consist of JavaScript and HTML code run client-side to add to the viewer UI, and Java or .NET code run server-side to access the ReportEngine SDK (Java or .NET) used in the processing of the document for viewing and editing.  Access to ReportEngine - with its report creation/modification capabilities - means much of the features available in the Interactive Viewer and Editor are accessible through this API.

With this extension, you can programmatically access the structure of the Web Intelligence document being viewed - its  tables, charts, data providers, and even its internal data sets. You can programmatically remove components of the viewer you don't prefer to expose to clients, and add your own - toolbar buttons and "Left Panel" tabbed panes.  You can even integrate components of the viewer into your own custom web application.

Let's walk through a simple code example that uses this extension - I'll integrate Google Maps into the Interactive Viewer.

Integrating Google Maps - A Walkthrough

Here's a screenshot of the results:

When you click on the "G" button in the toolbar, a JavaScript callback function invokes a JSP page, that invokes ReportEngine to introspect the Data Provider of the Web Intelligence document.  It seeks out columns named "City" and "State", then dynamically creates JavaScript for creation of a Combo Box selection control in a pop-up dialog box.  The Combo Box is filled with all the City+State values and selection of a value posts back to a JSP page that invokes JavaScript using the Google Maps API to display the location of the selected City + State.

Installation of XI 3.1 Service Pack 2

To use the Interactive Viewer extensions, you must have BusinessObjects Enterprise XI 3.1, and you must install Service Pack 2 on top of it.

Modification of the webiviewer.properties file

In the Java Web Application AnalyticalReporting, open the file AnalyticalReporting/WEB-INF/classes/webiviewer.properties file, and set the "ALLOW_CUSTOMIZATION" property to equal "yes".  This enables the DHTML extensions.

Modification of the user.js file

An Extension Point customization is declared and triggered by addition of JavaScript code to the file AnalyticalReporting/viewers/cdz_adv/user.js.  Here is the user.js file I use:

user.js
user_extension("MENUBAR", { title: "Google Maps", iconURL: "customize/samples/Menu_Bar/google_maps_icon.png", align: "right", targetPage: "customize/samples/Menu_Bar/googleMaps.jsp", appendViewerContextParameters: true, targetWindow: "popupWindow", width: 600, height: 400 });

This file specifies that this extends the Toolbar ("MENUBAR") by addition of a button, where the button image may be found at AnalyticalReporting/viewers/cdz_adv/customize/samples/Menu_Bar/google_maps_icon.png (I just downloaded Google's icon, trimmed and resized to fit on the toolbar).  Clicking on the button pops up a "popupWindow" of size 600x400, where the pop-up window calls back to the JSP page AnalyticalReporting/viewers/cdz_adv/customize/samples/Menu_Bar/googleMaps.jsp.  The Interactive Viewer context - including such info ass the ReportEngine document  storage token - is configured to be appended to the postback to googleMaps.jsp as HTTP GET parameters.

Create the postback Java Server Page

I made just a few modifications to the Yahoo! Financial sample code found in the documentation+sample download linked above to create this JSP page. The googleMaps.jsp page is given here (please Select All Ctrl-A then Copy Ctrl-C, and then Paste Ctrl-V to a text editor, for ease of reading).

googleMaps.jsp
<%@ include file="wistartpage.jsp" %><% /* * The wistartpage.jsp may be found in the Interactive Viewer, * or may be found in the sample codes download for * the Interactive Viewer Extension Points. */ response.setDateHeader("expires", 0); response.setContentType("text/html;charset=UTF-8"); String googleMapsKey = "ABQIAAAAu2aQyV4OmJpQAJVeja2y-RS_2V8IisG8E4u638zv2gfp-EG4_BTDjvyfkm4hLigJxbaFPo24vjrE_A"; %> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <style type="text/css"> .titlezone { color:#375487; font-family:"arial","sans-serif"; font-size:11px; font-weight:bold; } </style> <script type="text/javascript" src="../../webiIntegration.js"></script> <script type="text/javascript"> data = new Array(); <% try { String sEntry; DocumentInstance documentInstance; DataProviders dataProviders; /* * Retrieve ReportEngine document representation using the * storage token saved to parameter 'sEntry'. */ sEntry = requestWrapper.getQueryParameter("sEntry", true); documentInstance = reportEngines.getDocumentFromStorageToken(sEntry); /* * Retrieve the Data Provider, and record all data under columns named 'City' or 'State'. */ dataProviders = documentInstance.getDataProviders(); for(int i = 0, m = (dataProviders == null ? 0 : dataProviders.getCount()) ; i < m ; i++) { DataProvider dataProvider; dataProvider = dataProviders.getItem(i); for(int j = 0, n = dataProvider.getFlowCount() ; j < n ; j++) { Recordset recordset; recordset = dataProvider.getResult(j); int cityIndex = -1; int stateIndex = -1; for(int k = 0, p = (recordset == null ? 0 : recordset.getColumnCount()) ; k < p ; k++) { if("City".equals(recordset.getColumnName(k)) && String.class.equals(recordset.getColumnType(k))) { cityIndex = k; } else if("State".equals(recordset.getColumnName(k)) && String.class.equals(recordset.getColumnType(k))) { stateIndex = k; } } /* * Write JavaScript array element for each location - one for display, and another URLEncoded * used for passing the values to maps.jsp */ if((cityIndex >= 0) || (stateIndex >= 0)) { for(int l = 0 ; l < 50 ; l++) { // Max 50 results. out.println("data[" + l + "] = new Array(2)"); try { String location = ""; if(cityIndex >= 0) { location += recordset.getCellObject(cityIndex).toString(); } if(stateIndex >= 0) { if(cityIndex >= 0) { location += ", "; } location += recordset.getCellObject(stateIndex).toString(); } out.println("data[" + l + "][0] = \"" + ViewerTools.escapeQuotes(location) + "\";"); out.println("data[" + l + "][1] = \"" + java.net.URLEncoder.encode(location, "UTF-8") + "\";"); if(recordset.isLast()) { break; } recordset.next(); } catch(Exception eek) { break; } } } } } %> function comboCB(o) { var index = o.selectedIndex; document.getElementById("googleMapsFrame").src = "maps.jsp?location=" + data[index][1]; } function loadPage() { popupIntegration.setTitle("Google Maps"); // Fill combobox var combo = document.myForm.comboLocation; for (var i=0; i<data.length; i++) { combo.options[i] = new Option(data[i][0], data[i][0]); } combo.selectedIndex = 0; comboCB(combo); } </script> </head> <body class="dialogzone" onload="setTimeout('loadPage()',1)" style="margin:0px;padding:0px"> <form name="myForm" method="post"> <table border="0" cellspacing="0" cellpadding="2"> <tr style="padding-top:7px;padding-bottom:7px;background-color:#E4E4EC;"> <td class="titlezone" width="7%"><nobr>Location</nobr></td> <td> <select name="comboLocation" size="1" onchange="comboCB(this);"> </select> </td> </tr> <tr> <td colspan="2"> <iframe id= "googleMapsFrame" frameborder="0" style="left:0px;top:0px;border-width:0px;width:900px;height:800px;" marginWidth=0 marginHeight=0 src=""></iframe> </td> </tr> </table> </form> </body> </html> <% } catch(Exception e) { e.printStackTrace(); out.println("<script language=\"javascript\">"); out.println("if (popupIntegration)"); out.println(" popupIntegration.displayErrorMessage(\"" + ViewerTools.escapeQuotes(e.getLocalizedMessage()) + "\")"); out.println("</script>"); out.println("</body></html>"); } %>

This page retrieves the document storage token from the HTTP Request, then retrieves the Web Intelligence document being displayed in the viewer via the ReportEngine.  It then introspects the Data Provider for City+State data, and generates HTML with JavaScript that creates a Combo Box with the location data.

The JavaScript function comboCB then calls back to the JSP page AnalyticalReporting/viewers/cdz_adv/customize/samples/Menu_Bar/maps.jsp with the location appended as a HTTP Get parameter whenever a selection is made.

Create the Google Maps API page

The maps.jsp contains the Google Maps API JavaScript code:

maps.jsp
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml"> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"/> <title>Google Maps</title> <!-- Make sure you get your own Google Maps API key for your own domain --> <script src="http://maps.google.com/maps?file=api&amp;v=2&amp;key=ABQIAAAAu2aQyV4OmJpQAJVeja2y-RS_2V8IisG8E4u638zv2gfp-EG4_BTDjvyfkm4hLigJxbaFPo24vjrE_A" type="text/javascript"></script> <script type="text/javascript"> var map = null; var geocoder = null; function initialize() { if (GBrowserIsCompatible()) { map = new GMap2(document.getElementById("map_canvas")); map.setUIToDefault(); geocoder = new GClientGeocoder(); } } function showAddress(address) { if (geocoder) { geocoder.getLatLng( address, function(point) { if (!point) { alert(address + " not found"); } else { map.setCenter(point, 15); } } ); } } </script> </head> <body onload="initialize(); showAddress('<%= java.net.URLDecoder.decode(request.getParameter("location"), "UTF-8") %>');" onunload="GUnload()"> <form action="#" onsubmit="showAddress(this.address.value); return false"> <div id="map_canvas" style="width: 600px; height: 400px"></div> </form> </body> </html>

This merely retrieves the location information from the HTTP Request, then triggers a JavaScript client-side that invokes Google Maps, geolocates the position, then centers the map around that position.  Note that the "key" code in this page is tied to my domain - you'll have to go to the Google Maps API site, and generate a key for your own domain.

Create a Web Intelligence document with City and State columns in the Query

Now, create a Web Intelligence document off of the eFashion Universe, where you include the Store City and Store State objects in the Query.  Restart your Java Web Application Server, flush cache on your web browser (to ensure you're retrieving the modified JavaScript files), log onto Java InfoView, ensure you've configured your User Preferences for the Interactive Viewer and Editor, and navigate to the Web Intelligence doc you've just created. 

.NET InfoView Samples Codes

Here I'll present equivalent sample code files for .NET InfoView. First, you enable the Interactive Viewer Extension Point by editing the file:

    <Enterprise INSTALL>\Web Content\InfoViewApp\AnalyticalReporting\Web.config

and setting WebiSettings ALLOW_CUSTOMIZATION to "yes".

The JavaScript file

    <Enterprise INSTALL>\Web Content\InfoViewApp\AnalyticalReporting\Viewer\customize\user.js

is modified to point to the ASPX files deployed to the folder

    <Enterprise INSTALL>\Web Content\InfoViewApp\AnalyticalReporting\Viewer\customize/samples/Menu_Bar/

where the files are:

user.js
user_extension("MENUBAR", { title: "Google Maps", iconURL: "customize/samples/Menu_Bar/google_maps_icon.png", align: "right", //left, right targetPage: "customize/samples/Menu_Bar/googleMaps.aspx", appendViewerContextParameters: true, targetWindow: "popupWindow", //inPlace, dialogBox, popupWindow, customView width: 600, height: 400 });

googleMaps.aspx
<%@ Page language="c#" AutoEventWireup="false" %> <%@ Import namespace="BusinessObjects.ReportEngine" %> <% Response.Expires = 0; %> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <style type="text/css"> .titlezone { color:#375487; font-family:"arial","sans-serif"; font-size:11px; font-weight:bold; } </style> <script type="text/javascript" src="../../webiIntegration.js"></script> <script type="text/javascript"> // Data headers header = new Array(); // Data values data = new Array(); <% ReportEngines reportEngines; string sEntry; IDocumentInstance documentInstance; string[] header = null; IDataProviders dataProviders; /* * Retrieve Web Intelligence document instance using storage token. */ reportEngines = (ReportEngines)Session["ReportEngines"]; sEntry = Request.QueryString.Get("sEntry"); documentInstance = reportEngines.getDocumentFromStorageToken(sEntry); dataProviders = documentInstance.DataProviders; for(int i = 0, m = (dataProviders == null ? 0 : dataProviders.Count) ; i < m ; i++) { IDataProvider dataProvider; dataProvider = dataProviders[i]; for (int j=0, n = dataProvider.FlowCount ; j < n ; j++) { IRecordset recordset; int cityIndex = -1; int stateIndex = -1; recordset = dataProvider.GetResult(j); for(int k = 0, p = (recordset == null ? 0 : recordset.ColumnCount) ; k < p ; k++) { if("City".Equals(recordset.ColumnName(k)) && typeof(String).Equals(recordset.ColumnType(k))) { cityIndex = k; } else if("State".Equals(recordset.ColumnName(k)) && typeof(String).Equals(recordset.ColumnType(k))) { stateIndex = k; } } if((cityIndex >= 0) || (stateIndex >= 0)) { for(int l = 0 ; l < 50 ; l++) { // Max 50 results. Response.Write("data[" + l + "] = new Array(2);"); try { String location = ""; if(cityIndex >= 0) { location += recordset.GetCellObject(cityIndex).ToString(); } if(stateIndex >= 0) { if(cityIndex >= 0) { location += ", "; } location += recordset.GetCellObject(stateIndex).ToString(); } Response.Write("data[" + l + "][0] = \"" + location + "\";"); Response.Write("data[" + l + "][1] = \"" + HttpUtility.UrlEncode(location) + "\";"); if(recordset.IsLast) { break; } recordset.Next(); } catch(Exception eek) { break; } } } } } %> function comboCB(o) { var index = o.selectedIndex; document.getElementById("googleMapsFrame").src = "maps.aspx?location=" + data[index][1]; } function loadPage() { popupIntegration.setTitle("Google Maps"); // Fill combobox var combo = document.myForm.comboLocation; for (var i=0; i<data.length; i++) { combo.options[i] = new Option(data[i][0], data[i][0]); } combo.selectedIndex = 0; comboCB(combo); } </script> </head> <body class="dialogzone" onload="setTimeout('loadPage()',1)" style="margin:0px;padding:0px"> <form name="myForm" method="post"> <table border="0" cellspacing="0" cellpadding="2"> <tr style="padding-top:7px;padding-bottom:7px;background-color:#E4E4EC;"> <td class="titlezone" width="7%"><nobr>Location</nobr></td> <td> <select name="comboLocation" size="1" onchange="comboCB(this);"> </select> </td> </tr> <tr> <td colspan="2"> <iframe id= "googleMapsFrame" frameborder="0" style="left:0px;top:0px;border-width:0px;width:900px;height:800px;" marginWidth=0 marginHeight=0 src=""></iframe> </td> </tr> </table> </form> </body> </html>

maps.aspx
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <%@ Page language="c#" AutoEventWireup="false" %> <%@ Import namespace="BusinessObjects.ReportEngine" %> <% Response.Expires = 0; %> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml"> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"/> <title>Google Maps</title> <script src="http://maps.google.com/maps?file=api&amp;v=2&amp;key=ABQIAAAAu2aQyV4OmJpQAJVeja2y-RS_2V8IisG8E4u638zv2gfp-EG4_BTDjvyfkm4hLigJxbaFPo24vjrE_A" type="text/javascript"></script> <script type="text/javascript"> var map = null; var geocoder = null; function initialize() { if (GBrowserIsCompatible()) { map = new GMap2(document.getElementById("map_canvas")); map.setUIToDefault(); geocoder = new GClientGeocoder(); } } function showAddress(address) { if (geocoder) { geocoder.getLatLng( address, function(point) { if (!point) { alert(address + " not found"); } else { map.setCenter(point, 15); } } ); } } </script> </head> <body onload="initialize(); showAddress('<%= HttpUtility.UrlDecode(Request.QueryString.Get("location")) %>');" onunload="GUnload()"> <form action="#" onsubmit="showAddress(this.address.value); return false"> <div id="map_canvas" style="width: 600px; height: 400px"></div> </form> </body> </html>

Summary

With a couple of pages of code, I was able to create a very simple Proof-of-Concept that integrates Google Maps into the Interative Viewer.  There's certainly room for improvements, of course!  I'll leave that up to you...

Next time, I'll blog about the Web Intelligence Custom Data Provider Plugins, another very exciting API new with Service Pack 2.