Art of BI: BITeamwork and Your Existing OBIEE Customizations

If you’ve downloaded and installed BITeamwork (community or enterprise edition) you will have noticed that the Oracle BI commenting solution makes use of the default Oracle BI customization structures. This post quickly looks at BITeamwork and Custom XML Template Configurations in order to give confidence that BITeamwork aligns with any existing configurations that your Oracle BI implementation currently has in place. Again, BITeamwork sits within the Oracle BI architecture and in no way interferes with normal system processes. It augments its features by aligning with the pages and HTML areas in which it OBIEE works. As such, let’s examine part of the XML template that BITeamwork seeks to customize during deployment and how your standard customization of the Oracle BI header logo or portal title is aligned.

This blog also takes a quick look at the some of the confusion that can arise when implementers use the instanceConfig.xml and set the custom logical and physical path elements to provide a reference to their customizations files. Hopefully by the end of this post you have an understanding about XMLTemplates, aligning your existing customizations with BITeamwork, and general customizations within OBIEE.

BITeamwork Installation Customization Adjustments

During the installation of BITeamwork two folders will be created within the OBIEE instance under which you’ve conducted the installation: /pages and msgdb/messages/l_en/, under the folder structure path, ex: $FMW_HOME/instances/instance1/bifoundation/core_application/BIServerPresentationServicesComponent/

These folders and underlying files will be unique to the majority of Oracle BI implementations and they will be created in the location as described above. This file structure is generally a set of unknown or unused folders to most OBIEE implementations even when users “lightly” customize OBIEE. However, they are “one” (and the correct one per Oracle documentation) of the correct locations for providing updates or customizations for the OBIEE customMessage files. The files that are created within this folder structure are updated for the BITeamwork product to align with each release of Oracle BI. This includes every GA patch release where there is no delta from the preceding patch. Said, another way, this is an area of OBIEE which is seldomly touched. BITeamwork is a packaged product solution release cycles ensure that these BITeamwork files are updated per release to correlate with each new release of OBIEE to maintain as synergistic integration.

If your implementation uses a file called customMessage.xml to augment your Oracle BI look and feel then you can either merge your customizations into the new file(s) created by BITeamwork, leave them both in place, or copy the third WebMessage block from the BITeamwork installation into your existing customMessages.xml file. The most important item that must be present for BITeamwork to function is the WebMessage block with the name “kuiSecondaryTabbarPageBorderBottom”.

BITeamwork also modifies the page template of OBIEE. So, if there are any detailed customizations done in your OBIEE implementation then you will merely need to retain the JavaScript snippets at the bottom of the head tag for each of the pages in order to retain BITeamwork functionality. This is more advanced and won’t be covered in this blog post but feel free to contact BITeamwork support for assistance.

Change My Header Back

Once the install of BITeamwork completes, it then updates the header in the upper-left corner of the OBIEE portal to read “Powered by BITeamwork and ArtOfBI”. This is done so that you know the installation has been run and most likely had completed successfully. If you already had customized that part of OBIEE with your logo and some of your Company text and would like to revert, then follow these steps:

1) Navigate to the path mentioned above, $FMW_HOME/instances/instance1/bifoundation/core_application/BIServerPresentationServicesComponent/
2) Back up the customMessages.xml file
3) Open the customMessages.xml file for editing
4) Remove the two WebMessage XML blocks as shown below for kmsgHeaderBIBrandName and kmsgProductPortal
5) Save the file
6) Return to the OBIEE Administration page and click the option to “Refresh Files and Metatadata”

Your Customizations and BITeamwork

Perhaps you’ve customized your Oracle BI implementation and bit and modified your portal header text. This should have been done using a customMessage.xml file in your implementation. BITeamwork tries to replace that initially as we discussed above. So, just follow the instructions above and you’ll be good to go.

Perhaps you got clever and changed your OBIEE portal logo to that of your company’s. This is done in the CSS files if done correctly (and aligns with the skins/styles configuration). BITeamwork does not attempt to modify the CSS at all during its installation, so no worries on this one.

Perhaps you’ve totally hit genius level and updated all of the above and in addition to that you’ve modified the default skins and styles to change background colors, borders, and complete look and feel of OBIEE. BITeamwork does not worry about this and does not seek to modify skins or styles during the installation, so no worries here.

