Integrating OBIEE and Portal has been tricky due the lack of publicly available OBIEE documentation on the HtmlViewService, therefore, I wanted to write this post to describe the implementation of an OBIEE Chart portlet and provide a sample implementation.   I will cover some of the lessons learned and provide solutions to issues discovered during implementation.

This document only covers the portlet code for displaying an OBIEE report and does not cover the creation of OBIEE reports.

Your implementation may differ depending on your business requirements, however, this article and sample provided should provide a good foundation for your development efforts.

You can download the sample code here.

Prerequisites

This project was built using the following technologies:

• Java version:  1.6
• IDE:  Eclipse with Web Tools Platform 3.1.1
• Portal Server:  Liferay 5.2.3 on Tomcat 6.0
• Portlet:  Spring (version 3.0.2) MVC JSR 286 using Annotations
• OBIEE version:  10.1.3.4

NOTE:  In our development environment, the communication to the OBIEE server was via https and the OBIEE server was using a self signed certificate.  Java will not allow communication via web services to a non-trusted source (not a trusted third-party certificate), therefore, we used jssecacerts to create a trust certificate.

Chart Portlet Requirements

Below are the requirements of this sample application:

1. Allow multiple Chart portlets to be placed on the same page.  Portlets of this type are called “Instanceable” and allowing this capability is configured through the portlet deployment descriptors.   For Liferay, this is defined in liferay-portlet.xml:
   
2. Only support IE and Firefox browsers.  This is really an OBIEE restriction because according to official OBIEE documentation, OBIEE does not support all of the browsers that the portal supports.  The following was taken from the “System Requirements and Supported Platforms for Oracle Business Intelligence Suite Enterprise Edition” document published by Oracle:
   
3. Our requirement was to give the user a warning or error depending on the following:
   – If the browser type is not supported by OBIEE, the user will be given a message stating that their browser is not supported and the Chart/Report will not be displayed.
   ○   This component only supports Microsoft Internet Explorer and Firefox browsers.- If the browser version is higher than supported by OBIEE, the user will be given a warning stating their browser version is not supported and that they may experience issues with the generated chart and the Chart/Report will be displayed.
   ○   This component officially supports Microsoft Internet Explorer version 6.x and 7.0 and Firefox 1.5x and 2.0.  You may experience issues while viewing the report/chart.
4. Impersonate the authenticated user from portal in OBIEE.  This allowed OBIEE to ensure authorization within the reports, however, it requires that Portal and OBIEE share the same LDAP user repository.  The HtmlViewService provides an alternative to this that will be detailed in the “Portlet Technical Details” section below if you do not need this ability.
5. Prevent multiple OBIEE user sessions being created by storing the OBIEE session in the Portal session.  Since the lifetime of the sessions may not be the same, we perform a check to ensure that the OBIEE Session is still active before calling the OBIEE Chart and create a new session if needed.  Detailed information on the implementation will be covered in the “Portlet Technical Details” section below.
6. Let all users configure the portlets, however, this is not recommended and should be restricted since all users see the configuration changes when they are made.  You can extend the functionality of the provided sample to add this functionality.
7. Implement OBIEE Bridge Security – In order to prevent the bridge from serving content from other servers within the network, the bridge will only allow urls targeted to the configured OBIEE server endpoint.

Other suggested areas for improvement would be to localize all labels and error messages as well as the reports generated by passing the country and language.

Not Included

The OBIEEChartSample.war does not include the needed code for calling the OBIEE HtmlViewService due to security issues, however, I will walk you through creating this project in the “Portlet Technical Details” section below.  You must obtain the saw.wsdl file from your OBIEE server in order to generate the needed client.

High Level Overview

The following diagram depicts the high level overview of the provided solution:

1. The browser requests the Portal page with the OBIEE Chart portlet.
2. The OBIEE Chart portlet calls the HtmlViewService web service with the browser type and bridge url information.
3. The HtmlViewService takes the browser type and bridge url information and dynamically returns the HTML for the specified browser type and bridge url.  The bridge url is used to point all resource requests (iframe, css, js, images, etc.) through the bridge.
4. The HTML is returned with the portal page and portlet code to the browser.
5. The browser receives the page and portlet with the HTML from OBIEE and retrieves the additional resources via the bridge.
6. The bridge will proxy the call to the OBIEE server.
7. The OBIEE server will deliver the additional HTML for the iframe and all image, css, and javascript resources to the bridge.
8. The bridge will deliver the requested information to the browser in order to prevent cross browser scripting errors in the javascript and will appear to be serving all resources from the Portal server.

