Friday, December 28, 2012

Creating and Developing Custom Styles, Skins, and Messages in Oracle BI EE 11g


Overview

Oracle BI EE 11g's UI is generated by using scripts and is therefore highly customizable. The "look and feel" is controlled by skins, styles, and messages. Skins define the UI chrome (visible graphic features) outside the home and dashboard area. A prime example of chrome or skins is a toolbar. Styles control the appearance of a dashboard and its various views, such as the font style and font color within a pivot table view. Messages store the text for various UI elements (for example, brand name).
Oracle BI EE 11g is shipped with two default styles: blafp (browser look-and-feel plus) and fusion (FusionFX)—both found in the <ORACLE_HOME>/bifoundation/web/app/res directory. This tutorial uses these default styles to provide a starting point to build the custom style and skin that you want to deploy.

Scenario

In this tutorial, you use common customization examples. These examples are packaged with the name Eden (available from the link below).

Software Requirements

The following is a list of software requirements:
  • Oracle BI EE 11.1 or later must be installed along with the default samples, Sample Sales Lite.
  • Oracle WebLogic Server (WLS) 11.1 or later must be the default application server to work in tandem with Oracle BI EE.
  • The eden zip file must be downloaded from this link.
  • The testfile.zip must be downloaded from this link.
  • A text editor (such as WordPad or Notepad) must be installed.
  • Mozilla Firefox 3.6 or higher is the preferred browser. Caution: If you use Internet Explorer, you may not be able to see some of your style sheet changes.

Prerequisites

Before starting this tutorial, you should:
  • Have the proper permissions for installing and configuring Oracle BI EE and WLS on your company's system
  • Have downloaded the testfile.zip file to your local hard drive, unzipped, and copied the test.txt file to<ORACLE_INSTANCE>/bifoundation/OracleBIPresentationServicesComponent/coreappplication_obips1/analyticsRes on your local hard drive
  • Have downloaded the sample eden.zip file to your local hard drive, unzipped, and copied the Eden subordinate directories to <ORACLE_INSTANCE>/bifoundation/OracleBIPresentationServicesComponent/coreappplication_obips1/analyticsRes
  • Have the Home page as your starting page in Oracle BI EE. Depending on what has been configured as your starting page, you might be presented with the Home page or My Dashboard page when you sign in to Oracle BI EE. If your starting page is My Dashbaord, you can always navigate to the Home page by clicking the Home page link on the global header.
  • Have some familiarity with creating analyses and dashboard pages by using Oracle BI EE
Note: Screen captures for this tutorial were taken in a Windows XP Professional environment; therefore, Start menu options will vary.

Deploying analyticsRes and Developing a Custom Skin

Before you can begin to customize the appearance of Oracle BI EE, you must create a directory to house the customizations, which can then be accessed by Oracle Business Intelligence Presentation Services (Presentation Services). Presentation Services generates the UI for the Analysis Editor and dashboards, which visualize data from Oracle BI Server, the core server behind Oracle BI. Various application servers have their own ways of exposing static directories. The steps below allow you to expose the static directory within WLS by deploying it as a J2EE application.
Note: Default styles and skins located in the <ORACLE_HOME>/OracleBI1/bifoundation/web/app/res directory should not be modified because potentially it can be overwritten with any upgrade or new installation.

Exposing a Static Directory in WebLogic Server


1 .The default installation for Oracle BI EE 11g creates a default directory that can be used for customization. This directory is<ORACLE_INSTANCE>/bifoundation/OracleBIPresentationServicesComponent/coreappplication_obips1/analyticsRes.
To expose this directory, you must open the WebLogic Administration Console. Open a browser window and in the address bar, enterhttp://<hostname>:7001/console/login/LoginForm.jsp (for example, http://localhost:7001/console/login/LoginForm.jsp). The WLS Login window appears.
Screenshot for Step
2 .Enter your username and password (for example, weblogic/welcome1) and click Login. The WLS Administration Console appears.
Screenshot for Step
3 .Select Deployments from the Domain Structure pane on the left.
Screenshot for Step
The "Summary of Deployments" pane appears on the right.
Screenshot for Step
4 .In the Change Center pane on the left (directly above the Domain Structure pane), click Lock & Edit.
Screenshot for Step
All applications are made available for update within the table and the Install button is enabled.
Note that the "Lock & Edit" button is now disabled.
Screenshot for Step
5 .In the "Summary of Deployments" pane on the right, click the Control tab and then click Install,
enabling you to install a new web application. The Install Application Assistant pane appears.
Screenshot for Step
6 .a. Select the appropriate folders within the Install Application Assistant pane to navigate to
<ORACLE_INSTANCE>/bifoundation/
OracleBIPresentationServicesComponent/coreappplication_obips1.
The path is automatically entered for you.
b. Select the option button for analyticsRes. This is a valid application for deployment.
Screenshot for Step
7 .Click Next and accept the default value "Install this deployment as an application."
Screenshot for Step
8 .Click Next. In "Optional Settings - Source accessibility", select the radio button for
I will make the deployment accessible from the following location and accept the default path.
Screenshot for Step
9 .Click Next to review the summary. In the "Additional configuration" section, ensure that the radio button
 for Yes, take me to the deployment's configuration screen is selected, and then click Finish.