But, what if in doing any of the above you got so clever, and read somewhere that you could modify the location of the customization files so that they could be located somewhere else in the file server environment. This happens and it can potentially (rarely, but we’ve seen it) impact the success of the initial BITeamwork installation. Basically your customizations are safe and will not be overwritten by the BITeamwork installation. However, if you have manually modified the pointer to where your customization files are referenced by OBIEE this could be a slow-step in the installation. You will most likely need to find these customizations files to ensure the BITeamwork customizations are read by the OBIEE system. BITeamwork can’t account for every permutation and customization for every customer but there is any easy remedy to this scenario which is described further in the next section.

Locating Our Custom Configuration Files

Perhaps you’ve read this Oracle BI customization document or the Oracle BI customization documentation for your OBIEE installation and thought it was a good idea to store your customizations on a shared file system or replicated file system location for a High Availability environment. The most intense change you would have made from this document is updating your instanceConfig.xml file by adding the new elements which point to your unique customization folders. Just as an example, that would look something like this:

/home/obiee/customstuff
/customstuff

If these folders actually contain your your customizations then that is great. This should only impact BITeamwork if you are overriding one of the WebMessage blocks that it needs to function. Your skins and styles are inconsequential to BITeamwork’s processes. If this is the case for your implementation, if you do not see the “Powered by BITeamwork and ArtOfBI” header after the BITeamwork installation completes then you will need to copy the customMessage.xml file created by the BITeamwork installation and place it in your CustomerResourcePhysicalPath directory. Refresh the files and metadata from the Administration page of OBIEE and you should be good to go. If not, then you probably have a spider-web of random custom message files located within your Oracle BI server’s file system and need to locate them.

Superfluous Custom Message XML Files

If you have multiple custom message XML files superfluously located throughout your system, this may also cause an issue with BITeamwork rendering properly. Most likely you’ve already experienced issues with your customizations efforts and you know it needs a bit of clean up any way. Well now there’s not better time to get to it. The best thing to do here is to take an inventory of your CustomMessage files. On a Linux system you can run a find command from the terminal prompt while you are on the directrory for your fusion middleware home (FMW) directory of your OBIEE instance. For example: find /u01/FMW -name “custom*xml”

If you are running on Windows OS, we suggest that you download WinGrep (www.wingrep.com) to run this type of search. Either way you will need to search for files with the “.xml” extension so that you understand how much unnecessary overlap you’ve thrown at your customizations and perhaps simply forgotten about or did not test sequentially. You only need one XML file to hold your custom message XML templates (per locale if you need to break it out for foreign language translations, etc.) and there technically only needs to be one physical directory location that stores your custom Styles and Skins folder(s). Once you’ve cleaned this up you’ve done your infrastructure a favor and you should have zero issues with BITeamwork’s augmentation integration with OBIEE.

Don’t You Know that Our Company’s OBIEE has the Most Customizations “Ever”?

While we are sure that you think it does there are hundreds of Oracle BI customers that have massive amounts of customization applied to their Oracle BI implementation. BITeamwork is no stranger to this. We actually embrace it. OBIEE was build from the ground-up to embrace the customizations its customers need to throw on it so that user engagement is increased and the product feels more like it is “their” tool. BITeamwork functions in even the most complete of customized Oracle BI environments. We realize that there are some alternative ways to make the customizations happen and although BITeamwork is setup to handle all of them, there may still be the off chance that we need to tailor a bit of BITeamwork’s configuration to fit your Oracle BI implementation. Or, your customizations could use a bit of tuning so that they are best practice and align directly with BITeamwork’s best practice integration with Oracle BI. Either way this is a really straightforward discussion and effort as we’ve shown in this blog post.

Some Other Information on the Topic

• http://www.oracle.com/webfolder/technetwork/tutorials/obe/fmw/bi/bi1113/customizing_obiee11g/customizing_obiee11g.htm?cid=5665&ssid=115836023212657
• http://www.rittmanmead.com/2010/12/oracle-bi-ee-11g-styles-skins-custom-xml-messages/
• http://www.oracle.com/technetwork/middleware/bi/customizing-oracle-biee-11g-176387.pdf