How the Portlet Works

The following diagram depicts a simplified view of the portlet screens and logic flow:

Portlet Technical Details

OBIEEChartSample.war – Portlet Project with Dependencies

The portlet project is created as a Dynamic Web Project in Eclipse and has been saved with source included.  This project requires another java project with the code generated from the saw.wsdl that will be provided by your OBIEE administrator (see details below for creating the dependent project).  After the dependent project is created, add the project as a Java EE Module Dependency so that the build path is updated and the java project (OBIEEWebServiceClient.jar) will be included when you create the OBIEEChartSample.war.

Dependent Project – OBIEEWebServiceClient.jar

1. Create the java project by selecting File/New/Other…/Java Project:
   
2. Enter the name OBIEEWebServiceClient in the Project Name field and click Finish:
   
3. Import saw.wsdl into the project:
   
4. In order to prevent future issues with the generated code and namespacing, double click on the saw.wsdl and copy the namespace (you will use this when generating the client):
   
5. Right click on the saw.wsdl and choose Web Services/Generate Client:
   
   Click Next on the first screen:
   
   Choose the option to Define custom mapping for namespace to package, then click Next:
   
   Click Add and paste the namespace (previously copied) into the namespace column, then paste it again into the package column and replace the / with . in the package column, then click Finish.  Note:  If your server is using a self signed certificate then you must create the certificate trust before clicking Finish.   We used jssecacerts to create the trust certificate:
   
   When complete your project will look as follows:
   
6. Add this project as a Java EE Module Dependency to the OBIEEChartSample project by right clicking on the OBIEEChartSample project, then clicking Properties:
   
7. Now the code should compile without errors.

Code Walkthrough

This article assumes that you have some Java and portlet programming experience and is not going to cover how to create a portlet using Spring MVC or discuss general Java or portlet programming.  I am going to point out the tricky areas of the API that enabled us to meet our business requirements.  The remainder of the provided code has proven to be a solid implementation using the API, however, your requirements might necessitate a different implementation.

OBIEEChartSample Project Package Structure

The sample project is a war file with source included and has been renamed to a .zip extension due to restrictions by the blog.  You can download the sample code here.

Revolutionize Your Business With Generative AI

From product design and software development to virtual agents, content creation, and reporting, GenAI is transforming business. Our AI experts help you unlock GenAI’s full potential and drive growth.

Let’s Get Started

There are three primary classes and many supporting classes.  The three primary classes are as follows:

• com.perficient.sample.portlet.ObieeController – Contains the controller for the Chart portlet.
• com.perficient.sample.portlet.SharedObieeController – Contains core OBIEE logic and is structured for reusability.
• com.perficient.sample.servlet.ObieeBridge – A servlet that contains the logic for the bridge.

ObieeController

The ObieeController is called when the portlet has been requested for render and the method that is run depends on the annotation on the method.  The method that has the annotation @RequestMapping will be the default method and will perform pre-processing, then return the named page.

The default method for this sample application is the retrieveChart(…) method.  Upon first run of the portlet instance, this method will get the portlet preferences previously saved and it will check to make sure that it has been configured.  If it has not been configured a message will be displayed to the user letting them know that it must be configured.   Once configured, this method will call the getReportHtml method in the SharedObieeController (see details below) passing it request, chart path, and parameter list.

The html from the error or call to getReportHtml will be added to the reportHtml attribute and return the obiee/analyticsReport.jsp for display to the user.

SharedObieeController

The SharedObieeController is the main reason for this article and it contains all of the logic for calling OBIEE.  It has been broken into a separate class so that it can be reused by other portlets in the future (for instance a reporting portlet).  Most of the code is self explanatory and I have included comments within the code, so I am only going to focus on the overall flow and important items.

The getReportHtml method is the primary method of this class and will call other methods within the class.

You will need to supply the following information before using this portlet:

public static String SERVICE_END_POINT=”https://your.endpoint.com/analytics”;

private static String SERVICE_USER_NAME=”AdministratorUserName”;

private static String SERVICE_USER_PASSWORD=”AdministratorPassword”;

private static String IMPERSONATE_USER_NAME=”impersonate.user@yourdomain.com”;

Note:  Impersonation will require that your Liferay server and OBIEE server are using the same user repository.

Here are the important pieces of this method:

