Configuring user interface behavior in OBIEE

Let's face it, there are some things about the OBIEE interface that just don't sit well with you. For example, you may have noticed that the "Download to Excel" feature actually downloads MHTML, not native XLS, which may or may not be desirable behavior for your users but regardless, it's not the most accurate label for the given behavior.

Say we want to remove the "Download to Excel" link and instead force users to use the "Download to Excel 2000" feature -- and to eliminate any confusion, we want to drop the "2000" and display that option simply as "Download to Excel". Is this doable? How?

Changing the interface to achieve these requirements is doable, and here are the steps we have to take:

• Drop the original "Download to Excel" link from the Download menu
• Rename the "Download to Excel 2000" menu item to "Download to Excel"

First we need to understand how to configure the interface behavior. Much (if not all?) of the OBIEE user interface is configurable via a series of XML files:

OracleBI/web/msgdb/messages/*.xml
These files define the HTML (and JavaScript) code used to create the UI for various user controls. They rely on message "variables" for the actual words that users see

OracleBI/web/msgdb/l_*/messages/*.xml
These files assign language-specific message words to the message variables (files in l_en/messages assign message verbiage for English-language configurations, l_es for Spanish, l_de for German, etc)

But before we start messing with these files we need to understand how to modify them in a way that is compatible with an upgrade. Notice in the "OracleBI/web/msgdb" folder there are three "types" of subfolders:

a) language-specific folders (l_ar, l_cs ... l_en, etc),
b) the "/messages" subfolder
c) the "/customMessages" folder

Files in the "/messages" folder have been deployed by the application install process. Any files in the "/messages" folder will be OVERWRITTEN during an application upgrade. If you don't want your custom configurations to be wiped out at upgrade time, here's what you do: copy the desired file that you want to configure into the "/customMessages" folder and make your changes there. The application will automatically use whatever lives in the "/customMessages" folder as the "official" version, overriding the version in the "/messages" folder.

Now the question is, which of the xml files in "/messages" and "/l_en/messages" do we need to configure?

In "/messages", the file in question is called "viewscontrolmessages.xml". Open that up, then save it to "/messages/customMessages." Upon examining this file you'll see that the XML defines a series of "WebMessage" entities. We are interested in the one named "kmsgEVCDownloadLinks", which happens to be the first WebMessage entity. This element contains a series of HTML links whose purpose might not be obvious at first glance. Look closer and you'll see some code that should give us some good clues as to what's going on.

Let's deconstruct the first link as an example:

<a onclick="">Download('@{command}&amp; Format=mht&amp; Extension=.xls'); return false" href="javascript:void(null);"name="SectionElements"><!--xml:namespace prefix = sawm /--><sawm:messageref name="kmsgEVCLinkDownloadExcel"></a>

In the opening tag we see the name of this element ("SectionElements") and a JavaScript "onclick" directive that calls the "Download" subroutine with various parameters, including "Format=mht".

Where we would expect to find the actual verbiage of the link that the user sees -- between the opening and closing anchor tags -- we see a messageRef "token" that refers to an entity named "kmsgEVCLinkDownloadExcel." This is the message variable whose value is set in the language-specific configuration files (which are found in /l_en/messages for my English-language installation).

Hmm, judging from the naming convention it looks like we found the "Download Excel" link. Looking further down the list we see another link referring to the variable "kmsgEVCLinkDownloadExcel2000". I'm going to go out on a limb and say we've found the HTML for the two links that we need to change. Remember we want to remove the first and relabel the second. Let's simply delete the "Download to Excel" entry. The resulting XML should look something like this:

<webmessage name="kmsgEVCDownloadLinks"><!-- Param command --><!-- target is parent so when saving from frameset we dont get access denied error -->[html]<sawm:choose><sawm:when name="noMenu"><a name="SectionElements"><xmp>href="javascript:void(null);" onclick="NQWClearActiveMenu();Download(&#39;@{command}&amp;Format=excel2000&amp;Extension=.xls&#39;); return false"><sawm:messageref name="kmsgEVCLinkDownloadExcel2000"></a>&amp;nbsp;

Notice the "sawm:choose..." conditional -- looks like there are two versions of the Download menu being defined here. Why? We'll have to save that question for another conversation. For now let's just comment out both links to be safe.

The next question is, in which file do we set the value of the message variables? I did a filesystem search for the string "kmsgEVCLinkDownloadExcel2000" in the contents of all files in the /l_en/messages folder... and found the value for this variable is set in the file "viewmessages.xml":

<webmessage name="kmsgEVCLinkDownloadExcel2000">Download to Excel 2000</webmessage>

Now that I have the file, the first thing I want to do is create an upgrade-proof copy for the custom messages the same way I did for the "viewscontrolmessages.xml" file. I don't see a "/customMessages" folder in the "l_en" folder, so I'll have to create one first, then save a copy of "viewmessages.xml" to that folder.

I open the new file, find the "kmsgEVCLinkDownloadExcel2000" variable, and remove the "2000" from the message. The XML now looks like this:

<webmessage name="kmsgEVCLinkDownloadExcel2000">Download to Excel</webmessage>

I save both files (double-checking to make sure I was modifying the "/customMessages" versions) and restart the Presentation server and voila:

What if we want to change the HTML or verbiage of another interface element but we don't have the luxury of knowing which files define the element? Here's a somewhat crude but essentially effective way of doing it: Now that we know where the message verbiage is set, we could simply do another filesystem search in the "/l_en/messages" folder for the file that sets the variable to the verbiage we want to change, then we can search the "/messages" folder to see where that variable is being used.

As always, have fun...

Oracle BI High Availability: Part 3

The following is the third installment on the topic of High Availability within an OBIEE environment. As I mentioned in previous posts, much of what I’ll be discussing was covered in an Oracle eSeminar which I recently viewed on the subject. To quickly summarize, our basic goal within an HA implementation is to provide multiple instances of all components from the BI Server all the way to the end user, so if anything fails, we have another instance of the same component ready to go. The first two posts on the subject can be found in the blog archives if you’d like to rewind. This installment will feature the HA connections between the Presentation Servers and BI Scheduler Servers as well as between the Presentation Servers and BI Servers. We’ll also look closer at the BI Scheduler Cluster configuration.

First we’ll look at the connection between the BI Servers and the Presentation Servers. This again is handled by the Cluster Controller. In a Windows environment you’ll need to go into the Administrative Tools on each Presentation Server and set up the clustered ODBC data source. To do so, simply ensure that “Is this a clustered DSN?” is checked, then specify the primary and secondary cluster controllers and ports. On a Unix/Linux box, you’ll need to make the following changes to the odbc.ini file:

IsClusteredDSN=Yes

PrimaryCCS=<PrimaryCCS>

PrimaryCCSPort=9706

SecondaryCCS=<SecondaryCCS>

SecondaryCCSPort=9706

One important note to keep in mind is that if you have any clients from which you want to access your repository in online mode, you’ll need the clustered DSN set up on these as well. They’ll need the same connection to the BI Servers as the Presentation Servers will.

The BI Scheduler Cluster Controller assigns the active Scheduler server. In an HA environment, you would have two cluster controllers, a primary and a secondary, in an active/passive relationship. The secondary server will not be used unless the primary is unavailable. The client Controller ports are specified in the respective NQClusterConfig.INI files. The Scheduler configuration will be handled by the Cluster Controllers, so all we need to do in the instanceconfig.xml file is point to the Cluster Controllers, as shown below:

<Alerts>

<ScheduleServer>

ccsPrimary=”<Primary Cluster Controller>”

ccsPrimaryPort=”<Client Controller Port>”

ccsSecondary=”<Secondary Cluster Controller>”

ccsSecondaryPort=”<Client Controller Port>”

</Alerts>

</ScheduleServer>

The other task you would need to complete is to add the BI Scheduler Administrator credentials to the credential store of each ps. The quickest and easiest way would probably be to copy the credential store file from one instance to all other presentation servers.

A few notes about what will occur when the Active Scheduler fails. The transition from one server to another is seamless to the user’s perspective. The users won’t receive any errors, the Cluster Controller will simply detect the failure on the active server and point to the secondary. Any jobs which didn’t complete will be picked up where they left off. One important note to remember is that once the primary server is back up, it will not automatically resume the primary role. Only after the services have been restarted will the primary Scheduler resume its proper role. If any Java, command line, or script jobs are being run during an interruption, they will be restarted when another server is activated and given a new job ID. Take a look at the diagram of the basic HA architecture for the Scheduler Servers.

To configure the Cluster Controller to talk with multiple Schedulers, you must make the following entry in the NQSClusterConfig.INI file on each Cluster Controller:

SCHEDULERS = "scheduler1:9705:9708", "scheduler2:9705:9708";

The first port number for each scheduler will be the rpc port, where the Scheduler will be listening for connections from the Scheduler. The second will be the monitor port, which simply listens for a “heartbeat” from the Scheduler, to confirm it’s still available. This is how the Cluster Controller determines that the primary server has gone down and it needs to look to the secondary server. The default ports for the rpc and monitor ports are 9705 and 9708, respectively.

Configuration of the BI Scheduler Servers themselves can be completed through the Job Manager or via command line using schconfig. All configuration settings are saved in the instanceconfig.xml file of the Scheduler folder, not to be confused with the file of the same name in the web\config folder. The Scheduler can be configured to talk with multiple Presentation Servers and Java Hosts, which will be necessary if you are setting up a true HA environment. If you are using the Scheduler to run script files, you must place them in a shared network file, so that multiple Scheduler Servers can access them. All Schedulers should have read/write access to these files.

That’s going to wrap it up for this post. I’ll finish things up next time with a closer look at the BI Server cluster and how it’s integrated into the HA environment.

Oracle BI High Availability: Part 2

This is the second installment in a series of posts in which I’ve been discussing the implementation of High Availability within an OBIEE environment. Much of what we’ll be discussing was in included in an Oracle eSeminar which I recently viewed on the topic. In my original post, I gave the broad strokes in regards to HA and provided the basic overall architecture of a High Availability deployment. This time, we’ll start to dive into some of the specifics regarding configuration which will be necessary to implement a true “shared nothing” HA environment.

Each Presentation Server can be configured to talk with multiple web servers, Java hosts, BI Servers, and BI Schedulers. In this installment we’ll cover the Presentation Catalog, web server, and Java host connections to the Presentation Servers as well as how the user is affected when a Presentation Server fails. The diagram below is a subset of the one shown in my original post on the subject. This figure shows only the components of the HA architecture which we’ll be looking at today.

First, let’s discuss the web client behavior in a High Availability environment. When a user begins a session, the web client is bound to a specific Presentation Service and subsequent requests will be sent to that same service. When a Presentation Service failure occurs, the error is relayed back to the browser and any unsaved data will be lost. Upon logging in again, the user will be bound to another available Presentation Service. Two exceptions to this rule would be if the user is using SSO or if the Presentation Services plug-in is configured to automatically reconnect to another server. In these cases, there may still be a loss of session state. There will also be a time lag to recognize the failed server. This lag will be dependent on plug-in ping settings which we’ll get to eventually.

Any iBots which fail to complete as a result of a Presentation Service failure will result in an error being passed to the BI Scheduler Server and will be included in the log file. When the next available Presentation Service becomes available, the job is rerun without impact and will start again at the step in which it originally failed.

Next, we’ll look at how we would like our Presentation Services to share the Presentation Catalog. There are two basic options which can be deployed. The first option is to use a shared file system. All presentation servers have access to the same shared files. This is the simplest approach and, as I mentioned in my last post, is recommended by Oracle. Alternatively, a more complex method of catalog replication can be deployed through the use of replication agents on each instance which will monitor a single instance for changes and sync other copies as necessary. Two-way replication, which involves making changes to multiple copies of the Presentation Catalog and attempting to keep them all in sync, is highly discouraged and should be avoided. As you can imagine, this method would make maintaining data integrity much more difficult and complicated.

If you’ll be using the shared file approach, the first step necessary will be to point each presentation server to the shared file path by editing the <Catalog> element of the instanceconfig.xml file. In addition, we should also make changes the Presentation Service cache settings. Keep in mind that each instance will have its own cache, which we’ll want to configure to ensure it won’t get stale. Oracle recommends adding the following settings to each configuration file:

<Catalog>

<ReportIndexRefreshSecs>120 </ReportIndexRefreshSecs>

<AccountCacheTimeoutSecs>180 </AccountCacheTimeoutSecs>

<PrivilegeCacheTimeoutSecs>180 </PrivilegeCacheTimeoutSecs>

<CacheTimeoutSecs>120</CacheTimeoutSecs>

<CacheCleanupSecs>600</CacheCleanupSecs>

</Catalog>

Another piece of the puzzle will be to configure the presentation servers to work with multiple Java hosts. Once again, we must edit instanceconfig.xml to complete this task. This will involve listing the java host instances as shown below. The default Java Host port is 9810, but you can verify this by checking the OracleBI_Home\web\javahost\config\config.xml file. Simple load balancing will be performed in a round robin fashion between all instances listed in the config file.

<JavaHostProxy>

<Hosts>

<Host address=”<Javahost Machine1>” port=”9810”/>

<Host address=”<Javahost Machine2>” port=”9810”/>

</Hosts>

</JavaHostProxy>

You may also add an optional LoadBalance/Ping element. This element specifies the criteria for determining whether a Java Host is reachable. The ping element is not necessary if you wish to keep the default, which is 5 pings at 20 second intervals.

The final component we’ll look at today is the BI pres Services plug-in, which sits on the web servers. Here I’ll outline the changes necessary on each web server instance both for IIS and Java-based servers. IIS web servers will use the ISAPI plug-in, and the config file for this plug-in can be found in the OracleBIData_Home\web\config directory. The only element you must configure is the Hosts element, in which you will list the host and port of all Presentation Service instances. You may also optionally configure the LoadBalancer element which controls the autoroute feature. The default setting is false, which means that the user will receive an error if the current Presentation Server goes down. Setting this option to true would cause the server to attempt to connect to the next available Presentation Server without impact to the user. You also have the option of adding the ping element, which is the same element we just discussed when examining the Java host configuration.

The Java Servlet changes necessary for Java-based web server configuration are very similar to the ISAPI configuration mentioned above. You’ll need to edit the config file found in the OracleBI_Home\web\app\WEB-INF directory to include all Presentation Server host and port pairs. The <oracle.bi.presentation.sawconnect.loadbalance.AlwaysKeepSessionAffiliation> element is equivalent to the <LoadBalancer> element with the ISAPI plug-in and should be set to “Y” or “N”.

Next time we’ll continue to discuss the BI Presentation Server and how it will be configured to talk with the BI Server and Scheduler…