Screenshot for Step
10 .The "Settings for analyticsRes" pane appears. Click Save.
Screenshot for Step
A confirmation message appears above the "Settings for analyticsRes" pane.
Screenshot for Step
11 .In the Change Center pane on the left, click Activate Changes.
Screenshot for Step
A second confirmation message appears above the "Settings for analyticsRes" pane.
Screenshot for Step
12 .Select Deployments in the Domain Structure pane.
Screenshot for Step
13 .Click the Control tab and then select the check box for the analyticsRes application.
 Notice that the state for analyticsRes appears asPrepared. You need to start the application.
Screenshot for Step
14 .Click Start and then select Servicing all requests.
Screenshot for Step
15 .Click Yes in the Start Application Assistant pane.
Screenshot for Step
16 .The "Summary of Deployments" pane reappears with a confirmation message. Note that
analyticsRes now shows a state of Active.
Screenshot for Step
17 .Open a browser window and enter http://<hostname>:7001/analyticsRes/test.txt 
(for example,http://localhost:7001/analyticsRes/test.txt).
Your test file should appear in the browser window.
Screenshot for Step

Deploying a Custom Skin

After exposing the analyticsRes file to WLS successfully, you can now use this directory to develop custom skins.
To customize the skin for Oracle BI EE, perform the following steps:
1 .a. Log in to Oracle BI EE. Open a browser window and in the address bar, enter
http://<hostname>:7001/analytics (for example, http://localhost:7001/analytics).
b. Enter your username and password (for example, weblogic/welcome1) and click Sign In.
The image below displays the default skin associated with Oracle BI EE:
Screenshot for Step
The image below displays the default skin associated with Eden:
Screenshot for Step
In your normal business environment, you would:
  1. Navigate to <ORACLE_HOME>/OracleBI1/bifoundation/web/app/res.
  2. Copy sk_blafp or sk_FusionFX to 
<ORACLE_INSTANCE>/bifoundation/OracleBIPresentationServicesComponent/coreappplication_obips1/analyticsRes.
Rename the copied skin file before performing any edits.
For this topic, you use the sk_Eden skin directory that you previously copied to<ORACLE_INSTANCE>
/bifoundation/OracleBIPresentationServicesComponent/
coreappplication_obips1/analyticsRes
and make modifications to cascading style sheets.
Screenshot for Step
c. Close the browser window.
2 .a. Navigate to <ORACLE_INSTANCE>/config/
OracleBIPresentationServicesComponent/coreappliation_obips1
and open instanceconfig.xml. At the bottom of the file but within the <ServerInstance>
 grouping, enter the following code:
<UI><DefaultSkin>Eden</DefaultSkin></UI>
The file should look similar to this:
Screenshot for Step
b. Save the file.
Note: This option directs Oracle BI Presentation Services (Presentation Services)
to look for the customized (Eden) skin rather than the default, Oracle BI EE skin.
3 .In the next few steps, you modify your skin and view the changes.
Navigate to <ORACLE_INSTANCE>\bifoundation\
OracleBIPresentationServicesComponent\
coreapplication_obips1\analyticsRes\sk_Eden\b_mozilla_4.
Because theinstanceconfig.xml file is now pointing to the Eden skin, the Oracle logo will be
replaced with oracle_logo.png. If you review this image file, you will notice that it is actually
 an Eden logo.
Screenshot for Step
4 .Edit the sk_Eden skin and change the banner color. Open common.css (a cascading style sheet for
common elements found within Oracle BI EE) located in<ORACLE_INSTANCE>\bifoundation\
OracleBIPresentationServicesComponent\
coreapplication_obips1\analyticsRes\sk_Eden\b_mozilla_4.
Search within the style sheet and locate the .HeaderBrandName class.
Carefully change the font color from #007700 (dark green) to #660066 (bright pink). Hint:
Use the search feature to locate the class.
Screenshot for Step
5 .With the style sheet still open, locate the .HeaderBarSeparator class and change the color from 
#005500 (green) to #660066 (bright pink).
Screenshot for Step
6 .To see the change, you must restart Presentation Services. Open a new browser window and in the
 address bar, enter http://<hostname>:7001/em (for example,http://localhost:7001/em).
The Oracle Enterprise Manager Fusion Middleware Control Login window appears.
Screenshot for Step
b. Enter your username and password (for example, weblogic/welcome1) and click Login.
7 .a. In the Farm_bifoundation_domain pane on the left, expand Business Intelligence.
Screenshot for Step
b. The Business Intelligence pane appears on the right. Select coreapplication in the Business Intelligence
 pane.
Screenshot for Step
8 .a. Click the Capacity Management and Availability tabs in the Change Center and then expand
Presentation Services.
b. Select coreapplication_obips1 and click Stop Selected.
Screenshot for Step
9 .Click Yes in the confirmation window to stop Presentation Services.
Screenshot for Step
When the second confirmation window appears, click Close.
Screenshot for Step
10 .Restart the Presentation Services. Select coreapplication_obips1 and click Start Selected.
Screenshot for Step
Note: Notice that a red downward-pointing arrow indicates that the service is stopped, whereas a
green upward-pointing arrow indicates the service is running.
11 .Click Yes in the confirmation window. Click Close when the confirmation window appears.
12 .To test your recent changes, log in to Oracle BI EE.
a. Open a browser window. If you do not immediately notice that the logo has changed from Oracle to
Eden, refresh your browser's cache.
Screenshot for Step
b. Log in as you did above—for example, enter your username and password as weblogic/
welcome1.
13 .Click Sign In. Note the changes to the dashboard.
Screenshot for Step
Note: If you do not see the changes to your dashboard, press Shift and Refresh (Refresh the cache) to clear and refresh
 your browser.
14 .Next, make changes to the Home page cascading style sheet. Open home.css located in
<ORACLE_INSTANCE>\bifoundation\
OracleBIPresentationServicesComponent\
coreapplication_obips1\analyticsRes\sk_Eden\b_mozilla_4.
At the top of the style sheet, change the BODY class. Change the color from #006600 (dark green) to
 #ffff66 (yellow).
Screenshot for Step
15 .Next, make changes to the left pane of the Home page cascading style sheet. Locate the .
BIEEHomeLeft class. Change the right border color from #BFBFBF (gray) to #FF0033 (red).
Screenshot for Step
Save your changes and log out of Oracle BI EE (close your browser window or tab).
16 .To see the changes take effect, you must restart Presentation Services just as you practiced above.
a. Within Oracle Enterprise Manager Fusion Middleware Control, you navigate to coreapplication and
select the Capacity Management and Availability tabs in the Change Center,
expandPresentation Services, select coreapplication_obips1, and click Stop Selected.
Screenshot for Step
b. Restart Presentation Services. Select coreapplication_obips1, and click Start Selected.
17 .Open a browser window and log in to Oracle BI EE Analytics once again. Your dashboard, Home page,
 appears. Review the modifications to your Home page.
Screenshot for Step
As you continue to explore the changes that you can make to the skin by using the sk_Eden 
skin directory, note that images for objects such as menu bars, can also be modified. Some of these images
 are located in<ORACLE_INSTANCE>/bifoundation/
OracleBIPresentationServicesComponent/coreappplication_obips1/
analyticsRes/b_mozilla_4/uicomponents/obips.UberBar.

Deploying a Custom Style

For this topic, you use the s_Eden style directory that you previously copied to<ORACLE_INSTANCE>/bifoundation/OracleBIPresentationServicesComponent/coreappplication_obips1/analyticsRes and make modifications to two style sheets.
You begin this topic by creating a simple analysis and adding it to My Dashboard. Adding an object to the dashboard will make viewing your style changes easier.
To begin building your dashboard and customizing the styles for My Dashboard and an analysis, perform the following steps:
1 .Open a browser window and log in to Oracle BI EE as you did above. From the Home page, click
New > Analysis.
Screenshot for Step
2 .From the Select Subject Area dialog box, select Sample Sales Lite.
Screenshot for Step
The Analysis Editor appears.
Screenshot for Step
3 .In the Subject Areas pane, expand Products and double-click Products Hierarchy. Products Hierarchy
appears in the Selected Columns pane.
Screenshot for Step
4 .Similarly, add Per Name Year from the Time folder and Revenue from the Base Facts folder.
The Selected Columns pane should look like this:
Screenshot for Step
5 .a. Click the Results tab. Your Pivot Table view appears.
Screenshot for Step
Note that the default view for hierarchical columns is pivot table.
b. Click the red X for the Title view to remove it from your analysis.
Screenshot for Step
6 .Click the Save icon (Save) and save your analysis as "My analysis" in the My Folders directory.
Screenshot for Step
7 .Next, you add the analysis to My Dashboard. On the global header, click Dashboards > My Dashboard.
Screenshot for Step
My Dashboard appears.
Screenshot for Step
8 .Click the Page Options icon (Page options icon) and select Edit Dashboard.
Screenshot for Step
The Dashboard Editor appears.
Screenshot for Step
9 .a. Expand My Folders in the Catalog pane and drag "My analysis" to the Drop Content Here canvas.
Screenshot for Step
The Dashboard Editor should look like the following image:
Screenshot for Step
b. Save your dashboard. Click the Save icon ().
10 .You are now ready to change the stylesheet for your dashboard. From the Tools menu (Tools menu icon), select
Dashboard Properties.
Screenshot for Step
The Dashboard Properties dialog box appears.
Screenshot for Step
11 .a. In the General Properties grouping, select Eden from the Style drop-down list.
Screenshot for Step
b. Click OK and then click Save and Run. The Eden-style My Dashboard appears.
Screenshot for Step
12 .a. Navigate to<ORACLE_INSTANCE>/bifoundation/
OracleBIPresentationServicesComponent/coreappplication_obips1/
analyticsRes/s_Eden/b_mozilla_4and open portalcontent.css.
b. Change the MY Dashboard outer border. Locate the .PortalBodyInteractive class and change the
 border color from #006600 (gray) to #ff00ff (pink).
Screenshot for Step
13 .a. Change the MY Dashboard inner border. Locate the .DashboardPageContentOuterDiv
class and change the border color from #daf1de (light green) to#9999ff (lavender).
Screenshot for Step
b. Save the file.
14 .Restart Presentation Services once again, open Oracle BI EE, clear the cache in the browser, and navigate
to My Dashboard to view the changes. Your dashboard should look similar to this:
Screenshot for Step
15 .a. Navigate to<ORACLE_INSTANCE>/bifoundation/
OracleBIPresentationServicesComponent/coreappplication_obips1/
analyticsRes/s_Eden/b_mozilla_4and open views.css.
b. Locate the .PTChildPivotTable class. Beneath this class, locate the classes .PCH0 through .PCH10. Change the font color from #C9CBD3 (light gray) to#ff00ff (pink) and the interior border color (for the variable headers) from #979991 (dark gray) to #ffff66 (yellow) as indicated in the image below.
Screenshot for Step
c. Save the file.
16 .Restart Presentation Services once again, open Oracle BI EE, clear the cache in the browser, and navigate to My Dashboard to view the changes. Your dashboard should look similar to this:
Screenshot for Step

You can continue to experiment with the different classes within the Eden style sheets. Each style sheet manages different aspects of the display.

Deploying Custom Messages

There may be occasions when you wish to customize messages that appear to your users. For example, if you enforce constraints in your database, you might want to provide a custom error message to display to the end user when one of those constraints is violated. Another example is the use of a write-back template. The write-back template is an XML-formatted file that contains SQL statements, which are needed to insert and update records in the write-back table and columns that you have created. You can create multiple write-back templates, customizing each one for the fields that are used in each specific analysis. You use the same analyticsResdirectory to store custom messages and write-back templates.
The Eden zip file provides a sample write-back XML file (testtemplate) and a sample message file (l_en). These are located in<ORACLE_INSTANCE>/bifoundation/OracleBIPresentationServicesComponent/coreappplication_obips1/analyticsRes/customMessages.
1 .Typically, you or your administrator would create a directory named customMessages within
analyticsRes where you store the XML templates. To create a language-dependent message file,
you must also create a folder for the required language—for example, a folder named l_en,
 representing the English language. You would then create an XML file containing the instructions for the
 application (for example, an analysis that allows write-back) or a message that you wish the end users to
see (the constraint example above). The XML code is structured similarly to the following:
<?xml version="1.0" encoding="utf-8" ?>
- <WebMessageTables xmlns:sawm="com.siebel.analytics.web/ message/v1">
- <WebMessageTable protect="true" export="true" translate="false" system="ProductMessages" table="ProductNames">
- <WebMessage name="kmsgHeaderBIBrandName">
<TEXT>Report Center</TEXT>
</WebMessage>
</WebMessageTable>
</WebMessageTables>
This sample code provides a label, namely Report Center, for the message name
 (kmsgHeaderBIBrandName) that is stored within the CompanyName.xml file.
 By using this code, you can change the brading for your sample dashboard.
a. Navigate to<ORACLE_INSTANCE>/bifoundation/
OracleBIPresentationServicesComponent/coreappplication_obips1/
analyticsRes/customMessages/l_en/messagesand open CompanyName.xml.
b. Select the text Report Center.
Screenshot for Step
2 .a. Change the text to Analytic Dashboards.
Screenshot for Step
b. Save the file.
3 .Restart Presentation Services once again, open a browser window, and navigate to the Oracle BI EE
Sign In window. You immediately notice the new branding for the page:
Screenshot for Step

Summary

Using your own skin, styles, and messages allows you to customize the Oracle BI EE environment to suit your business requirements.
In this tutorial, you should have learned how to:
  • Expose the analyticsRes directory by deploying it as a J2EE application
  • Modify an Oracle BI EE UI skin
  • Modify an Oracle BI EE UI style
  • Create a customMessages file