Customizing the OBIEE user interface is one of the most frequent activities when implementing OBIEE in a company. Not because you don’t like and don’t want to see it’s an Oracle tool but mainly because you want your users to “feel like at home” and have a unified experience finding at least your corporate identity applied to as many tools as possible.
It is also proved by the number of posts on OTN forums asking how to change the oracle_logo.png on the top-left corner of the OBIEE interface to put the company logo or something like that instead.
If you are looking for custom styles using a shared folder, “analyticsRes”, you find the details in another post: OBIEE 12c Custom Style using shared folder (analyticsRes)
Why another post on custom styles?
If it’s such a common and frequent activity why the need to write about it again? Well … the answer come from OTN posts mainly, it’s unbelievable the number of users who posts things like: “I searched and replaced all the oracle_logo.png in the OBIEE folder but I still don’t see my logo”.
Customizing OBIEE isn’t a really difficult activity as long as you make it right and understand why it’s not about search/replace files around your filesystem.
Basic concept of a custom style
Thinking about customization and how it interact with the life cycle of the application, the custom style stay the same (in general) while the application is updated to fix bugs and deliver new functionality to users, it’s obvious that customizing something like OBIEE can easily be painful.
Search and replace a file as zero chances to survive an update or an upgrade, no need to think too much: when changing a file or component of an application you don’t control there is no way to prevent a future update to override what you did.
That’s why a proper process for customization must be implemented and adopted by the application itself. Luckily for us OBIEE does it!
There are 2 official ways to deploy a custom style/skin for OBIEE 12c and in this first post I’m covering the one I prefer also because it seems to be the one with the best results and less missing / wrong URL references (at least in 188.8.131.52.0, maybe fixed in 184.108.40.206.0, will test and cover it in another post).
The official OBIEE documentation cover custom styles/skins, for 220.127.116.11.0+ you can trust it, for 18.104.22.168.0 the doc is wrong and there are bugs, so better to first search in MOS the fix and new doc to avoid losing time.
More in general if you are still on a 22.214.171.124.0 or 126.96.36.199.0 version it’s highly advises to update to 188.8.131.52.0 (latest available at this time) as many bugs have been fixed. Even with custom style.
Which style to extend?
First thing first you must decide on which default style provided out of the box you base your customization. OBIEE works by extension, since years it’s extending styles and skins from a basic one. The current default style/skin is Alta in OBIEE 12c, Alta is based on Skyros and Skyros is based on blafp (“browser look and feel”).
In this post I’m going to extend Alta as it’s the most “modern” looking style available for now (light colors, flat interface, the changes which reached our mobile phones UIs and websites some time ago already).
Custom style deployment with a EAR file
The short version for customizing with a EAR file from the doc is to get the template file, modify the content, deploy it in Weblogic, tell OBIEE the name of the new default style, done!
It’s a bit more than that, there are more details and the doc goes quite straight forward assuming you know how it works through the steps. By following some extra steps and understand why you need it, you can make it without problems and quite quickly after a first test.
Let’s work based on an example: my company, DATAlysis, want to customize OBIEE by using the company logo and changing the top header color, a bit like the datalysis.ch website.
As said I’m going to start from Alta as I like the new grey&white style.
Use the template EAR file
First I get a copy of ORACLE_HOME/bi/bifoundation/jee/bicustom-template.ear , this is the template to be used for a customization. It contains a copy of Skyros, so if you simply modify it’s content you end up with a Skyros base and not the Alta one, they aren’t really similar as Skyros is a dark blue style.
This file is basically a zip archive (do not focus too much on the extension), you can unzip it with your preferred zip tool.
Start by extracting it, for example on linux I did unzip bicustom-template.ear -d ./ear_file (I’m extracting into a temporary folder to make my live easier).
Do not touch the META-INF folder and its content, just leave it there, I will need it later and the work will be done on the bicustom.war file. Once again it is a zip file and it’s the one that will contain the files of the custom style/skin.
Extract bicustom.war to be able to start modifying it, here again on linux I did unzip bicustom.war -d ../war_file .
Once again META-INF and WEB-INF are folders you keep like that and do not change anything inside (and you must keep them or Weblogic will complain when trying to deploy the file later).
The interesting part is into the res folder.
First I must edit filemap.xml as it’s here where I start defining my custom style and/or skin based on Alta (remember Alta is based on Skyros, Skyros is based on blafp). In this case Alta is the “parent” style.
So the content of filemap.xml must be something like:
<!-- The style name should exactly match the name of the folder, including case -->
<Hierarchy>s_Alta / s_DATAlysis</Hierarchy>
<!-- The style name should exactly match the name of the folder, including case-->
<Hierarchy>sk_Alta / sk_DATAlysis</Hierarchy>
What does it means? My custom style folder will be named s_DATAlysis and will be based on s_Alta, my custom skin will be named sk_DATAlysis and will be based on sk_Alta. The skin (sk_ folder) isn’t mandatory, it is defined but no need for it to physically exist. As the comment in the file remind you pay attention to the case you use when writing the style/skin hierarchy: s_datalysis is not the same as s_DATAlysis which is also different from s_DATALYSIS.
The s_Custom folder content: the style itself
Now I can start customizing the style itself and this is also done inside the res folder. By default the template gives me a s_Custom folder. First activity is to rename it to match the value I just entered into filemap.xml, so I rename it to s_DATAlysis. The content of the style is inside the master subfolder. For example the top-left logo named oracle_logo.png is just there in the folder, next to master.css and custom.css and many others pictures.
For my target (custom logo and different colors on the top bar) custom.css is enough. This is actually the advised approach as it avoid me to edit the real main style CSS file (master.css) making it simpler to move my customization to a different base style (like Skyros) or to update the Alta base I’m customizing. CSS works, as the name says, on cascading styles, and custom.css start by importing master.css and everything you write just after will override the styles of master.css .
First challenge: find the Alta style to use it as base
Oracle published a “bicustom-altatemplate.ear” file which contains directly a template of custom style based on Alta, making the following steps unnecessary. Thanks to Chet Justice for sending me the link.
As said before the template file provided by OBIEE is based on Skyros while my target is to customize Alta. So … how to do that? I must find the Alta style so I can replace the content of the master folder with the right one before to customize it.
- Get a copy of ORACLE_HOME/bi/bifoundation/jee/analytics.ear : this is the EAR file containing all the default styles and a lot more (do not mess with this one, do not customize this one as you are going to lose everything at the first update, even if some suggested to do it this way in the past).
- Extract this file (unzip) in a folder and extract again analytics.war in a folder.
- Go to res/s_Alta/master and copy all its content to your own custom style (delete old content first and then copy the one from s_Alta).
Done! Now my s_DATAlysis/master folder contains the Alta base style and I can start the customization.
Replacing the top-left Oracle logo is as simple as replacing the file named oracle_logo.png, I must keep the same name and to avoid bad surprises I also keep the same height and try to match a bit the width (trying to fit a 200x1600px logo instead of the original 136x17px one is looking for issues, I would suggest to try to respect the height of 17 and a similar width, if it’s less it’s not really a problem).
As I said the best approach for custom CSS is to use the custom.css as much as possible. In my case I can easily make it that way as I have only few things to define: a background color, a font color and it’s done. To test the CSS code I use my browser’s (Chrome) Developer toolbar and there I can test the CSS code “live” in the OBIEE page to identify which tag, class, ID I must use. The result is few rows of CSS.
Pack archives again, generate bicustom.ear
Now that my customization is done I must only pack all the files together to generate the bicustom.ear file I will deploy in Weblogic. As I said few times these are normal ZIP files, just do not forget to keep the structure and content of these files (the META-INF and WEB-INF folders I said to ignore and not touch before).
In my linux box I simple go inside the temporary folders where I extracted the files and start zipping again with zip -r ../ear_file/bicustom.war * and then going into the temporary folder for the ear file another zip -r ../bicustom.ear * .
The bicustom.ear file is now ready to be deployed in Weblogic.
Weblogic deployment of bicustom.ear
First I must upload the file on the OBIEE server and place it in BI_DOMAIN/bidata/components/OBIPS/. Then open the Weblogic console (by default <ip/domain>:9500/console) and go to Deployements. Now I lock the configuration and then start the install wizard.
I can now browse my OBIEE server and I navigate to the folder where I loaded bicustom.ear (BI_DOMAIN/bidata/components/OBIPS/) and select it.
Select to install as an application and move to the next screen.
Time to define where I want to deploy the content, I need it on the bi_cluster. I can select bi_server1 as it’s a single node cluster, but it’s easier to stay on the cluster itself. Avoid the AdminServer as it runs on a different port and you are not supposed to deploy OBIEE things there.
Last step of the install wizard is to select the option to make the deployment accessible from the specified location.
The install process is now over, just a last step to activate the changes in Weblogic.
As any new deployment an extra step is required: start the deployment and accept and serve requests. In the Deployments screen move to the Control tab, select the bicustom deployment and start it.
Tell OBI Presentation server to use my style as default
Now my custom style is available but I want to make it the default one for my OBIEE. This is done in the OBI Presentation server (OBIPS) configuration file.
On the OBIEE server edit the file BI_DOMAIN/config/fmwconfig/biconfig/OBIPS/instanceconfig.xml and find the tags DefaultSkin and DefaultStyle inside the UI tag. They must already be defined and contain the value Alta. As my style is named DATAlysis (the name of the folder without the s_) I simply replace Alta with DATAlysis.
Now after restarting the OBI Presentation server I must see my own logo and colors in OBIEE.
To resume, and some advice
- Read the official documentation once first, try to visualize all the steps and fill in the blanks (or read this post)
- Test your customization with the Developer toolbar of your browser first, to not have to deploy the EAR file 15 times
- Try to limit yourself, if possible, to the custom.css file
- Try to keep similar sizes for images you replace (oracle_logo.png for example)
- The EAR file is a packaged way to make things, you first need to prepare the EAR file and only after you can deploy it
- If you need to update something update the EAR file (new version overriding the original one) and in Weblogic Console select the deployment and click on “update”: done!
- Keep in mind CSS can act in different ways on different browsers