Skip to main content

Digital Transformation

Sample Integration – OBIEE with Portal

Before We Begin

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:
    Deployment Descriptor 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:
    OBIEE Supported Browsers
  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:

OBIEE Integration High Level Overview

  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:

OBIEE Screen 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:
    Java Project Wizard - Step 1
  2. Enter the name OBIEEWebServiceClient in the Project Name field and click Finish:
    Java Project Wizard - Step 2
  3. Import saw.wsdl into the project:
    Project with imported wsdl
  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):
    Namespace from wsdl
  5. Right click on the saw.wsdl and choose Web Services/Generate Client:
    Generate Client from wsdl in Eclipse
    Click Next on the first screen:
    Web Service Client Wizard - Screen 1
    Choose the option to Define custom mapping for namespace to package, then click Next:
    Web Service Client Wizard - Screen 2
    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:
    Web Service Client Wizard - Screen 3
    When complete your project will look as follows:
    Web Service Client after Generation
  6. Add this project as a Java EE Module Dependency to the OBIEEChartSample project by right clicking on the OBIEEChartSample project, then clicking Properties:
    OBIEE Client Module Dependency
  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.

Project Structure

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:

OBIEE Bridge Overview

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.

Liferay Add Application Dialog

The portlet will be under Perficient/OBIEE Sample:

Perficient Sample Application Add

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.

Thoughts on “Sample Integration – OBIEE with Portal”

  1. Hello, thanks for the information. Is there anyway to get a list of the Web Services Guide for OBIEE v 10g? I am reasearching, if you guys happen to know/have something I dont it would be a great help. Thanks!

    Thank you,

    Ricky Fair

  2. Dan Wellborn Post author

    Hello Ricky,
    Unfortunately there is not much in the way of public documentation. Here is a document that I used to get started, however, much was learned through trial and error, public forums, and collaboration with other developers. The best approach would be to download the sample, then research each method you are curious about.

    Hope this helps,
    Dan Wellborn

  3. Renzo Bernasconi

    Hello, i’m triying to implement the example and the tag “${reportHTML}” always appear in the screen and is not changing with the results. The log show me the information but not in the screen. Any idea?

    Thanks.

    Renzo Bernasconi

  4. Dan Wellborn Post author

    You should not see the tag ${reportHTML} because this is JSTL notation. Please make sure that you have the needed jstl jar file in your path.

    Thank you,
    Dan Wellborn

  5. Hello Dan,

    I’m Trying to integrate Websphere with obiee 10g. I’m using the portlet “sawjsr168portlets” and the portal is asking for the “ReportPath”. I don’t know how to configurate this, is like the catalog path or anything like that? Thanks for the attention!

  6. Dan Wellborn Post author

    Here is a sample of what the path value would look like: Report Path: /shared/Path/To/Report

    Hopefully this will help you find the value that is needed.

    Thanks,
    Dan Wellborn

  7. Hello Dan,
    the download link that you provided seems not working.
    Where can I download your project?

    Thank You
    Cheers
    Rob

  8. Dan Wellborn Post author

    Hello Rob,

    Sorry for the inconvenience, there must have been an issue when we migrated to the new site. I fixed the issue, please retry.

    Thank you,
    Dan Wellborn

  9. Great! Thank You, Dan!
    Just want you to note that you forgot to fix the link in the “OBIEEChartSample Project Package Structure” section, but the others are working perfectly. Thank you again!

    Cheers
    Rob

  10. Hello!
    I can’t make the sample work. When the bridge servlet tries to open the input stream with the ajaxGo page it returns “403: Forbidden”. The login phase says that it is authenticated. Any suggestions?

    Thank you very much.
    Marek

  11. Dan Wellborn Post author

    Sorry, I do not have access to OBIEE 11 and I am not aware of what changed between versions. Hopefully the information provided in this post will benefit you.
    Thank you,
    Dan Wellborn

  12. Dan Wellborn Post author

    Hello Marek,

    It sounds like you are able to authenticate to your portal server, however, your bridge is not working. Did you modify the SharedObieeController:

    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”;

    Please make sure that you have provided the correct information above.

    Thank you,
    Dan Wellborn

  13. Yes, I edited that part. I’m not using the impersonate, so I edited also the part that you’ve commented.
    I also tried to “semplify” the servlet when yours did not work, but the result is the same. If you prefer, I can send you my servlet code.

    Marek

  14. Using your example I was able to get a very robust integration of OBIEE 11.1.1.7 and LifeRay. Thanks for the leg up. I am running into an issue though. I’m having trouble with the PDF print link at the bottom of each analysis. It posts through the bridge but it gets a 400 bad request result back from the OBIEE server. Have you been able to get these links to work?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Dan Wellborn

More from this Author

Follow Us
TwitterLinkedinFacebookYoutubeInstagram