OracleBIBlog Search

Tuesday, June 16, 2009

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:

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

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...


E said...

Joseph this was super useful. Thanks you! Question. We are wanting to change the "Log Out" words. If we change to anything longer that 7 characters, the service will not start. Get Internal Server Error message. So for example we can change "Log Out" to "Bck Prt" but not to "Back to Portal". Seems like there must be a place that specifies the length or max length of messages. Any ideas where?


Joseph Naujokas said...

Hmm, that's a good one.

Which variable are you changing? Just looking at the xml files without actually testing them, it appears there are two variables that seem to be relevant:

kmsgAuthenticateLogOff = 'Log Out'


kmsgAuthenticatenQuireLogOff = ' Log Out' (note the leading space)

Note that kmsgAuthenticatenQuireLogOff = 8 chars including the leading space, while kmsgAuthenticateLogOff = 7 chars.

Interestingly, logoncontrolmessages.xml references kmsgAuthenticatenQuireLogOff, not kmsgAuthenticateLogOff.

Two thoughts off the top of my head:

* If you modified kmsgAuthenticateLogOff, try kmsgAuthenticatenQuireLogOff instead

* When you say that anything over 7 chars fails, perhaps you mean that ANY CHANGE to the value results in a 500 error? If that's the case, it could be that your text editor is saving the file in the wrong format. Make sure the file format settings in your text editor match the operating system standards (Unix vs Win vs Mac have different ways of indicating line breaks).

Let us know...

Anonymous said...

Hi Joseph,

Your article is good and thanks for posting the same.
I have a requirement where in the user wants the OBIEE window to be closed when they click on the Log Out button. how can we do that?
Your earliest response would be highly appreciated.