• Line 48:
  String ua = httpReq.getHeader(“User-Agent”);
  • Importance:  Will be used to determine if it a supported browser and type on lines 50 & 55.  Will be passed to OBIEE so that it can dynamically deliver the css and javascript for the appropriate browser on line 84:
    sessionparams.setUserAgent(ua);
• Line 64:
  String portletId= “_” + portletDisplay.getInstanceId();
  • Importance:  Our requirement was to allow multiple portlets per page and we need to ensure that the javascript generated by OBIEE does not conflict between portlets.  In order to accomplish this we must get a unique id for each portlet, so we are just going to use the instance id from Liferay.  This instance id is going to be prepended to the javascript variables generated by OBIEE and will prevent javascript conflicts, however, sometimes the instance id will begin with a number which is illegal in javascript, so we must prepend an underscore to the id in order to prevent this from happening.  The OBIEE API provides a way to pass this into the method as you will see on line 72 and line 117.
• Line 66 and 67:
  String portAddressHtml = SharedObieeController.SERVICE_END_POINT+”/saw.dll?SoapImpl=htmlViewService”;
  HtmlViewServiceSoapProxy htmlClient = newHtmlViewServiceSoapProxy(portAddressHtml);
  • Importance:  The wsdl provided contained an endpoint, however, you can dynamically set the endpoint and avoid the need to regenerate the client for each environment (dev, test, qa, prod, etc.).
• Line 88:
  sessionparams.setLocale(sawlocale);
  • Importance:  When supporting multiple locales, you can optionally set the country and language.
• Line 94:
  sessionID = getObieeSession(portletSession, sessionparams, userId);
  • Importance:  This is a call to the method getObieeSession that will check to see if an OBIEE session already exists.  If not, it will get the OBIEE session else it will validate that it is still active.  If it is not still active it will get a new OBIEE session else it will use the existing session.
    
• Line 137 and 138:
  String portAddressSAW = SERVICE_END_POINT+”/saw.dll?SoapImpl=nQSessionService”;
  SAWSessionServiceSoapProxy myPort = newSAWSessionServiceSoapProxy(portAddressSAW);
  • Importance:   The wsdl provided contained an endpoint, however, you can dynamically set the endpoint and avoid the need to regenerate the client for each environment (dev, test, qa, prod, etc.).
• Line 145:
  authResult = myPort.impersonateex(SERVICE_USER_NAME, SERVICE_USER_PASSWORD, impersonateUserId, sessionparams);
  • Importance:  This method allows you to impersonate the logged in user from portal letting OBIEE authorization control data.  If you do not use this feature you must pass your criteria as filter criteria.  If this feature is not needed you can call:
    authResult = myPort.logonex(SERVICE_USER_NAME, SERVICE_USER_PASSWORD, sessionparams);
• Line 106:
  filter[0] = getReportFilterCriteria(chartParameterList);
  • Importance:  This is a call to the method getReportFilterCriteria that build the report filter criteria, if needed.  This method will check to see if any report parameters have been defined on the configuration page and will dynamically build the report filter xml based on the report parameters defined.
• Line 112:
  htmlClient.setBridge(“/OBIEEChartSample/ObieeBridge”, sessionID);
  • Importance:  This defines the bridge that OBIEE will use to dynamically set the resource url.  Note:  The bridge will be covered later in this document.

How the Bridge Works

The following diagram depicts a simplified view of the OBIEE bridge:

The OBIEE bridge is a servlet that acts as a proxy to get the resources requested by the browser.  The bridge will deliver the requested information to the browser in order to prevent cross browser scripting errors in the javascript and will appear to be serving all resources from the Portal server.  The bridge also prevents requests to other non-obiee endpoints.

During the development of this chart portlet an issue was discovered in two of the files delivered by OBIEE:

• copyiframe.js – this file was not well formed and was causing random issues for the supported browsers.  A well formed version of this file was created to resolve this issue.
• menu.css – this file was overriding many of the styles used by portal and was not needed.  A file without content was created to avoid this issue.

Using the Sample Portlet

After you have performed the necessary modifications to the provided sample and deployed to Liferay, add it to a page by clicking Add Application.

The portlet will be under Perficient/OBIEE Sample:

Summary

The limited availability of good documentation on using the HtmlViewService was a real challenge, however, the OBIEE API is very well thought out.  I hope that the sample code and explanations provided will assist you in your OBIEE integration and help you avoid some of the issues that I faced in development.

You can download the sample code here.